> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックスランタイム

> ユーザーごとに永続化されるサンドボックス。コード実行とツール呼び出しの実行場所。

# サンドボックスランタイム

すべてのユーザーには、**分離され永続化する**サンドボックス環境が割り当てられ、再起動後も状態が残ります。

## 永続化

一時的なサンドボックスと異なり、Myrm のサンドボックスは次を保持します。

* インストール済みのパッケージとツール
* ファイルシステムの状態
* 環境設定
* 実行中のプロセス（自動再起動）

### クラッシュ整合性の永続化（アトミック書き込み）

永続化は「クラッシュ後もデータが完全なまま」でなければ意味がありません。Myrm は重要な状態ファイルすべてに、統一された **クラッシュ整合性アトミック書き込みプリミティブ**（`infra/atomic_write`）を使います: 一時ファイルへ書き出し → `fsync` → アトミックな `rename` → 親ディレクトリを `fsync`。したがって対象ファイルは**常に「完全な旧版」か「完全な新版」であり、途中で半端な欠片が残ることは決してありません** — プロセスクラッシュ・電源断・サンドボックス再起動がどの瞬間に起きても同じです。

この保証は最も重要な永続化点を覆います。

* **コンテキストスナップショット** — 圧縮サイクルの前に書き込まれるセッションスナップショットは再起動後も完全に残り、長時間セッションは文脈を復元できます
* **Teammate メールボックス JSONL** — 子 Agent 間のメッセージ履歴は途中で破損せず、複数 Agent の協業状態が整合します
* **スキルインスタンスと状態ファイル** — スキル設定と実行時状態はアトミックに往復します
* **暗号化鍵** — `0o600` 権限でアトミックに書き込まれ、鍵が途中で切り詰められること（＝全履歴データが復号不能になる）も、露出することもありません
* **使用量台帳** — 追記書き込み + ロック保護により、同時追記が台帳を破損させることはありません

競合するツールは通常、既存ファイルを切り詰める直接上書き書き込み（`open(path, "w")`）を使うため、書き込み途中のクラッシュで解析不能な破損ファイルが残り、恒久的なデータ損失になります。Myrm のアトミック書き込みは「クラッシュ ＝ データ損失」をありえないものにします。

## 分離

各サンドボックスは独立した環境で実行されます。

* 独立したファイルシステムボリューム
* ネットワーク名前空間による分離
* リソース制限（CPU・メモリ・ディスク）
* 実行時に強制される安全ポリシー
* **UI 相互作用ブラックリスト**: バックグラウンドの子 Agent のサンドボックスは UI インターフェース（`interactive_feedback`、`send_message`）を遮蔽し、バックグラウンド処理がフロントエンドユーザーをポップアップで妨害できないことを物理レベルで保証します
* **段階別プロセス（PID）上限**: サンドボックスのプロセス上限は課金プランに対応し、Free 200 / PRO 512 / MAX 1024 — プラン設定が自動配布されコンテナ作成時に検証されます。プランとコンテナのリソースは常に一致します。プロセス使用量は cgroup 上限（`pids.current` / `pids.max`）で 2 段階しきい値監視（70% で警告 / 90% で告警）され、ブラウザプロセスの帰属と上位メモリプロセスの表示も含めて Doctor パネルから直接確認できます。「プロセス表が埋まって Agent が原因不明で固まる」この種の無反応障害は起きません。

### ネイティブ OS レベルのサンドボックス（Docker 不要）

ローカルおよびデスクトップのデプロイでは、Myrm は主要プラットフォームすべてで**ネイティブ OS レベルのプロセス分離**を提供します。

| プラットフォーム | 分離メカニズム | 仕組み |
| - | - | - |
| macOS | Seatbelt（sandbox-exec） | SBPL ポリシーを動的生成。ゼロトラストマウントで、明示的に許可したパスのみを許可 |
| Linux | bubblewrap（bwrap） | カーネル名前空間分離 + PID / ネットワーク unshare + セッション分離 |
| Windows | AppContainer | Win32 ネイティブセキュリティトークン + パス単位の ACL 権限制御 |

サンドボックス Provider は起動時に自動検出され、設定は不要です。優先 Provider が利用できない場合も、システムはグレースフルに縮退し明確な警告を出します。

**Docker 方式に対する優位点**:

* Docker Desktop のインストールが不要（Windows / macOS の導入障壁を下げる）
* サブミリ秒の起動（コンテナイメージの pull が不要）
* OS ネイティブのセキュリティプリミティブを使う（カーネル強制で、ユーザー空間simulationではない）
* Local WebUI・Tauri デスクトップ・クラウドホストの 3 形態で挙動が一致

