path: root/README.md

# AI Agent Sandbox MCP Server v1

Windows 11上でOllamaを利用し、利用者が確認したWorkspace、Mount、Executable、Network、Resourceの範囲だけをLPAC内で実行するMCP Serverです。MCP `2026-07-28`のstateless HTTPと公式Tasks Extensionに対応し、MCP公開Toolは `agent_run` と `agent_status` の2つです。

## 動作要件

- Windows 11 x64
- 管理者権限（TaskごとのWFP filter追加・削除に必要）
- Base Filtering Engine (BFE)が実行中
- Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。
- Release既定model: `deepseek-v4-flash:cloud`（native Internal Tool calling対応）

サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。

## 初回セットアップ

管理者としてPowerShellを起動し、Release Bundleへ移動します。

```powershell
ollama --version
ollama pull deepseek-v4-flash:cloud
ollama serve
```

初回はUser Sandbox ConfigurationのLogical Pathを確認してから、別の管理者PowerShellで診断します。

```powershell
.\agent-mcp.exe sandbox resolve --config .\agent.yaml
.\agent-mcp.exe executable resolve python --config .\agent.yaml
.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml
.\agent-mcp.exe sandbox confirm --config .\agent.yaml
.\agent-mcp.exe sandbox show --format text --config .\agent.yaml
.\agent-mcp.exe check --config .\agent.yaml --lang ja
```

`administrator=true`、`bfe_engine_open=true`、`wfp_write_transaction=true`、`wfp_filter_add_delete=true` が必要です。probeはdynamic WFP filterを追加後すぐ削除し、残留させません。

`serve`も待受開始前に同じprobeを必ず実行します。失敗時はendpointをbindせず、失敗項目・Win32 error・対処方法をstderrと`logs/application.log`へ出してexit code 2で終了します。

## User Sandbox Configuration

`schema_version: 1`のSandbox設定は利用者が理解できるsemantic単位で記述します。未指定capabilityはdenyです。

```yaml
sandbox:
  profile: development
  workspaces:
    - C:/work/project
  mounts:
    - path: C:/data/reference
      access: read_only
  execution:
    executables: [python, git]
    shells: [powershell]
  network:
    access: local
    local_endpoints:
      - port: 11434
    restricted_endpoints: []
  resources:
    profile: normal
    # memory_mb: 4096
    # process_limit: 16
    # execution_timeout_seconds: 1800
```

`readonly` ProfileはWorkspaceをread-onlyにし、Workspace ArtifactのEntry起動を禁止します。`development`はWorkspaceのread/write/deleteとArtifact起動を許可します。Mountは`read_only`、`read_write`、`read_write_delete`から選び、Mount上のExecutableをEntry Processとして起動することはできません。

Resource Profileは`constrained`（1024 MiB/4 Process/300秒）、`normal`（4096 MiB/16 Process/1800秒）、`extended`（8192 MiB/32 Process/3600秒）です。正数overrideを指定できます。

Network accessは`none`、`local`、`restricted`です。`none`はLoopbackを含め全deny、`local`は列挙portの`127.0.0.1`と`::1`だけ、`restricted`はTask開始時にIP snapshot化したhost/portだけを許可します。Ollama通信はBroker側から行うため、Sandbox Process TreeのNetwork設定とは独立です。

Workspace/Mountはreparse chainをResolved Pathへ解決します。`sandbox resolve`で差分を確認し、`sandbox confirm`でconfig別のResolution Storeへ保存してください。config fingerprintまたはResolved Pathが変わると`serve`は再確認までfail-closedになります。

```powershell
.\agent-mcp.exe sandbox resolve --config .\agent.yaml
.\agent-mcp.exe sandbox confirm --config .\agent.yaml
.\agent-mcp.exe sandbox show --format json --config .\agent.yaml
```

## Executable Approval

`sandbox.execution`には人間向けAliasを記載します。PATH候補は提示だけで自動選択されません。選んだResolved PathとSHA-256をuser-local Approval Storeへ固定します。

