mountable.io

mountable.io CLI

mountable mounts a mountable.io filesystem, a shared POSIX filesystem for agents and teams, on any Linux machine or agent sandbox and on a Mac (macOS 26, Apple Silicon), and manages filesystems, mount tickets and sessions. It is also an MCP server.

curl -fsSL https://mountable.io/install.sh | sh   # standalone binary

npx -y mountable-cli version # or npm uvx mountable version # or PyPI

The installer checks the package against npm's sha512 and installs to ~/.local/bin. All three channels run the same CLI for Linux/macOS (x64 and arm64). With npm or PyPI, use npx -y mountable-cli or uvx mountable in place of mountable below.

The CLI is one self-contained binary: it downloads nothing at mount time and keeps the session's credentials in memory. Mounting needs FUSE (/dev/fuse) on Linux; on macOS it needs nothing else installed and no sudo (see macOS).

Authentication

• People: mountable login signs this machine in with a device flow.
• Backends and agents: set MOUNTABLE_API_KEY=mtbl_…. An API key belongs to one organisation, and the commands use it.
• Sandboxes: need no credentials, only a one-time ticket on stdin.

Commands that work inside an organisation take --org ORG_ID, then MOUNTABLE_ORG, then the only organisation the caller has; with several, they fail with org_required.

Commands

Deleting a filesystem is done in the console.

The API checks the limits' ranges: --spending-cap-cents 0 to 1,000,000,000 (cents a month), --mutations-per-minute 1 to 1,000, --byte-quota 1 byte to 100 GiB, --entry-quota 1 to 1,000,000; the quotas cannot be removed. fs create and fs update refuse an API key limited to one filesystem (key_limited_to_filesystem) and need the key's creator to be an owner or admin. fs update and every webhooks command need read-write access to the filesystem. A webhook URL must be https:// on port 443 with a public host (bad_url), a path prefix / or a directory (bad_path); a filesystem has at most 5 webhooks (webhook_limit), and a webhook whose creator lost access cannot be enabled again (access_revoked): create a new one. An API key lists and revokes only its own sessions.

The files commands use the files API without mounting, with your login or the API key: each creates a token session for itself (ro for read, list and changes, rw for write and delete), keeps its token in memory and revokes it at the end; if that fails, a note says so and the session expires within the hour. Paths are encoded per segment; a . or .. segment fails with bad_path before any request.

Output, errors and exit codes

