blob: e2a350c615f7c76b1bc5d5aa8dc03dec6cb063ea (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
# AI Agent Sandbox MCP Server v1
Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、Process、Network操作だけをAppContainer内で実行するMCP Serverです。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は未確定です。
- 必須local model: `hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL`
サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。
## 初回セットアップ
管理者としてPowerShellを起動し、Release Bundleへ移動します。
```powershell
ollama --version
ollama pull hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL
ollama serve
```
別の管理者PowerShellで診断します。
```powershell
.\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を追加後すぐ削除し、残留させません。
## agent.yaml
Filesystem pathは能力ごとに指定します。未指定能力はdenyです。
```yaml
sandbox:
filesystem:
read: [C:/work/fixture]
write: [C:/work/fixture]
execute:
- C:/Program Files/dotnet/dotnet.exe
delete: [C:/work/fixture]
```
実行ファイルはcanonical absolute pathとSHA-256の両方を承認します。
```powershell
(Get-FileHash -Algorithm SHA256 -LiteralPath 'C:\Program Files\dotnet\dotnet.exe').Hash
```
```yaml
sandbox:
process:
allow_shell: false
approvals:
- path: C:/Program Files/dotnet/dotnet.exe
sha256: <64桁の実測値>
```
Sandbox processからの子process生成は、承認済みpathであってもOSのchild-process restrictionで拒否されます。build/testで必要な各実行ファイルは事前にpath/hash承認し、個別の `process_run` としてBrokerから起動してください。E2Eではbuild server、node reuse、shared compilationを無効化し、in-process buildまたはBrokerから直接起動できるself-testを使用します。Networkは既定でlocalhostを含めdenyです。allow時はTask開始時にhostをIPへsnapshot化します。
```yaml
sandbox:
network:
mode: allow
allow:
- host: 127.0.0.1
ports: [11434]
```
Ollama通信は管理Broker側から行うため、Sandbox processのnetwork許可とは独立です。
## 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を起動します。
```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` だけです。Streamable HTTP POSTだけを使用し、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。
## 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
- `state/journals/`: crash recovery journal。正常終了後は空
- `state/backups/`: 大容量file transaction backup。正常終了後は空
log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。
正常停止後、`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名を確認してください。
- executable deny: pathをabsolute/canonicalにし、更新後のSHA-256を再取得してください。
- file deny: 対象pathを必要なread/write/execute/delete能力へ追加し、再起動してください。
- 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\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 directory、version付きZIP、ZIP checksum、publish manifestを生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。完全な `agent-mcp check` は管理者PowerShellで実行してください。
|
