RunSeal RFCs

July 23, 2026 · View on GitHub

RunSeal is for agent applications that need to run real local tools without giving the agent full control of the endpoint.

Unlike VM or container sandboxes, RunSeal keeps execution close to the host OS so commands can use installed toolchains, workspace files, enterprise endpoint configuration, local app integrations, and direct networking unless a network control is requested. Unlike raw shell execution, every command runs through a policy-governed boundary with filesystem restrictions, optional network controls, synthetic home/profile roots, cleanup, and structured audit events.

The Windows reference backend is the complete first-class MVP enterprise baseline.

Embeddable local security runtime for endpoint AI agents.

macOS and Linux remain experimental backends rather than the Windows enterprise baseline. read-only, workspace-write, and workspace-contained share one portable policy contract; portable workspace-contained uses a deny-by-default host-read boundary and is promoted only after the shared conformance suite passes. Unsupported or unavailable runtime guards fail closed.

RunSeal does not aim to be a VM platform, a Docker Desktop replacement, or a cloud multi-tenant sandbox service. It turns local agent execution into a policy-governed, auditable capability.

Core idea

AI agents increasingly need to run local commands: package managers, tests, linters, code generators, data-processing scripts, internal API clients, and loose community skills. The useful security boundary is not just “ask the user before every command”. The runtime needs a technical boundary that lets low-risk work continue autonomously while forcing sensitive operations through policy.

RunSeal follows the Codex-style model:

Sandbox: the OS-enforced boundary for filesystem, process, network, and resources.
Approval/policy: the governance layer that decides what can run automatically, what is denied, and what requires escalation.
Execution: a single command or tool run inside a seal.
Controlled proxy: the only network path for enterprise use, able to enforce routes, inject auth, redact data, and audit traffic.
Host OS capability preserving: keeps installed toolchains, workspace files, enterprise configuration, and local app integrations available inside the sandbox.

Architecture flow

flowchart LR
  Agent[Agent framework] --> Protocol[RunSeal CLI / JSON-RPC]
  Protocol --> Policy[Policy engine]
  Policy --> Backend{Platform backend}

  Backend --> Windows[Windows reference backend]
  Backend --> MacOS[macOS experimental backend]
  Backend --> Linux[Linux experimental/community backend]

  Windows --> Exec[Sandboxed execution]
  MacOS --> Exec
  Linux --> Exec

  Exec --> Audit[JSONL audit events]
  Exec --> Proxy[Managed proxy]
  Proxy --> Network[External network]

Initial RFC set

CLI vocabulary

The primary CLI verb is exec:

runseal exec --policy workspace-write --network proxy -- pnpm test
runseal exec --policy workspace-write --network disabled -- python skill.py
runseal exec --policy workspace-write -- pnpm test

The protocol method is execute; the returned domain object is an Execution, not a raw process.

Non-goals

No cloud VM sandbox platform.
No microVM runtime as the default product direction.
No Docker daemon dependency.
No direct secret injection into sandboxed processes.
No unmanaged direct network bypass when enterprise network controls are requested.
No claim that OS-native sandboxing prevents every kernel-level escape.
Not a generic sandbox CLI for manual developer use — built to be embedded by agent apps, IDEs, RPA platforms, and enterprise AI platforms.

Reference signals

These RFCs intentionally build on public industry signals:

OpenAI Codex sandboxing: OS-native sandboxing, workspace-write defaults, network approval, and sandbox/approval separation.
Anthropic Sandbox Runtime: OS-native process-tree restrictions for agent tools and MCP servers on macOS and Linux.
Microsoft MXC: cross-platform policy-driven execution isolation with deny-by-default macOS and Linux backends.
Linux bubblewrap/Flatpak: unprivileged namespace-based isolation, default-limited filesystem and network permissions.
Enterprise egress proxies such as iron-proxy: default-deny egress, boundary-level secret injection, and per-request structured audit trails.
OpenTelemetry/structured observability practices for sandbox execution and egress components.

Status

PRD-ready for MVP. The RFC set defines a Windows-first implementation baseline: Windows is the reference backend and enterprise security baseline, while macOS and Linux can be implemented behind the same protocol and promoted through conformance evidence.