RunSeal Docs

Get started

Quickstart

Download the Windows release archive and keep these executables in the same directory:

• runseal.exe
• runseal-windows-sandbox-setup.exe
• runseal-command-runner.exe

.\runseal.exe setup windows-sandbox --cwd C:\path\to\workspace --elevate
.\runseal.exe capabilities
.\runseal.exe exec --json --policy workspace-write --network disabled --cwd C:\path\to\workspace -- whoami.exe

Windows sandbox support requires Windows 10 1809 / build 17763 or newer. Use --elevate to request UAC when first setup cannot run in the current shell. Sandboxed execution fails closed when setup is missing or stale.

Current behavior

Capability status

Use sandbox_levels, network_modes, and feature_statuses from getCapabilities for client decisions.

macOS and Linux support read-only, workspace-write, and workspace-contained with network.disabled and experimental network.proxy. macOS allows only the current execution's managed proxy endpoint; Linux uses an isolated network namespace and execution-local relay. Direct external, unrelated loopback, and unapproved host IPC connections remain denied. Portable contained execution exposes only the workspace, private runtime roots, explicit policy roots, and a minimum read-only system baseline. Backend status and low-level feature statuses remain experimental; clients should key decisions off the public sandbox level and network mode statuses.

macOS and Linux hardening evidence

Windows remains the reference backend. macOS and Linux track extra hardening evidence for the portable capabilities they claim, including deny-by-default host-read containment.

Reference

CLI reference

runseal exec --policy workspace-write --network proxy --cwd /workspace -- python skill.py
runseal exec --policy workspace-write --network disabled --cwd /workspace --timeout-ms 30000 -- whoami
runseal explain-policy --policy workspace-write --network proxy
runseal capabilities
runseal setup windows-sandbox --cwd C:\path\to\workspace --elevate
runseal mcp --stdio --policy workspace-write
runseal rpc --stdio
runseal service --stdio
runseal version

exec accepts --json, --events, --policy, --network, --cwd, and --timeout-ms. Flags must appear before --; the command and its arguments follow --.

Protocol

JSON-RPC stdio

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "execute",
  "params": {
    "command": ["python", "skill.py"],
    "cwd": "/workspace",
    "policy": "workspace-write",
    "network": {"mode": "proxy"},
    "timeout_ms": 30000
  }
}

Supported execute params are command, cwd, policy, network, stdin, timeout_ms, metadata, and env.

Windows backend

Setup and readiness

Windows sandbox support requires Windows 10 1809 / build 17763 or newer.

Build helper binaries locally when developing the Windows reference backend:

.\scripts\build-windows.ps1
.\scripts\build-windows.ps1 -Release

Check setup readiness without changing state:

.\target\debug\runseal.exe setup windows-sandbox --cwd C:\path\to\workspace --status

The status payload reports broker, elevated, can_repair, can_run_setup_now, requires_setup, and next_action.

Client guidance

Third-party integration

1. Call getVersion and getCapabilities before sandboxed execution.
2. Gate requested sandbox levels and network modes on capability statuses.
3. Fail closed when a capability is unsupported or setup is unavailable.
4. Use runseal mcp --stdio --policy <policy> [--network <mode>] when exposing execution directly to an AI agent. The MCP server exposes only exec; model calls must set command and cwd, and may set timeout_ms and string env overrides subject to policy scrub rules, but not policy, network, or stdin.
5. Treat the canonical policy plus workspace path as the policy epoch. Same-epoch executions may run concurrently; boundary-changing different-epoch requests must return POLICY_TRANSITION_BUSY unless they use isolated sandbox workers, identities, and setup state.
6. Use runseal service --stdio when one process should own completed execution state.
7. Use conformance tests with RUNSEAL_BIN=/path/to/runseal for candidate implementations.

{
  "mcpServers": {
    "runseal": {
      "command": "runseal",
      "args": ["mcp", "--stdio", "--policy", "workspace-write"]
    }
  }
}

Use the absolute runseal binary path when the MCP host does not inherit your shell PATH. Restart the host after editing its MCP config, then call the discovered exec tool with command, cwd, optional timeout_ms, and optional string env overrides.

Omit --network for unmanaged direct networking; pass --network disabled only when the MCP host should deny network egress. With --network proxy, commands should use injected proxy environment variables such as HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, GIT_HTTP_PROXY, and GIT_HTTPS_PROXY inside the current execution; do not hardcode a proxy host, port, or credential because RunSeal may attach the execution to a shared local managed proxy broker. RUNSEAL_NETWORK_PROXY_AUTHORIZATION is a per-execution credential for tools that require an explicit Proxy-Authorization header.

Verification

Testing

cargo fmt --check
cargo clippy --tests -- -D warnings
cargo test

Windows dogfood smoke:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\windows-smoke.ps1

Run from an elevated shell, or add -AllowElevation to validate the documented interactive UAC bootstrap path.

Linux or macOS portable smoke:

python3 scripts/portable-probe-smoke.py

Windows contained and network adversarial evidence: read the reproducible evidence snapshot.

Distribution

Release packaging

Pushing a v* tag runs .github/workflows/release.yml, builds native release archives, and publishes SHA-256 checksum files, SHA256SUMS, and a CycloneDX SBOM. Dispatch the same workflow with a tag input to rebuild assets for an existing release.

sha256sum -c runseal-vX.Y.Z-linux-x86_64.tar.gz.sha256
gh attestation verify runseal-vX.Y.Z-linux-x86_64.tar.gz --repo runseal-labs/runseal

Open the latest release

Source of truth

RFCs

The public protocol and policy contract lives in the RFC repository.

• RunSeal RFCs
• Stable execution protocol
• Escape model
• Adversarial conformance
• macOS managed proxy boundary
• Linux managed proxy boundary