### 明示的ライフサイクルと漏れ防止のリソース解放

長時間動く Agent の複雑なワークフローや複数ターンのセッションでは、バックグラウンド常駐プロセスとファイルハンドルFusion の決定的な解放が重要です。Myrm は**二層の明示的 async 解放プロトコル**を実装しています。

1. **`CodeExecutor` ライフサイクル契約**: 抽象基底クラスとミドルウェアの連鎖上で `async def close(self) -> None:` と `__aenter__` / `__aexit__` を async コンテキストマネージャとして規格化。
2. **プロセスツリーの一斉終了**: `LocalExecutor.close()` は常駐 bash 子プロセスツリーへ `SIGTERM` / `SIGKILL` を冪等に送り、I/O パイプを安全にクローズ。
3. **OS レベル ACL セキュリティ記述子の取り消し**: `SandboxProvider.cleanup()` がプラットフォームのセキュリティトークン（Windows AppContainer の SID 権限など）を自動で取り消し、ハンドルとセキュリティ記述子の蓄積漏れを防止。
4. **セッションキャッシュの自動アンバインド**: `run_lifecycle` の `finally` フックでキャッシュされた実行インスタンスをスタックから出し、async にクローズ。

## コード実行

Agent はサンドボックス内で直接コードを実行できます。

* Python 3.14、Node.js 20、Bun 1.3、Shell スクリプト
* uv/pip、npm、apt によるパッケージ導入
* ファイル読み書き
* ネットワークアクセス（設定可）

### 同梱のデータサイエンスツールスタック（70+ パッケージ）

サンドボックスはすぐに使えます。インストールを待つ必要はありません。

| カテゴリ | パッケージ |
| - | - |
| **データサイエンス** | pandas、numpy、scipy、scikit-learn、statsmodels |
| **可視化** | matplotlib（CJK フォント対応済み）、seaborn |
| **Excel** | openpyxl、xlsxwriter、xlrd |
| **ドキュメント** | python-docx、python-pptx |
| **PDF** | pypdf、pdfplumber、reportlab、pdf2image、pypdfium2 |
| **画像** | Pillow |
| **ビッグデータ** | pyarrow（Parquet/Arrow） |
| **数学** | sympy、mpmath |
| **ユーティリティ** | httpx、orjson、tqdm、pytz |

### Jupyter 級のインラインチャート

matplotlib が生成したチャートは自動的に取得され、会話の中にインライン表示されます。ファイルを手動でダウンロードする必要はありません。CJK フォントはそのまま使え、ビルド時に自動検証されます。

### スマートなエラー回復

パッケージが欠けているとき、Agent は実行可能な診断ヒント（正確なインストールコマンドの提案）を受け取ります。試しugaしループが不要になります。

**自動言語ルーティング**: 組み込みの単一実行ツールが Python コマンドか Shell コマンドかを自動判別します。`python3 -c` で手動で包む必要も、ツールを使い分ける必要もありません。構文エラーは実行前にブロックされ、明確なヒントが出るため、無効な再試行を減らし token を節約できます。

**競合との比較**: OpenClaw の `exec` は Shell のみ。Hermes は Shell と Python を別ツールに分割。Myrm は GUI ユーザーに対して単純な入口を一つ保ち、下層で自動ルーティングします。

## アップロードファイルの直通

メッセージに添付したファイル（ドラッグ&ドロップまたはクリックアップロード）は、サンドボックスのワークスペースでそのまま使えます。

* **小ファイル**（100 KB 未満）: 内容が直接 LLM コンテキストに注入され、即座に分析
* **大ファイル**（100 KB 以上）: 自動的にワークスペースの `_uploaded/` ディレクトリへコピーされ、Agent は `file_read_tool` で読むか、コードで処理できます（例 `pandas.read_csv()`）

つまり 5 MB の CSV をアップロードして「Python で四半期トレンドを分析して」と頼めば、Agent はファイル全体に直接アクセスできます。手動での転送もパス設定も不要です。

## ワークスペースサンドボックス（Git Worktree 分離）

任意のチャットセッションで **サンドボックスモード** を有効にすると、プロジェクト単位の分離が得られます。

* **ワンクリック切替**: メッセージ入力欄の「サンドボックス」ボタンを押すだけ
* **Git worktree**: 分離ブランチを作成し、すべての変更を一時ブランチ内に閉じ込めます
* **マージか破棄**: 完了後に良い変更を本ブランチへマージするか、実験全体を破棄するかを選べます
* **ゼロリスク**: あなたが明示的にマージするまで、メインコードベースは変更されません

