Sandbox & Execution

The first three layers decide whether a tool may run. This is layer 4: when an allowed tool actually runs code, it runs inside a box with no capabilities it wasn't granted — and its result is cryptographically attested. The earlier layers can be tricked by a clever prompt; this one can't, because it isn't asking the model anything. It's an operating-system-level cage with a signed receipt.

Two boxes: process and container

"Sandbox" means a confined execution environment: the code runs, but the walls of the box decide what it can see and do. The harness ships two boxes, picked by how strong the isolation needs to be.

The Docker executor enforces a minimum-isolation invariant. When a request's permission profile requires MinimumIsolation = Container and Docker is unavailable at runtime, the execution fails rather than quietly falling back to the weaker process sandbox.

Windows Job Objects: the resource cage

The process sandbox is held shut by a Job Object. Defining the term plainly: a Job Object is a Windows kernel object that caps and contains a group of processes — you attach a process (and everything it spawns) to the job, set limits on the job, and the kernel enforces those limits on every process in it. The harness wires this up via P/Invoke (calling the native Windows API directly) in two files:

• src/Content/Infrastructure/Infrastructure.AI/Sandbox/WindowsProcessResourceLimiter.cs
• src/Content/Infrastructure/Infrastructure.AI/Sandbox/WindowsJobObjectManager.cs

The default limits — all configurable through ResourceLimits — are:

The last row is the one that makes the cage trustworthy. JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE guarantees that when the job handle closes, every process in the job dies with it — there is no way for a spawned child to survive the teardown and keep running on the host. Combined with the active-process cap, this closes the most direct denial-of-service against the sandbox itself.

The closed-by-default capability model

Resource limits stop a tool from overwhelming the host. Capabilities stop it from reaching things it has no business reaching. A capability is a named permission for a category of effect. The flags live in src/Content/Domain/Domain.AI/Sandbox/ToolCapability.cs:

The model has three parts, and the order matters:

