mountable.io

Mountable CLI

mountable 可在任意 Linux 机器或 Agent 沙箱，以及 Mac（macOS 26，Apple Silicon）上挂载 Mountable 文件系统。它是一个供 Agent 和团队使用的共享 POSIX 文件系统，也可管理文件系统、挂载票据和会话。此外，它还是一个 MCP 服务。

npx -y mountable-cli login                          # npm
uvx mountable login                                 # PyPI
curl -fsSL https://mountable.io/install.sh | sh     # standalone binary

CLI 是一个独立的二进制文件：挂载时不会下载任何内容，并会将会话凭据保存在内存中。Linux 上挂载需要 FUSE（/dev/fuse）；macOS 上无需安装其他内容，也无需使用 sudo（参见 macOS）。

身份验证

• 个人用户： mountable login 使用设备授权流程登录此机器。
• 后端和 Agent： 设置 MOUNTABLE_API_KEY=mtbl_…。API 密钥属于一个组织，命令会使用该密钥。
• 沙箱： 无需凭据，只需通过标准输入传入一次性票据。

在组织内执行的命令会依次使用 --org ORG_ID、MOUNTABLE_ORG，然后使用调用者所属的唯一组织；如果调用者属于多个组织，则会报错 org_required。

命令

命令	功能
mountable orgs list	列出调用者所属的组织
mountable fs list	列出文件系统
mountable fs create NAME	创建文件系统；输出其 ID
mountable fs usage FS_ID	查看已存储的字节数和文件数与配额的对比，以及 30 天流量
mountable ticket create FS_ID [--ro] [--idempotency-key KEY] [--max-duration D]	为沙箱创建一次性挂载票据；会话持续时间为 D（例如 12h 或 720h；默认 12 小时，且不超过 API 密钥或登录的有效期）
mountable sessions list FS_ID	列出活动的挂载会话
mountable sessions revoke SESSION_ID	撤销会话；其挂载将停止
mountable mount [--ro] FS_ID DIR	使用你的登录凭据挂载
mountable mount --ticket-stdin DIR	使用从标准输入读取的票据挂载
mountable unmount DIR	卸载；在 Linux 上，会提交待处理的写入
mountable mcp	通过 stdio 提供 MCP 服务
mountable login、logout、version、licenses

删除文件系统需在控制台中操作。

输出、错误和退出代码

• 每个命令都可使用 --json 将一个 JSON 文档写入标准输出，字段名与 API 一致（help --json 会输出 {"usage": …}）。诊断信息会输出到标准错误。程序不会提示输入任何内容。例外是 mountable mcp，其标准输出用于 MCP 协议。
• mountable mount --json 会在挂载过程中逐行输出 JSON：挂载可用时输出 {"event":"mounted","path":…,"filesystem_id":…,"mode":…}，挂载结束时输出 {"event":"unmounted","reason":"signal|unmount|revoked|expired|error","detail":…}。请先等待 mounted，再使用该目录。
• 退出代码：0 表示成功；1 表示 API、网络、挂载或凭据错误；2 表示用法错误。
• 错误带有稳定的错误代码和后续操作建议：输出到标准错误，或在使用 --json 时以 {"error":{"code":…,"message":…,"hint":…}} 的形式输出到标准输出。例如，unauthenticated（运行 mountable login 或设置 MOUNTABLE_API_KEY）、org_required（传入 --org）、not_found（使用 mountable fs list 检查 ID）、payment_required（提示中包含控制台的账单链接）、rate_limited（等待 retry_after 秒）。
• 一次性票据只会出现在 ticket create 的结果中。API 密钥、登录令牌、证书和票据不会出现在错误信息或日志中。

重试

• 读取操作（list、usage）可以安全重试。
• ticket create 会发送幂等键：要么是通过 --idempotency-key 指定的键，要么是发送前打印到 stderr 的随机键。 超时后使用同一个键重试。如果结果未知 （network_error 或 outcome_unknown），错误中的 idempotency_key 就是 该请求发送时使用的键：使用完全相同的键重试。重放请求会返回现有 会话，但不返回票据：
  • 状态仍为 requested：票据已丢失。CLI 会撤销该会话， 使用新的键创建会话，并报告两个会话 ID （replaced_session_id）。
  • 状态为 active 或之后的状态：票据已使用。CLI 不会撤销任何内容，并会以 ticket_already_used 失败；要挂载另一个文件系统，请使用新键。