```powershell
.\agent-mcp.exe executable resolve python --config .\agent.yaml
.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml
.\agent-mcp.exe executable list --config .\agent.yaml
.\agent-mcp.exe executable revoke python --config .\agent.yaml
```

Approved Entry Executable／Approved Shell ExecutableはAlias、Resolved Path、SHA-256一致が必要です。確認済みRuntime Root内のRuntime Componentと、development Workspace内のWorkspace ArtifactもEntry Processにできます。その他のExternal Unknown ExecutableをBrokerから直接起動することはできません。

ApprovalはEntry Processにだけ適用されます。Descendant Processは個別Approvalを要求せず、Entry Processと同じLPAC token、Filesystem ACL、WFP、Job Objectを継承します。Jobからのbreakawayは禁止され、Process数・memory・timeout・`KILL_ON_JOB_CLOSE`はProcess Tree全体へ適用されます。

Sandbox Process Treeへは最小限のWindows/runtime環境変数だけを渡し、Brokerの任意token、password、SSH/API credential環境変数は継承しません。User profile等のpathが環境に含まれても、そのpathへFilesystem Capabilityは付与されません。

Executable Approval StoreとResolution Storeは`%LOCALAPPDATA%\AgentSandboxMcp`にuser-only DACL、WriteThrough、atomic replaceで保存されます。publishやupgradeはこれらのStoreを上書きしません。

## その他のagent.yaml設定

MCP Taskの保持とlog出力は次のtyped settingで変更できます。

```yaml
mcp:
  tasks:
    time_to_live_hours: 24
    poll_interval_ms: 1000
logging:
  directory: logs
  level: information       # information / warning / error / fatal
  http_requests: true
  max_file_bytes: 10485760
  retained_files: 5
```

配布された`agent.yaml`と同じdirectoryに任意の`agent.local.yaml`を置くと、環境固有値だけを上書きできます。mapは再帰merge、scalarと配列はlocal側で置換され、merge後の全設定を通常どおり検証します。相対pathは`agent.yaml`のdirectory基準です。local設定から利用者固有のSystem PromptやSkill directoryを指定できます。`agent.local.yaml`と、その参照先prompt／SkillはRelease Bundleへ含まれず、publishでも上書きされません。雛形は`config/agent.local.example.yaml`です。

引数なし、または最初の引数がoptionの場合は`serve`として扱われます。次の2つは同じです。

```powershell
.\agent-mcp.exe serve --config .\agent.yaml
.\agent-mcp.exe --config .\agent.yaml
```

Task状態は`state/mcp-tasks/`へatomic保存されます。再起動時の未完了Taskは`failed/server_restarted`となり、自動再実行されません。

## Agent Skills

`skills/<skill-name>/SKILL.md`形式だけを読み込みます。legacyの`skills/*.md`は読み込みません。SkillはLLMへの補助指示であり、Sandbox capabilityは付与しません。Skillが使うHost ExecutableはAliasを設定し、Entry起動前に承認してください。

## stdio

WFP操作のため、stdioではMCP Client自体を管理者PowerShellから起動します。Client設定例:

```json
{
  "mcpServers": {
    "agent-sandbox": {
      "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe",
      "args": ["serve", "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml", "--lang", "ja", "--transport", "stdio"]
    }
  }
}
```

`agent_run`へ自然言語の依頼を送り、返却されたUUIDを `agent_status` でterminal stateまでpollします。複数Taskはqueuedで受理しますが、planning/runningおよびTask Resource適用は全体で1件です。

## Streamable HTTP

管理者PowerShellでserverを起動します。`MCPリクエストを受け付けられます`とendpointが表示されてから接続してください。

```powershell
.\agent-mcp.exe serve --config .\agent.yaml --lang ja --transport http
```