適用シーン:

* リファクタ実験（「リスクを賭けずにこの案を試す」）
* Agent に複数の案を並行探索させる
* コードレビューで変更を検証してから受け入れる

**並行子 Agent のワークスペース分離**: 複数 Agent のタスクを実行すると、各子 Agent は独立した copy-on-write（COW）ワークスペース clone（ISOLATED\_COPY 戦略）と 1 GiB の安全ガードを受け取ります。並行実行の後は直列順に安全にマージされ、ファイル衝突ゼロ・データ損失ゼロです。

7 種のオーケストレーションモード（Spawn / Chain / Batch / DAG / Verified / Swarm Fission / Alternatives）、カスケードキャンセル、委譲予算により、並列実行の安全性とコスト可控を担保します。三層のサンドボックス（OS namespace / Docker コンテナ / ワークスペース COW）は Docker 依存なしでミリ秒起動。**1,101 項目のテストがサブエージェントとサンドボックススタック全体を検証しています。**

Claude Code の CLI 専用 `--worktree` オプションが提供されるのに対し、Myrm のワークスペースサンドボックスは GUI ボタンでワンクリック切替でき、セッション途中でも有効・無効を切り替えられ、マージ／破棄ワークフローと事前承認の連携まで備えています。

## Git と PR の納品

サンドボックスにより Git ワークフローは**すぐに使えます**。真新しい環境でもそのまま動きます。

* **ホスト限定 push 資格情報**: `GITHUB_TOKEN` が存在し push 先が HTTPS の `github.com` リモートであるとき、Myrm はインライン資格情報ヘルパーを注入します — ただしサンドボックスに既存資格情報がない場合のみ。このヘルパーは**ホスト限定**で、`github.com` / `www.github.com` にのみ応答し、token が第三者 Git サーバー（例: 自前の GitLab リモートや素の HTTPS URL）に渡ることはありません。token は環境変数参照で渡され、コマンドにインラインで埋め込まれることはありません。
* **自動コミット identity**: サンドボックスに `git config user.name/user.email` のグローバル設定がなければ、Myrm は接続済み GitHub アカウントから解決します（`login@users.noreply.github.com`、`TMPDIR` キャッシュ + 5 秒タイムアウト + ローカルフォールバック）。`git commit` は一発で成功し、「Please tell me who you are」で止まることはありません。
* **ワンクリック PR 納品**: **設定 > 連携 > GitHub** の GitHub 連携と組み合わせると、webhook URL にワンクリックコピー付き表示が出て、設定した Webhook Secret が GitHub 側と一致している必要があります（ペイロードは `X-Hub-Signature-256` で検証）。PR オープン / issue / push イベントは完全なコンテキスト付きでチャットに還流します。

結果: Agent に「GitHub に push して PR を作って」と伝えるだけで、資格情報・identity・イベントがすべて揃っており、手動の Git 設定が一切不要です。

## 休止と復帰

サンドボックスはアイドルになると自動的に休眠し、リクエストが来れば秒単位で復帰し、ユーザーは何も感じません。

* **スマートなアイドル検出**: バックグラウンドが 60 秒ごとにアクティブなサンドボックスを走査し、`last_active_at` でアイドルしきい値を超えたか判定します（HTTP リクエストごと・新建 WebSocket 接続ごとにこの時間は更新され、DB 書込は毎分 1 回に制限）。休眠はサンドボックス内の稼働中をすべて中断するため（Docker はプロセスを凍結、Fly.io は停止）、アイドル判定後・休眠前にサンドボックス内 agent-server に走行中の仕事があるかを問い合わせます: 会話ターン、cron / カンバン / チャネル / 評価の実行、切り離された子 Agent、バックグラウンド shell タスク — あれば睡眠を延期します。バックグラウンド shell タスクはプランのアイドルしきい値に加えて最大 1 時間まで維持され、忘れられた開発サーバーがサンドボックスを永久に眠らせ続けることを防ぎます。応答できないサンドボックスはアイドル扱いで、無応答のサンドボックスが永久に起きていることはありません
* **権益段階ごとのタイムアウト**: Free 5 分、Companion 30 分、Pro 1 時間、Max 24 時間 — EntitlementService がユーザーのプラン別に設定
* **二層バッファ**: アイドル 5 分かつ agent もバックグラウンド shell タスクも動いていないとき、まず CPU をプランのコア数の 25% へ下げ（ResourceScaler）、さらにアイドルがしきい値に達してから休眠します。次のリクエストが来れば CPU は即座にフルパワーへ戻ります
* **秒単位の復帰**: Docker の pause/unpause でプロセスを凍結・復元し、メモリ状態は完全に保持、復帰は 100ms 未満。unpause が失敗した場合は start コンテナへ自動縮退
* **メッセージのゼロ損失**: 休眠中に届いたメッセージは Redis キュー（最大 10 件）に入り、復帰後に自動排出
* **状態の自己修復**: StateReconciler が定期的に DB の状態とコンテナの実際の状態を照合し、不一致を自動修復
* **長期未使用の自動回収**: 設定日数を超えた未使用サンドボックスは自動破棄されリソースを解放

