Mount on Linux

For a bare Linux host, an EC2 instance, or a sandbox VM. Running in a container? See Mount in a container. On Kubernetes? See Mount in Kubernetes.

The mount surfaces a workspace as a regular Linux directory. Programs use it like a local path without knowing it's remote. Mounting is done by the CLI on the host that needs the filesystem; the TypeScript SDK manages workspaces over HTTP and can't mount.

Install the client

curl -fsSL https://artifacts.tonbo.dev/install.sh | bash

See Install for offline, pinned-version, or non-root install options.

Authorize

artifacts login
# Browser opens; sign in with GitHub or Google.
# Credentials cache at ~/.config/tonbo/artifacts/credentials.json.

// Generate an API key at user.tonbo.dev (Profile → API keys), then:
export TONBO_API_KEY=<your key>

// The SDK reads it automatically:
const artifacts = new Artifacts();
// or: new Artifacts({ apiKey: '<your key>' })

Mount a workspace

mkdir -p /mnt/work
artifacts mount my-workspace /mnt/work

What you should see: the CLI prints Mounting /mnt/work ... then the prompt returns. The FUSE-serving process detaches into the background; your shell, container entrypoint, or agent runtime can keep going.

Verify the mount:

mount | grep /mnt/work
# Tonbo:my-workspace on /mnt/work type fuse.juicefs (rw,...)

ls /mnt/work shows your data plus four system files: .accesslog, .config, .stats, .trash. .stats is a Prometheus-format counters file you can cat or scrape for cache hit rates and request counts.

Unmount

artifacts unmount /mnt/work

Fallbacks if the supervisor process is gone:

fusermount3 -u /mnt/work
# or
pgrep -af "artifacts mount my-workspace /mnt/work"
kill -TERM <supervisor-pid>

All paths trigger the same graceful unmount: in-flight operations drain, the kernel mount goes away within ~0.5 seconds.

That's the short path. Everything below is opt-in.

Advanced

Read-only mode

artifacts mount my-workspace /mnt/work --read-only

The kernel mount is registered with ro; write syscalls return EROFS immediately. The mount session itself is also signed read-only at issue time: for managed workspaces the underlying S3 credentials deny PutObject / DeleteObject; for BYO workspaces the metadata service rejects write operations server-side. A read-only mount can't be escalated to read-write by bypassing the kernel ro flag.

Cache profile

artifacts mount my-workspace /mnt/work --cache-profile benchmark

interactive (default), benchmark, and custom are supported. benchmark allocates more buffer and prefetch, which suits a find-and-read-heavy agent workload. custom accepts additional flags; see artifacts mount --help.

Daemon vs foreground

The default is daemon (the shell returns within a second). Pass --foreground (-f) to keep FUSE attached:

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

Foreground is useful for ops or debug when you want live mount logs. systemd units use it so the unit can supervise the process.

Mount automatically on startup

There's no mount.tonbo fstab helper. To bring a mount up at boot, supervise the foreground process. Two common options.

Via nohup. For a quick boot-script entry that survives the shell exiting:

nohup artifacts mount my-workspace /mnt/work --foreground \
  >> ~/.cache/tonbo/artifacts/mount.log 2>&1 &

Via systemd. For finer control over lifecycle (logging, restart policy, unit dependencies):

[Unit]
Description=Tonbo Artifacts mount: my-workspace at /mnt/work
After=network-online.target
Requires=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/artifacts mount my-workspace /mnt/work --foreground
ExecStop=/usr/local/bin/artifacts unmount /mnt/work
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now artifacts-my-workspace.service

For runtime templates managed by a cloud platform, inject the signed mount ticket as a file and put the mount command directly in your boot script:

artifacts mount my-workspace /mnt/work \
  --ticket-file /run/tonbo/artifacts/mount-ticket.json

Mount session lifetime

Each mount provisions a fresh permission scope on the metadata service. For a CLI-based mount authorized by artifacts login, the session is long-lived and revoked when you log out or an admin revokes it.

Mounts never auto-expire mid-flight. Cleanup is always explicit via artifacts unmount.

For platforms issuing short-lived mount tickets to customer runtimes, the lifecycle is different (TTL-bounded, per-session revoke). See Temporary mount credentials.

Command reference

See CLI reference for the full subcommand listing. The flags relevant to mount and unmount: