mountable.io

Mountable CLI

mountable は、エージェントやチーム向けの共有 POSIX ファイルシステムである Mountable ファイルシステムを、任意の Linux マシンやエージェントのサンドボックス、および Mac（macOS 26、Apple Silicon）にマウントし、ファイルシステム、マウントチケット、セッションを管理します。また、MCP サーバーでもあります。

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

CLI は自己完結型のバイナリ 1 つで構成されています。マウント時に何もダウンロードせず、セッションの認証情報をメモリ内に保持します。マウントには Linux では FUSE（/dev/fuse）が必要です。macOS では、ほかにインストールするものも sudo も必要ありません（macOS を参照）。

認証

• ユーザー： mountable login を実行すると、デバイスフローでこのマシンにサインインします。
• バックエンドとエージェント： MOUNTABLE_API_KEY=mtbl_… を設定します。API キーは 1 つの組織に属し、コマンドはそのキーを使用します。
• サンドボックス： 認証情報は不要で、標準入力から読み込む 1 回限りのチケットのみ必要です。

組織内で実行するコマンドでは、--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]	サンドボックス用の 1 回限りのマウントチケット。セッションは 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	標準入出力を使う MCP サーバー
mountable login, logout, version, licenses

ファイルシステムの削除はコンソールで行います。

出力、エラー、終了コード

• すべてのコマンドで --json を指定すると、API のフィールド名を使った JSON ドキュメントを 1 つ標準出力に書き込みます（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、API、ネットワーク、マウント、または認証情報のエラー時は 1、使い方が誤っている場合は 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 秒待ってください）です。
• 1 回限りのチケットは ticket create の結果にのみ表示されます。API キー、ログイントークン、証明書、チケットがエラーやログに表示されることはありません。

再試行

• 読み取り（list、usage）は安全に再試行できます。
• ticket create は冪等性キーを送信します。--idempotency-key で指定したキー、または送信前に標準エラーへ出力されるランダムなキーです。タイムアウト後は、同じキーで再試行してください。結果が不明な場合（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 秒待ってください。

エージェントのワークフロー

バックエンドは 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 はチケットを使用する前にディレクトリを確認します。チケットは標準入力から読み取られるため、引数リストには表示されません。

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 までの各書き込みは、ファイルシステムのメタデータレートを 1 単位消費します。
• ファイルは、順次書き込みの場合で約 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）はマウント内でのみ有効です。

スキル

スキルは、このワークフロー、エラーコード、再試行ルールをコーディングエージェントに教えます。

npx skills add writeitai/mountable

スキルは skills/mountable/SKILL.md にあります。

MCP サーバー

mountable mcp は、list_organizations、 list_filesystems、create_filesystem、filesystem_usage、 create_mount_ticket、list_mount_sessions、revoke_mount_session の各ツールを stdio 経由で提供します（create_mount_ticket には省略可能な max_duration_seconds を指定できます）。認証方法は CLI と同じです。結果は API の JSON 形式で、エラー時にはコードとヒントを返します。マウントは引き続きサンドボックス内のプロセスとして実行されます。 create_mount_ticket は、チケットと、そのチケットを使ってマウントするコマンドを返します。

MOUNTABLE_API_KEY は環境経由でサーバーに渡してください。MCP クライアントの起動元の環境から継承させるか、クライアントの MCP 設定の env に設定します。キーをコマンドライン引数として渡さないでください。プロセス一覧やシェルの履歴に残ることになります。

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 経由で Files API を使用します。SDK は API キーから独自の短期トークンセッションを作成し、更新します。

どちらも mountable-sdk として公開されています。Python 版は PyPI で提供され、Python 3.10 以降に対応します。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 は 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 を保持し、サンドボックスには一度限りのチケットを標準入力で渡します。ガイドは https://mountable.io/docs/integrations をご覧ください。

ショーケースデモ

examples/showcase では、2 つのデモを実行できます。1 つ目は、同じディレクトリを共有するプランナーのサンドボックスとコーダーのサンドボックス、続いて読み取り専用のノート PC マウントを使用します。もう 1 つは、アクセス失効用のキルスイッチです。python3 examples/showcase/relay.py --dry-run を実行すると、API を呼び出さずに一連の処理を表示します。同じデモは https://mountable.io/showcase でもご覧いただけます。ファイルシステムは作成されません。

ノートブックのスターター

examples/notebooks には、Colab、Kaggle、Deepnote、Hugging Face Spaces 用の Jupyter ノートブックと、Marimo ノートブックがあります。データセット、特徴量キャッシュ、チェックポイントは mountable-sdk を使って Mountable フォルダーに保存されるため、カーネルを再起動してもファイルは保持されます。

マルチエージェントのコーディングハーネス

examples/research-showcases/multi-agent-harness では、プランナー、コーダー、検証役が 1 つの共有フォルダーで動作します。署名付きのファイル変更ウェブフックをトリガーとして、読み取り専用の検証役マウントを作成します。デフォルトでは 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。