path: root/README.md

# AI Agent Sandbox MCP Server

Windows上でOllamaを利用し、AIエージェントのファイル操作とプロセス実行を、利用者がYAMLで指定した範囲へ閉じ込めるMCP Serverです。MCP Clientには`agent_run`と`agent_status`だけを公開します。

## 機能

- 計画、ファイル検索・読取・編集、プロセス実行を伴うAgent Task
- MCP stdio／Streamable HTTP（stateless）とMCP Tasks Extension
- LPAC、NTFS ACL、Job Object、WFPによるSandbox Process Treeの強制
- Workspace、Mount、Entry Executable、Network、Resourceの一括設定・確認
- 日本語／英語、監査ログ、異常終了後のRecovery

## 動作環境

| 項目 | 要件 |
| --- | --- |
| OS | Windows 11 x64 |
| 実行権限 | 通常ユーザー。Sandbox Processを初めて実行するTaskでWindows UACを表示 |
| Windows Service | Base Filtering Engine（BFE） |
| LLM | Ollama。配布設定の既定モデルは`deepseek-v4-flash:cloud` |
| Client | stdioまたはStreamable HTTP対応MCP Client |

Ollamaへの通信はBrokerが行います。Sandbox内プロセスのNetwork設定とは別です。

## 設定

`agent.yaml`がbase設定です。同じディレクトリに任意の`agent.local.yaml`があれば自動的に上書きマージします。mapは再帰merge、scalarと配列はlocal側で置換されます。相対pathはbase設定のディレクトリ基準です。

権限の希望状態はYAMLだけに記載します。CLIでExecutableやACLを個別登録する必要はありません。

```yaml
schema_version: 2

application:
  language: ja

mcp:
  transport: http
  http:
    host: 127.0.0.1
    port: 8080

ollama:
  endpoint: http://127.0.0.1:11434
  model: deepseek-v4-flash:cloud

sandbox:
  profile: development
  workspaces:
    - C:/tmp
  mounts:
    - path: C:/data/reference
      access: read_only
  execution:
    entries:
      - alias: python
        path: C:/tmp/.venv/Scripts/python.exe
        runtime_root: C:/Users/example/AppData/Roaming/uv/python/cpython-3.14-windows-x86_64-none
      - alias: powershell
        path: C:/Program Files/PowerShell/7/pwsh.exe
      - alias: cmd
        path: C:/Windows/System32/cmd.exe
  network:
    access: local
    local_endpoints:
      - port: 11434
    restricted_endpoints: []
  resources:
    profile: normal
```

実環境用path、Prompt、Skillは`agent.local.yaml`から指定できます。publish／upgradeは`agent.local.yaml`、`local/`、`logs/`、`state/`、適用済み設定Storeを上書きしません。

### 権限マトリックス

| YAML項目 | `readonly` | `development` | Entry Processとして起動 |
| --- | --- | --- | --- |
| `workspaces` | read | read/write/delete/execute | developmentのWorkspace Artifactのみ可 |
| `mounts: read_only` | read | read | 不可 |
| `mounts: read_write` | 設定不可 | read/write | 不可 |
| `mounts: read_write_delete` | 設定不可 | read/write/delete | 不可 |
| `execution.entries` | file read/execute | file read/execute | Alias、Resolved Path、SHA-256一致時に可 |
| `runtime_root` | read/execute | read/execute | Runtime Componentは子孫として利用可 |
| Resolved System32 | read/execute | read/execute | 未登録System32 Executableの直接Entry起動は不可 |

Entry Processの子孫には個別のExecutable登録を要求しません。同じLPAC identity、ACL、WFP、Job Objectを継承し、Process Tree全体が同じ制限内に残ります。

### Network

| `access` | 動作 |
| --- | --- |
| `none` | localhostを含む全通信を拒否 |
| `local` | `local_endpoints`のportについて`127.0.0.1`と`::1`のみ許可 |
| `restricted` | `restricted_endpoints`のhost/portをTask開始時にIPへ固定して許可 |

### Resource profile

| Profile | メモリ | Process数 | timeout |
| --- | ---: | ---: | ---: |
| constrained | 1024 MiB | 4 | 300秒 |
| normal | 4096 MiB | 16 | 1800秒 |
| extended | 8192 MiB | 32 | 3600秒 |

`memory_mb`、`process_limit`、`execution_timeout_seconds`は正数で個別上書きできます。

## 初回適用と起動

通常のPowerShellで展開先へ移動します。まずYAMLから計算された権限マトリックスを確認します。`show`と`apply`はUACを表示しません。

```powershell
.\agent-mcp.exe show .\agent.yaml
```

内容が正しければ設定全体を一度だけ適用します。Workspace/Mountの解決先、Executableの解決先とSHA-256、設定fingerprintが一つのスナップショットとして保存され、固定Application Profileが通常ユーザー権限で準備されます。

```powershell
.\agent-mcp.exe apply .\agent.yaml
```

