Workspaces

A workspace is a filesystem you create once and mount anywhere: think of it as a network drive for your agents. Its files outlive any single machine, and any Linux host you authorize can mount it, several at the same time. Each workspace is fully isolated from your other workspaces, and its file data lives in S3: Tonbo's managed bucket by default, or a bucket you bring yourself (BYO mode).

Names and handles

Every account has a handle, a slug like acme, chosen at signup. Workspaces live under it: the workspace you call my-workspace is fully addressed as acme/my-workspace, or artifacts://acme/my-workspace in URI form. The bare name works everywhere in the CLI and resolves to your own handle; the longer forms matter when scripting or reading logs.

Create

artifacts workspace create my-workspace

That's the whole command. Tonbo Artifacts allocates a per-workspace prefix in its managed bucket, mints scoped credentials for it, and the CLI runs the in-process format step automatically.

Add a mountpoint to create and mount in one step:

artifacts workspace create my-workspace /mnt/work

Flags

Flag	Default	Notes
<name> (positional)		required
--backend	managed	managed (default) or byo
--cache-profile	interactive	interactive / benchmark / custom
--bucket		required for --backend byo; ignored for managed
--endpoint		required for --backend byo; ignored for managed
--region		byo only

The workspace name has to satisfy ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$: letters (upper or lower case), digits, hyphens, and underscores, up to 63 characters, starting with a letter or digit.

Backends

What happens during create

1. Phase 1: reserve

   CLI calls POST /workspaces on the orchestrator. The server allocates a per-workspace metadata-namespace prefix {u_X_w_Y}: and provisions a 15-minute format-scope permission. Managed mode also mints an IAM user + access key scoped to the workspace's bucket prefix and returns the AK/SK in the response. Workspace status: pending_format.

2. Phase 2: format

   The bucket is formatted in-process on your machine. For managed workspaces the CLI uses the AK/SK from the Phase 1 response; for BYO it reads ARTIFACTS_S3_* from the host environment. Either way, the volume's setting key is written to Tonbo Artifacts' metadata service under your prefix and the namespace is bootstrapped in the 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 permission.

Output on success (managed). The three phases show as progress spinners, then the final line:

Creating workspace my-workspace (provisioning storage credentials)…
Formatting workspace my-workspace…
Activating workspace my-workspace…
Workspace my-workspace is active.

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. Run with --verbose to see Resuming pending_format workspace my-workspace on the second run.

To start over cleanly:

artifacts workspace delete my-workspace --yes
artifacts workspace create my-workspace ...

List

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

IDENTIFIER                    STATUS   BACKEND  BUCKET                  CREATED
artifacts://tzu/my-workspace  active   managed  tonbo-managed-storage   2026-05-02T17:37:04Z

Show

artifacts workspace show my-workspace

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

Delete

artifacts workspace delete my-workspace --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 (drops each session's metadata-service permissions, marks revoked_at).
3. SCANs and DELs every metadata key under {u_X_w_Y}:* (your workspace's metadata).
4. Managed only: revokes the per-workspace IAM user and best-effort-deletes its prefix in tonbo-managed-storage.
5. Flips status to deleted.

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