Winagent Sandbox

Windows 11 x64上でOllamaを利用し、AIエージェントのファイル操作とプロセス実行を利用者がYAMLで指定した範囲へ閉じ込めるMCP Serverです。LPAC、NTFS ACL、Job Object、WFPでSandbox Process Treeを強制し、通常権限のmain processからTask単位で必要なnetwork操作だけをUAC昇格します。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を個別登録する必要はありません。

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から指定できます。Release artifact生成用stagingにはこれらの利用者状態を含めません。利用者deploymentをupgradeするときはExecutableと既定資産だけを置換し、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を表示しません。

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

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

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

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

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

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

.\agent-mcp.exe .\agent.yaml

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

.\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を持つ次の場所に保存されます。

%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の昇格確認が表示されます。

{
  "mcpServers": {
    "winagent-sandbox-mcp": {
      "command": "C:\\tools\\winagent-sandbox-mcp\\agent-mcp.exe",
      "args": ["C:\\tools\\winagent-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

.\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

開発

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

Releaseとupgrade

Publish-Release.ps1はDirectory.Build.propsのApplication Versionを読み取り、次を生成します。展開済みBundle directoryは利用者deploymentではなく、実行のたびに完全再生成されるRelease staging成果物です。

build/Release/publish/
  winagent-sandbox-mcp/
  winagent-sandbox-mcp-v<version>-win-x64.zip
  winagent-sandbox-mcp-v<version>-win-x64.zip.sha256

ZIP内のroot directory名とExecutable名にはversionを含めません。agent.local.yaml、local/、logs/、state/、Applied Configuration StoreはBundleとZIPに含まれません。

利用者deploymentのupgradeでは、ZIP内のExecutableと既定資産だけを置換し、利用者固有のlocal設定、Prompt、Skill、logs、state、Applied Configuration Storeを保持してください。旧version付きdirectoryから新しいdeployment pathへ移す場合は、local資産を利用者が移動し、新しいconfig pathに対して次を実行します。

.\agent-mcp.exe show .\agent.yaml
.\agent-mcp.exe apply .\agent.yaml

本Repositoryはinstallerやdeployment upgrade scriptを提供しません。

詳細は仕様書と設計書を参照してください。

ライセンス

MIT