• fs create 没有幂等键，名称也不必唯一。超时后，运行 fs list，检查名称是否已存在，再决定是否重新创建。
• sessions revoke 是幂等操作。
• HTTP 429（rate_limited）时，等待 retry_after 秒。

Agent 工作流

后端持有 API 密钥；沙盒只会获取票据。

# 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

任何已有的可写目录都可以作为挂载点；mount 会在使用票据前检查该目录。 票据从 stdin 读取，因此不会出现在参数列表中。

macOS

在 macOS 26（Apple Silicon）上，无需安装其他内容：不需要 macFUSE、 内核扩展，也不需要 sudo。CLI 会通过 macOS 自带的 NFS 客户端提供文件系统，因此使用方式与其他文件夹一样：

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 会在文件夹保持挂载期间持续运行；可在其他终端或任意应用中使用该文件夹，并通过 Ctrl-C 或 mountable unmount ~/mnt/work 停止。

挂载仅对你的账户可见：CLI 通过只有你能打开的套接字提供挂载，并在每次请求时检查你的用户 ID。撤销会话或让会话过期都会移除挂载。Mac 发送的每次写入都会先由服务保存，然后 macOS 才会收到 OK，因此即使 CLI 崩溃，macOS 已确认成功的写入也不会丢失。其他机器上的更改会在片刻后显示。

限制

• 写入采用直写方式，速度约为 7 MiB/s；macOS 发送的每次写入（最大 1 MiB）都会占用文件系统元数据速率的一个单位。
• 文件顺序写入量最多约为 9.76 GiB；如果通过多次小型追加和 fsync 周期写入，则上限会更低。
• 对单个文件，最多可进行约 9,999 次更改已有字节或追加小片段的写入；之后对该文件的写入会失败，并提示“file too large”。请将数据库（SQLite 等）和其他原地改写的文件保存在本地磁盘上，或在本地与挂载目录间复制。编辑器会通过写入新文件（或先截断文件）来保存，因此不受影响。
• 写入失败会按文件报告一次，由任意程序对该文件执行的第一次 write、fsync 或 close 操作报告。
• 通过 mmap 进行的写入可能会失败而不报错。
• 其他挂载之间按单次写入协调，而不是在整个文件打开期间协调。
• 卸载前请完成写入（关闭文件或对文件执行 fsync）：强制卸载正在忙碌的挂载可能会丢弃仍在进行中的写入。
• macOS 会在大多数文件旁创建 ._ 文件；要避免将其纳入 git，请运行 mkdir -p ~/.config/git && echo '._*' >> ~/.config/git/ignore（如果 git config --global core.excludesFile 指定了文件，也可以将 ._* 追加到该文件中）。
• 不支持 Spotlight 索引；锁（flock、fcntl）仅在本地挂载中生效。

技能

技能会向编码 Agent 讲解此工作流、错误代码和重试规则：

npx skills add writeitai/mountable

文件位于 skills/mountable/SKILL.md。

MCP 服务

mountable mcp 通过 stdio 提供 list_organizations、list_filesystems、 create_filesystem、filesystem_usage、create_mount_ticket、 list_mount_sessions 和 revoke_mount_session 工具 （create_mount_ticket 接受可选的 max_duration_seconds）。它的身份验证方式与 CLI 相同。结果为 API 返回的 JSON；错误会返回代码和提示。挂载操作仍在沙箱中作为进程运行： create_mount_ticket 会返回票据以及使用该票据进行挂载的命令。

通过环境变量向服务提供 MOUNTABLE_API_KEY：从 MCP 客户端启动时所在的环境继承，或在客户端的 MCP 配置中通过 env 设置。切勿将密钥作为命令行参数传递，否则密钥会出现在进程列表和 Shell 历史记录中。