• --json on every command writes one JSON document to stdout, with the API's field names (help --json writes {"usage": …}). Diagnostics go to stderr. Nothing ever prompts. The exception is mountable mcp, whose stdout is the MCP protocol.
• files read without --to writes the file's bytes to stdout, so it takes --json only with --to (then it prints the file's path, type, size, etag and modified_at). files list --json writes {"entries":[…],"next":…}, files changes --json {"events":[…],"cursor":…}, files delete --json {"path":…,"deleted":true}.
• mountable mount --json writes JSON lines as the mount progresses: {"event":"mounted","path":…,"filesystem_id":…,"mode":…} once the mount is usable, and {"event":"unmounted","reason":"signal|unmount|revoked|expired|error","detail":…} when it ends. Wait for mounted before using the directory.
• mountable mount keeps stderr quiet. It says mountable: mounted at DIR (without --json), and otherwise only what needs attention, as mountable: … lines: the service not answering for 30 seconds and answering again, a file it could not save, a failed certificate renewal, why a mount ended. Programs using the mount also see a failed file operation as the operation's error. --verbose adds the mount engine's full log, for debugging.
• Exit codes: 0 success; 1 an error from the API, network, mount or credentials; 2 wrong usage.
• Errors carry a stable code and a next step: on stderr, or with --json as {"error":{"code":…,"message":…,"hint":…}} on stdout. For example, unauthenticated (run mountable login or set MOUNTABLE_API_KEY), org_required (pass --org), not_found (check the ID with mountable fs list), payment_required (the hint is the console's billing link), rate_limited (wait retry_after seconds).
• precondition_failed (an --if-match or --if-none-match that did not hold) carries current_etag: the file's ETag, or null when nothing exists there; the hint names it.
• The one-time ticket appears only in the result of ticket create, and a webhook's signing secret (whsec_…) only in the result of webhooks create and webhooks rotate-secret: alone on stdout, with the webhook's ID on stderr, or in the JSON answer. API keys, login and session tokens, certificates, tickets and webhook secrets never appear in errors or logs.

Retries

• The CLI never retries on its own.
• Reads (list, get, usage, files read, files list, files changes, webhooks list) are safe to retry.
• ticket create sends an idempotency key: the one given with --idempotency-key, or a random one it prints to stderr before sending. Retry with the same key after a timeout. When the outcome is unknown (network_error or outcome_unknown), the error's idempotency_key is the key that request was sent with: retry with exactly that key. A replay returns the existing session without a ticket:
• still requested: its ticket was lost. The CLI revokes that session, creates a new one with a fresh key and reports both session IDs (replaced_session_id).
• active or later: the ticket was used. The CLI revokes nothing and fails with ticket_already_used; use a new key for another mount.
• fs create has no idempotency key, and names need not be unique. After a timeout, run fs list and look for the name before creating again.
• fs update sets the values given, so repeating it changes nothing more.
• files write and files delete with --if-match or --if-none-match fail with precondition_failed rather than undo a change made since; a repeat after an unknown outcome can fail that way because the first one succeeded, so compare current_etag with the file you wrote.
• webhooks create is not idempotent: after an unknown outcome, run webhooks list before creating again. webhooks rotate-secret issues a new secret each time; after an unknown outcome, rotate again and use the secret it prints. webhooks delete after a lost answer answers not_found. webhooks enable is safe to repeat.
• sessions revoke is idempotent.
• On HTTP 429 (rate_limited), wait retry_after seconds.

Files limits

• files read to stdout streams the file: if the download breaks off, the command fails (exit 1) and the bytes already written are incomplete. With --to FILE, FILE is replaced only once the whole file arrived.
• files write reads stdin fully before sending, so its length is known; --from FILE streams a regular file with its size.
• Each request has 60 seconds, the transfer included (files changes: 60 seconds plus --wait).

Agent workflow

The backend holds the API key; the sandbox gets only a ticket.

# Backend

export MOUNTABLE_API_KEY=mtbl_… FS_ID=$(mountable fs create agent-workspace) mountable ticket create "$FS_ID" --idempotency-key job-42 --json # → {"ticket": "mtbltk_…", …}

Sandbox, with the ticket in MOUNTABLE_TICKET

mkdir -p /mnt/work printf '%s\n' "$MOUNTABLE_TICKET" | mountable mount --ticket-stdin --json /mnt/work &

wait for {"event":"mounted",…}, use /mnt/work, then:

mountable unmount /mnt/work

Any existing, writable directory works as the mount point; mount checks it before it uses the ticket. The ticket is read from stdin, so it never appears in an argument list.

macOS

On macOS 26 (Apple Silicon) there is nothing else to install: no macFUSE, no kernel extension and no sudo. The CLI serves your filesystem to macOS's own NFS client, so it works like any other folder:

FS_ID=$(mountable fs list --json | jq -r '.[0].id')   # or the ID from `mountable fs list`

mkdir -p ~/mnt/work mountable mount "$FS_ID" ~/mnt/work # add --ro for read-only

mountable mount stays running while the folder is mounted; use the folder from another terminal or any app, and stop with Ctrl-C or mountable unmount ~/mnt/work.

Your mount is private to your account: the CLI serves it over a socket only you can open and checks your user ID on every request. Revoking the session, or letting it expire, takes the mount away. Every write the Mac sends is saved by the service before macOS hears OK, so a crash of the CLI never loses a write macOS was told succeeded. Changes made on another Mac or a Linux machine show up here in under a second, and the other way round.

Limits

• Writes are write-through, at about 7 MiB/s; each write macOS sends, up to 1 MiB, uses one unit of the filesystem's metadata rate.
• Databases, logs and files patched in place work in