Bring your own bucket

Every workspace keeps its file data in an S3 bucket, and the one storage decision you make is whose bucket:

• Managed (the default). Tonbo provisions storage inside its own bucket and handles credentials; nothing to set up, nothing on this page applies. Right for getting started and for teams that don't care which bucket holds the bytes.
• BYO (--backend byo). The workspace points at a bucket you own (AWS S3, Tigris, R2, MinIO, any S3-compatible). Right when data residency, audit visibility, or paying for storage on your own bill matters.

Skip the rest of this page unless you're passing --backend byo.

In BYO mode the orchestrator never sees your S3 credentials. Your AK/SK live only on the machines that mount the workspace.

For what objects appear in the bucket once Tonbo Artifacts starts writing, see What's in your bucket.

Where credentials live

Both artifacts workspace create and artifacts mount walk this chain: env first, cache file second, error last.

Auto-cache on workspace create

After a successful artifacts workspace create, the CLI saves the current ARTIFACTS_S3_* env vars to ~/.config/tonbo/artifacts/byo-credentials automatically. You'll see the resolved path:

Cached BYO credentials at /home/<user>/.config/tonbo/artifacts/byo-credentials (mode 0600);
future mounts will use them automatically.

So a typical first-time BYO setup looks like:

export ARTIFACTS_S3_ACCESS_KEY_ID=...
export ARTIFACTS_S3_SECRET_ACCESS_KEY=...
artifacts workspace create my-workspace \
    --backend byo \
    --bucket your-bucket \
    --endpoint https://fly.storage.tigris.dev
# (cache populated)

# New shell, no exports needed:
artifacts mount my-workspace /mnt/work

Manual management

# Persist current ARTIFACTS_S3_* env vars to the cache.
artifacts storage set

# Or rotate just specific fields without touching others.
artifacts storage set --access-key-id AKIA... --secret-access-key SECRET
artifacts storage set --region us-west-2

# Or set the cache from scratch via flags only (env not needed).
artifacts storage set \
    --access-key-id AKIA... \
    --secret-access-key SECRET \
    --region us-west-2

# Print the cache path + masked field values.
artifacts storage show
# Path:               /home/ubuntu/.config/tonbo/artifacts/byo-credentials
# ACCESS_KEY_ID:      AKIA***726M
# SECRET_ACCESS_KEY:  LFq0***g03S
# SESSION_TOKEN:      (unset)
# REGION:             us-west-1

# Remove the cache. Future mounts will require ARTIFACTS_S3_* env.
artifacts storage clear

Rotating credentials

When you rotate the underlying AK/SK (scheduled rotation, suspected exposure), update the cache with the new pair:

artifacts storage set --access-key-id <new-ak> --secret-access-key <new-sk>

Existing mounts on this host keep using the in-memory credentials they were issued at mount time, so they don't break mid-flight. New mounts pick up the new credentials. For a forced re-issue:

artifacts unmount /mnt/work
artifacts mount my-workspace /mnt/work

Per-shell override

Env vars always win. So if you have AK/SK cached for the default region but want one shell to hit a different region:

export ARTIFACTS_S3_REGION=eu-west-2
artifacts mount my-workspace /mnt/work

The cache's REGION field is ignored for this command; ACCESS_KEY_ID and SECRET_ACCESS_KEY still come from the cache.

Multiple buckets / workspaces

The cache is global in v0: one set of credentials across all BYO workspaces on this host. If different workspaces use different buckets with different credentials, manage that via env vars in the shell/container that's mounting each. Managed workspaces don't share the cache; each has its own server-issued credentials.

A --profile model (mirroring AWS CLI profiles) is on the v1 roadmap.

Security model

The orchestrator never holds these values, never proxies S3 reads, and never sees a request that includes them. Customer-side leaks (e.g. you commit byo-credentials to a git repo by accident, or the host gets compromised) are handled by:

• File mode 0600 (rw-------); no other local user can read it.
• The cache lives outside the source tree. ~/.config/tonbo/artifacts/ is not git-tracked by default.
• Rotate via artifacts storage set whenever you suspect exposure. Tonbo Artifacts doesn't need to be told.