Claude Code（项目中的 .mcp.json；${MOUNTABLE_API_KEY} 会从 Claude Code 运行时所在的环境中读取，因此密钥不会写入文件）：

{
  "mcpServers": {
    "mountable": {
      "command": "npx",
      "args": ["-y", "mountable-cli", "mcp"],
      "env": { "MOUNTABLE_API_KEY": "${MOUNTABLE_API_KEY}" }
    }
  }
}

Claude Desktop（claude_desktop_config.json）和 Cursor （~/.cursor/mcp.json）；请妥善保管这些文件，因为其中包含密钥：

{
  "mcpServers": {
    "mountable": {
      "command": "npx",
      "args": ["-y", "mountable-cli", "mcp"],
      "env": { "MOUNTABLE_API_KEY": "mtbl_…" }
    }
  }
}

SDK

无需挂载即可读写文件的后端可通过 SDK 使用文件 API；SDK 会使用 API 密钥创建并刷新自己的短期令牌会话。

两者均以 mountable-sdk 发布：Python 版要求 Python 3.10+，发布于 PyPI；TypeScript 版发布于 npm（支持 Node 18+、Bun 或 Deno）：

pip install mountable-sdk      # import mountable_sdk
npm install mountable-sdk      # import { Mountable } from "mountable-sdk"

from mountable_sdk import Mountable

fs = Mountable().filesystem("fs_…", mode="rw")   # MOUNTABLE_API_KEY
info = fs.write("notes/a.md", "hello")
fs.write("notes/a.md", "hello again", if_match=info.etag)
print(fs.read("notes/a.md").data)

它们分别位于 sdk/python 和 sdk/typescript，行为一致（共用的测试案例见 sdk/contract.md），并会随标签 sdk-vX.Y.Z 一同发布。

LLM 提供商入门示例

examples/llm-providers 提供仅依赖标准库的工具，适用于 OpenAI Agents SDK 和 Responses API、Anthropic Messages API 和 Claude Code、Gemini ADK 以及 xAI Grok。编排器持有 MOUNTABLE_API_KEY，沙箱则通过 stdin 接收一次性票据。指南见 https://mountable.io/docs/integrations。

展示示例

examples/showcase 运行两个演示：一个规划器沙箱和一个编码器沙箱共用同一目录，随后进行只读的笔记本电脑挂载；另一个演示撤销终止开关。默认运行 python3 examples/showcase/relay.py --dry-run 会打印操作序列而不调用 API。相同的演示也可在 https://mountable.io/showcase 上体验，且不会创建文件系统。

Notebook 入门示例

examples/notebooks 提供适用于 Colab、 Kaggle、Deepnote 和 Hugging Face Spaces 的 Jupyter Notebook，以及一个 Marimo Notebook。它们使用 mountable-sdk 将数据集、特征缓存和检查点保存在 Mountable 文件夹中，因此内核重启后文件仍会保留。

多 Agent 编码框架

examples/research-showcases/multi-agent-harness 会让规划器、编码器和验证器在同一共享文件夹中运行。经过签名的文件变更 Webhook 会触发只读验证器挂载。默认离线运行 harness.py，或使用 --live 创建带有月度支出上限和速率限制的文件系统。

许可证

mountable licenses 会打印编译进 CLI 的第三方代码所使用的许可证和声明；每个软件包和发行版压缩包中也都附带 THIRD_PARTY_NOTICES。

文档：https://mountable.io/docs。

开发

go test ./...
go run ./tools/notices > THIRD_PARTY_NOTICES   # after changing dependencies
packaging/build.sh 0.0.0    # binaries, release archives, npm tarball and wheel in dist/

# SDKs
(cd sdk/python && uv run ruff format --check . && uv run ruff check . && uv run pyright && uv run pytest)
(cd sdk/typescript && npm ci && npm run typecheck && npm test && npm run build)

推送标签 vX.Y.Z（CLI）或 sdk-vX.Y.Z（SDK）即可发布；详情请见 packaging/README.md。 Mountable 服务本身由 WriteIt.ai s.r.o. 运营；此代码库仅包含开源客户端。

许可证

Apache-2.0。