Client endpointは `http://127.0.0.1:8080/mcp` です。設定できるbindは `127.0.0.1` または `::1` だけです。HTTPはMCP `2026-07-28` statelessで`Mcp-Session-Id`を使用しません。SDKの旧initialize fallbackは維持しますが、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。

Tasks対応clientは`agent_run`を公式MCP Taskとして受け取り、`tasks/get`と`tasks/cancel`を使用できます。非対応clientは従来どおりqueued textから`task_id`を取得し、`agent_status`でpollします。`session_id`はAgent会話IDでありHTTP transport sessionではありません。

## LogとRecovery

- `logs/application.log`: 起動・診断・管理event
- `logs/llm.jsonl`: LLM request/response、token usage、tool result
- `logs/audit.jsonl`: Task ID付きfile/process/policy/ACL/WFP/recovery event
- `logs/http.jsonl`: connection/trace ID、実socketの接続元IP/port、method/path/status/duration、MCP routing header
- `state/journals/`: crash recovery journal。正常終了後は空
- `state/backups/`: 大容量file transaction backup。正常終了後は空

log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。

HTTP logは`X-Forwarded-For`を接続元として信用せず、Authorization、Cookie、query、body、prompt、画像、Base64を保存しません。stateless HTTPでは永続接続を主張せず、request started/completedとして記録します。

HTTP request処理はconsole/file出力と同期しません。運用logはbounded queue経由でbackground出力し、consoleが一時停止してもHTTP requestを停止させません。queue飽和時はrequest継続を優先し、drop件数をapplication logへ警告します。

LLM/Audit JSONLはtask、session、event、call単位で絞り込めます。

```powershell
.\scripts\Read-AgentLog.ps1 -Path .\logs\llm.jsonl -TaskId <task-id> -Tail 100
.\scripts\Read-AgentLog.ps1 -Path .\logs\audit.jsonl -Event policy.deny -Tail 100
```

正常停止後、`agent-mcp.exe` descendant、追加ACL、WFP filter、loopback exemption、`state/backups`、`state/journals` が残っていないことを確認してください。loopback exemptionは `CheckNetIsolation.exe LoopbackExempt -s` で確認できます。

## よくあるエラー

- `error 5` / administrator=false: 管理者PowerShellから起動してください。
- BFE open失敗: `Get-Service BFE` でBase Filtering Engineを確認してください。
- Ollama接続失敗: `ollama list`、endpoint、model名を確認してください。
- resolution未確認／変更: `sandbox resolve`のLogical/Resolved Path差分を確認し、`sandbox confirm`を実行してください。
- Alias不明／Approval不足／hash変更: `executable resolve`で候補を確認し、明示したpathを`executable approve`で再承認してください。
- Filesystem deny: 対象を適切なWorkspaceまたはMountとして設定し、Resolutionを再確認してください。
- rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。

## ソースからのbuild／release

```powershell
dotnet restore AgentSandboxMcp.slnx
dotnet build AgentSandboxMcp.slnx -c Release --no-restore
dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore
.\scripts\Acquire-McpConformance.ps1
# 管理者権限でserverを起動後:
.\scripts\Run-McpConformance.ps1 -Url http://127.0.0.1:8080/mcp
.\scripts\Publish-Release.ps1
```

生成物はすべてrepository rootの `build/` に集約されます。

- `build/Debug/<ProjectName>/`: Debug build
- `build/Release/<ProjectName>/`: Release build
- `build/obj/<ProjectName>/`: restoreおよびcompiler中間生成物
- `build/Release/publish/`: win-x64 self-contained Bundle、version付きZIP、checksum

`artifacts/` はローカルの試験証跡・デバッグログ用です。`artifacts/` と `build/` はどちらもGit管理外です。

Release scriptは再現可能な既定値だけを含むwin-x64 self-contained ZIP、checksum、publish manifestをstagingから生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。deployment directory更新時は`agent.local.yaml`、`local/`、`logs/`、`state/`を削除・上書きしません。完全な `agent-mcp check` はResolution確認とExecutable Approval後に管理者PowerShellで実行してください。