## 企業組織管理とデータ資産の引き継ぎ

B2B チーム向けに、Control Plane は完全な組織ライフサイクル管理を提供します。

* **RBAC ロール体系**: Owner / Admin / Member の 3 段階権限とアトミックな認可
* **冪等なメンバー追加**: 重複操作は既存レコードを安全に返し、500 エラーを起こしません
* **ワンクリック退職引き継ぎ**: 管理者がサンドボックスを凍結 → Volume をバックアップ → 引継ぎ先へ譲渡、まで 1 ステップ
* **改ざん不能な監査**: すべての引き継ぎ操作にコンプライアンスログを記録
* **跨組織保護**: 同一ユーザーが 2 つの組織に同時に属することはできません
* **三路対称の失効**: メンバー削除は Org MCP / 承認ポリシー / モデル許可リストの 3 路を即時クリア（fire-and-forget の非同期配信）。サンドボックス休止中の解除では残留ガバナンスを自動クリアし、権限が残る窓をゼロに
* **アーカイブ保持期間の自動クリーン**: 退職アーカイブは組織設定の保持日数（`archive_retention_days`、既定 365 日）で自動削除され、コンプライアンス保持とディスク節約を両立
* **引き継ぎの安全境界**: 明示的な `backup_path` はバックアップディレクトリ配下である必要（越境は 409）、自己移譲（source == target）は拒否、UI はアーカイブ済みのメンバーだけを引継ぎ元として表示

企業データが退職者とともに失われることはありません — 常に組織管理下にあり、全過程が追跡可能です。

### Zero-Secret LLM ゲートウェイ

クラウドホストモードでは、API Key がサンドボックスに一切入りません。

* 実鍵は Control Plane の **AES-256-GCM 暗号化金庫**に保管
* サンドボックス内有のは HMAC 署名の**仮想鍵**（`myrm-vk-...`）のみで、実 Provider に対して完全に無効
* すべての LLM 呼び出しは CP relay 経由で転送: 署名検証 → 実鍵の注入 → リクエストボディの素通し
* リクエストボディは**バイト単位でそのまま転送**され、上流の Prompt Prefix Cache が完全に保持されます
* サンドボックスが完全に侵害されても、取得できる API 資格情報は 1 つもありません

### 企業 SSO シングルサインオン

Enterprise は OIDC プロトコルに対応します（WeCom、Feishu、DingTalk、Google Workspace、Azure AD、Okta）。従業員はアプリを開けば企業の IdP で認証されます — 個別の登録不要、API Key の管理も不要です。

## 明示的リソースライフサイクルとロックフリーの漏洩防止ランタイム

Myrm は二層の明示的 async 解放プロトコルと、ロックフリーの Actor 並行モデルを採用しています。

1. **明示的 async 破棄契約**: コード実行器は標準の `close()` async プロトコルを実装し、async コンテキストマネージャ（`async with executor:`）に対応します。破棄経路はミドルウェア経由で下層の OS サンドボックスハンドルまで縦に穿透します（Windows AppContainer 権限の主动取り消し、Seatbelt サンドボックスの解除、bash 子プロセスのクローズ）。
2. **Session Stash の自動追い出し**: 各会話ターンの終わりに一時保持された実行器セッションを自動追い出し・破棄し、高並行・複数 Agent オーケストレーションでもゾンビプロセスとファイルディスクリプタの漏洩を根絶します。
3. **ロックフリーの MCP セッション Actor**: 従来型の mutex やデッドロックしやすい同期機構に依存せず、Myrm は永続化 `MCPSessionActor` 内で単一 Owner の直列 FIFO キューによりツール実行とリソース読み出しをスケジューリングし、並行レースとデッドロックを根本から排除します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.