CIなど対話入力がない場合だけ`--yes`を使用します。

```powershell
.\agent-mcp.exe apply .\agent.yaml --yes
```

起動にはcommand名がありません。transport、languageなどはすべてYAMLから読みます。

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

設定pathを省略すると、実行ファイルと同じディレクトリの`agent.yaml`を使います。

```powershell
.\agent-mcp.exe
```

YAML、解決先、Executable hashのいずれかが変化すると起動はfail-closedになります。`show`で差分を確認してから`apply`し直してください。YAMLからEntryを削除して再適用すると、その権限も同じスナップショットから削除されます。

## CLIリファレンス

| 構文 | 引数／option | 変更 | 用途 |
| --- | --- | --- | --- |
| `agent-mcp [<config-path>]` | 任意の設定path | Task中の一時Sandbox Resourceのみ | read-onlyのPlatform/BFE/helper検査後に通常権限でServer起動 |
| `agent-mcp show [<config-path>]` | 任意の設定path | なし | 現在の希望状態、Resolved Path、hash、適用一致状態を表示 |
| `agent-mcp apply [<config-path>] [--yes]` | 任意の設定path、任意の`--yes` | Applied Configuration Storeをatomic置換 | マトリックスを一括確認して適用 |

`serve`、`check`、`executable ...`、`sandbox ...`はschema v2で廃止されました。`--config`、`--lang`、`--transport`、`--path`、`--runtime-root`、`--no-runtime`、`--format`も廃止されています。値はYAMLへ書き、設定pathだけを位置引数で渡します。

## Applied Configuration Store

適用済みスナップショットはYAMLではなく、起動ユーザー専用DACLを持つ次の場所に保存されます。

```text
%LOCALAPPDATA%\AgentSandboxMcp\applied-configurations\<config-path-hash>.json
```

YAMLは希望状態、Storeは利用者が確認した実体path・hashを含む適用状態です。`apply`は設定全体をatomic replaceするため、個別承認と個別confirmの不整合は発生しません。`show`はread-onlyで、ACLやWFPを変更しません。

## MCP Client設定

stdioでもMCP Clientは通常権限で起動します。ファイル操作だけのTaskではUACは発生しません。Task内で最初の`process_run`を行う直前だけ、WFPとloopback設定を担当する同梱Executableの昇格確認が表示されます。

```json
{
  "mcpServers": {
    "agent-sandbox": {
      "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe",
      "args": ["C:\\tools\\agent-sandbox-mcp\\agent.yaml"]
    }
  }
}
```

HTTPでも`agent-mcp.exe`と接続するMCP Clientを通常権限で起動します。既定endpointは`http://127.0.0.1:8080/mcp`です。Task時のUACを拒否すると当該Taskだけがfailedになり、Serverは継続します。crash後にpersistentなloopback設定のRecoveryが必要な場合だけ起動時にUACが表示され、拒否するとMCP受付前に終了します。

## MCP Tool

| Tool | 用途 |
| --- | --- |
| `agent_run` | 自然言語の依頼をAgent Taskとして登録 |
| `agent_status` | 状態、進捗、token実績、結果またはエラーを取得 |

## PromptとSkill

System Promptは`agent.user_system_prompt`、Skill directoryは`skills.directory`で指定します。Skillは`skills/<skill-name>/SKILL.md`形式です。PromptやSkillはSandbox権限を増やしません。

## ログとRecovery

| 場所 | 内容 |
| --- | --- |
| `logs/application.log` | 起動とアプリケーションイベント |
| `logs/llm.jsonl` | Ollama call、token、Internal Tool結果 |
| `logs/audit.jsonl` | ファイル、Process、Policy、ACL、WFP、昇格、IPC拒否、Recovery、非対話apply |
| `logs/http.jsonl` | HTTP接続と処理結果 |
| `state/journals/` | crash recovery用Journal |
| `state/backups/` | 大容量編集のtransaction backup |

```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
```

## よくある問題

| 状況 | 対処 |
| --- | --- |
| `sandbox.configuration_not_applied` | `show`で全体を確認して`apply` |
| Executable更新後に起動できない | hash変更は自動承認しないため、`show`後に`apply` |
| helper／BFE preflight失敗 | Release Bundleの`admin\agent-mcp-admin.exe`を復元し、`Get-Service BFE`を確認 |
| Task実行時にUACを拒否 | 当該Taskはfailedになる。内容を確認し、必要ならTaskを再実行して昇格を承認 |
| Filesystem拒否 | WorkspaceまたはMountをYAMLへ追加し、再度`apply` |
| Network拒否 | `network.access`とendpointを見直し、再度`apply` |

## 開発

```powershell
dotnet restore AgentSandboxMcp.slnx
dotnet build AgentSandboxMcp.slnx -c Release --no-restore
dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore
.\scripts\Publish-Release.ps1
```

詳細は[仕様書](doc/Specifications.md)と[設計書](doc/Design.md)を参照してください。

## ライセンス

MIT