Storage credentials

How Tonbo Artifacts stores BYO bucket credentials client-side, and how to manage them.

Tonbo Artifacts is bring-your-own-bucket: the orchestrator never sees your S3 credentials. Your AK/SK live only on the machines that mount the workspace.

Where credentials live

Location	When it's used
`ARTIFACTS_S3_ACCESS_KEY_ID` / `_SECRET_ACCESS_KEY` env vars	Always wins; per-shell override
`~/.config/artifacts/byo-credentials` (mode `0600`)	Fallback when env vars are unset

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/artifacts/byo-credentials automatically. You'll see:

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

So a typical first-time setup looks like:

export ARTIFACTS_S3_ACCESS_KEY_ID=...
export ARTIFACTS_S3_SECRET_ACCESS_KEY=...
artifacts workspace create cases --bucket ... --endpoint ...
# (cache populated)

# New shell, no exports needed:
artifacts mount cases /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/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

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 cases /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 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.

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

Security model

The BYO credentials cache is client-side only. It's not synced anywhere; an operator with ssm:GetCommandInvocation permission on the orchestrator EC2 cannot read your customer-side cache.

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/artifacts/ is not git-tracked by default.
Rotate via artifacts storage set whenever you suspect exposure. Tonbo doesn't need to be told.