An operator can narrow what a specific tool is allowed to do below its own declaration via a per-tool DeniedCapabilities override in ToolOverrideConfig. The harness keeps the tool's own declaration (ToolPermissionProfile.RequiredCapabilities) and the operator's deny list separate rather than folding one into the other — a tool whose declared requirement overlaps the deny is refused outright, not silently granted a smaller set of capabilities than it actually needs. EffectiveCapabilities (RequiredCapabilities minus DeniedCapabilities) is the value sandbox provisioning and the attestation reads. There is no ambiguity to exploit and no ordering trick: deny always wins, and a denial that the tool actually needs is a hard refusal, never a quiet downgrade. (This control also scopes allow/deny to specific filesystem paths and network hosts via AllowedPaths/DeniedPaths/AllowedHosts/DeniedHosts. CapabilityEnforcer checks a call's requested paths/hosts against these lists whenever the tool declares which of its parameters carry them, and this is enforced identically across all three tool-invocation entry points: the agent's conversational turn, the direct-invoke HTTP surface, and plan/DAG steps. One narrow gap remains, tracked for follow-up rather than fixed: whole-shell-command tools that bypass the capability enforcer entirely. (A plan step chaining a path/host value from an upstream step's output used to bypass scoping the same way; that's now fixed — such a value is normalized identically to a directly-declared one before the check runs.)

Long-lived sessions: a bundle's own MCP server, sandboxed

Everything above assumes a tool runs once: input in, output out, box torn down. A stdio-style MCP (Model Context Protocol — the standard the harness uses to expose tools to the model) server doesn't fit that shape. It's a local process that stays running for the whole conversation, answering many tool calls over one open connection — closer to a phone call than a letter. The one-shot sandbox has no way to hold that call open, so a bundle (an uploaded, untrusted package of instructions and files) that declared its own local MCP server used to be rejected outright at upload time. This section covers the sandbox's second shape: one built to stay open.

The bridge between this new session shape and the MCP protocol is SandboxedStdioClientTransport (src/Content/Infrastructure/Infrastructure.AI.MCP/Services/SandboxedStdioClientTransport.cs) — it makes an ISandboxSession look, from the MCP SDK's point of view, like an ordinary local process it's talking to over standard input/output. The model's side of the conversation doesn't change at all; only where the other end of the pipe actually executes does.

The registration gate that makes any of this reachable lives in BundleStagingService (src/Content/Infrastructure/Infrastructure.AI/Bundles/BundleStagingService.StdioMcp.cs). Before this capability existed — and still today, unless an operator turns it on — a bundle declaring a stdio-type MCP server in its manifest was rejected outright. Turning it on is a separate, explicit opt-in from the one that already lets a bundle register a remote (http/sse) server:

All four live under AppConfig:AI:BundleExecution:StdioMcpServers — deliberately separate from BundleExecutionConfig.AllowBundleDeclaredMcpServers, the flag for remote servers. Opting into one does not opt into the other; each capability needs its own decision.

The bundle's own files reach the container by copy, not mount — the sandbox workspace is seeded from the bundle's staged directory at session start (src/Content/Infrastructure/Infrastructure.AI/Sandbox/SandboxWorkspace.cs), never bind-mounted. A live session's lifetime and the staging directory's lifetime aren't the same thing; a mount would tie them together and let a running container see later changes to — or write changes back into — files outside the exact snapshot it was granted.

Argument-injection prevention

Even a correctly-caged subprocess can be subverted if you build its command line by gluing strings together. The harness's execution request, src/Content/Domain/Domain.AI/Sandbox/SandboxExecutionRequest.cs, removes the chance entirely: subprocess arguments are passed as an ArgumentList — an array where each element is handed to the process directly, with no shell interpretation in between.

The contrast is the whole defense. Consider a tool that runs grep over user-supplied input:

// SAFE — each array element is a literal argument, never parsed by a shell.
var request = new SandboxExecutionRequest
{
    ArgumentList = ["grep", userInput]   // userInput is ONE argument, whatever it contains
};

// UNSAFE — string concatenation hands the input to a shell to re-parse.
var cmd = $"grep {userInput}";           // a shell now interprets metacharacters in userInput

To force this safe path everywhere, the older string-valued Arguments property is deprecated with error: true — code that still uses it won't compile, so there is no quiet legacy path left that re-parses a shell string.

HMAC attestation: a signed receipt for every run

The cage stops a tool from doing damage. Attestation answers a different question: can you later prove this output really came from a sandboxed run of this input, and wasn't tampered with afterward? The harness signs an attestation after every sandboxed execution in src/Content/Infrastructure/Infrastructure.AI/Attestation/HmacAttestationService.cs, using HMAC-SHA256.

The signature covers a fixed payload. On a successful run:

// Success payload that gets HMAC-signed:
{toolName}|{inputHash}|{outputHash}|{timestamp:O}|egress:{egressDigest}

// Failure payload (no output to hash, so the failure reason is hashed instead):
{toolName}|{inputHash}|null|{failureHash}|{timestamp:O}

Why this matters: the attestation proves a given output was produced by a real sandboxed execution of a given input, and was not altered after the fact. The egress digest in the payload ties the run to the exact set of network destinations that were allowed when it started, so a result and its network policy can't be silently decoupled later.

Where the signing key lives

An HMAC is only as trustworthy as the secrecy of its key, so the key handling is deliberate. Keys come from IOptionsMonitor<AttestationKeyOptions> — src/Content/Infrastructure/Infrastructure.AI/Attestation/AttestationKeyOptions.cs — sourced from User Secrets in development and Azure Key Vault in production. They are never read from appsettings.json.

• CurrentKeyVersion supports rotation: the signed payload carries the key version, so keys can be rolled forward without invalidating the ability to identify which key signed an older attestation.
• Key bytes are zeroed after use with CryptographicOperations.ZeroMemory, so the secret doesn't linger in process memory longer than the signing operation needs it.

What a skill can read: two file sandboxes, not one

File access on the host runs through two separate sandboxes with deliberately different permissions. They share one implementation of the rules — allow/deny geometry, symlink resolution, hard-link identity checks — so they cannot drift on what "inside" means, but they permit different directories and offer different operations.

The guarantee, stated plainly: skill loading is confined to the configured skill content roots, read-only — and to nothing in the model's own file allowlist. Everything a skill can load — its SKILL.md, and any reference or template file it discloses on demand through read_skill_resource — must live inside one of those roots. A path outside them is refused with an error, never silently treated as missing: a refusal that read as "this directory holds no skills" would be indistinguishable from a directory that genuinely holds none, so a misconfigured root would boot an agent quietly missing its skills instead of failing.

The two allowlists are disjoint by design, so the guarantee is not the union of the two — the model's file tool gains nothing from the skill roots, and skill loading gains nothing from the model's configured paths.

The skill sandbox resolves its permitted roots from live configuration rather than snapshotting them at startup. Plugin-supplied skill directories are registered during host start, after the dependency container is built; a snapshot taken at registration time would refuse exactly the plugin skills the harness advertises support for. A plugin cannot widen the sandbox arbitrarily — its skill directory is accepted only after being verified as contained within the plugin's own directory, and that directory comes from operator configuration under AppConfig:AI:Plugins:Packages.

Where the network side lives

This layer contains what a tool can do on the host: how much it can consume, what it can touch, and proof of what it produced. The other half of containment is where it can reach on the network — blocking SSRF, cloud-metadata credential theft, and exfiltration. That's the egress allowlist whose digest you saw signed into the attestation payload above. It gets the full treatment on the next page.