Workspaces

A workspace is the unit of mountability. One workspace ↔ one S3 bucket-prefix ↔ one isolated metadata namespace in Tonbo's Redis. You mount it, write to it, share it across machines, eventually delete it. The metadata layout is per-workspace; the chunks live in your bucket.

Create

export ARTIFACTS_S3_ACCESS_KEY_ID=<your-bucket-access-key>
export ARTIFACTS_S3_SECRET_ACCESS_KEY=<your-bucket-secret-key>
export ARTIFACTS_S3_REGION=auto

artifacts workspace create cases \
    --bucket panta-cases \
    --endpoint https://fly.storage.tigris.dev

Flag	Required	Default / fallback
<name> (positional)	yes	—
--bucket	yes	falls back to ARTIFACTS_S3_BUCKET env
--endpoint	yes	falls back to ARTIFACTS_S3_ENDPOINT env
--region	no	ARTIFACTS_S3_REGION, then AWS_REGION, then AWS_DEFAULT_REGION
--prefix	no	empty (workspace lives at bucket root); falls back to ARTIFACTS_S3_PREFIX
--backend	no	byo (only mode in v0; managed buckets are v1)
--cache-profile	no	interactive

The workspace name has to satisfy ^[a-z][a-z0-9-]{0,38}[a-z0-9]$: lowercase letters, digits, and hyphens, not starting or ending with a hyphen.

What happens during create

1. Phase 1: reserve

   CLI calls POST /workspaces on the orchestrator. The server allocates a per-workspace Redis hashtag prefix {u_X_w_Y}: and mints a 15-minute format-scope ACL. Workspace status: pending_format. Your S3 credentials are not sent.

2. Phase 2: format

   juicefs format runs in-process on your machine with the format ACL token, writes the volume's setting key to Redis under your hashtag, and bootstraps the namespace in your bucket.

3. Phase 3: confirm

   CLI calls POST /workspaces/<handle>/<name>/format-completed. The orchestrator verifies the setting key exists, flips status to active, revokes the format ACL.

Output on success:

Phase 1: reserving artifacts://<handle>/cases on the orchestrator
Workspace artifacts://<handle>/cases reserved (status=pending_format, key prefix={u_…_w_…}:)
Phase 2: running juicefs format with local BYO credentials
Phase 3: confirming format completion with the orchestrator
Workspace artifacts://<handle>/cases is active.
Cached BYO credentials at /home/<user>/.config/artifacts/byo-credentials (mode 0600);
future mounts will use them automatically.

If create fails mid-phase

Re-run the same command. Each phase is idempotent: the orchestrator returns the same hashtag prefix on resume, the format token is re-issued, and the namespace bootstrap is re-pointed at the existing keys. You'll see Resuming pending_format workspace artifacts://<handle>/<name> in the second run.

To start over cleanly:

artifacts workspace delete cases --yes
artifacts workspace create cases ...

List

artifacts workspace list
# Or machine-readable:
artifacts --format json workspace list | jq .

IDENTIFIER             STATUS   BACKEND  BUCKET                   CREATED
artifacts://tzu/cases  active   byo      panta-cases              2026-05-02T17:37:04Z

Show

artifacts workspace show cases

Includes the storage block (bucket / endpoint / region / prefix), the status, the volume_name (server-derived JuiceFS volume name), and the key_prefix for debugging.

Delete

artifacts workspace delete cases --yes

Returns 202 Accepted. The orchestrator:

1. Acquires a FOR UPDATE lock on the workspace row, flips status to deleting.
2. Revokes any active mount sessions (DELUSER each ms-<id> ACL, marks revoked_at).
3. SCANs and DELs every Redis key under {u_X_w_Y}:* (your workspace's metadata).
4. Flips status to deleted.

A deleted workspace name is reusable; the next workspace create cases provisions a fresh row with a fresh hashtag.