---
title: "§10 Sandbox"
description: "Normative execution posture. Sandbox by default with bin allow-list, cwd jail, and no ambient credentials; native-local only by explicit opt-in."
canonical: https://harnesscontextprotocol.io/docs/specification/sandbox
---

# §10 Sandbox

> Normative execution posture. Sandbox by default with bin allow-list, cwd jail, and no ambient credentials; native-local only by explicit opt-in.

## 10.1 Default

1. A runtime MUST execute Adapters in `sandbox` mode unless the harness has
   explicitly opted into `native-local`.
2. Opting into `native-local` MUST require an explicit, positive configuration
   action. Absence of configuration MUST yield `sandbox`.

## 10.2 Sandbox requirements

In `sandbox` mode a runtime MUST:

1. Allow-list binaries. Spawn only `wrap.bin` values that are on the
   runtime's allow-list. The allow-list SHOULD be seeded with the activated packs'
   declared `wrap.bin` values and the runtime's own CLI. A bin not on the list
   MUST be refused with exit `127` and `error: sandbox: bin "<bin>" not allowlisted`.
   The runtime MUST NOT resolve an unlisted bare name via `PATH`.
2. Jail the working directory. Set the child's working directory to the
   pack root or a per-pack jail. Land `local` binds to this directory.
3. Inherit no ambient credentials. Provide only credentials minted through
   Binding (§8.4) and the pack's `wrap.agent_env`. A runtime MUST NOT rely on
   credentials present in its own environment to satisfy a pack.
4. Mark the environment. Set `HCP_SANDBOX=sandbox` in the child.
5. Ignore env-flag mocks. Mock is envelope-explicit only (§8.2).

## 10.3 Native-local

1. In `native-local` mode a runtime MAY resolve `wrap.bin` on the host `PATH`
   and MAY relax the cwd jail.
2. The runtime MUST set `HCP_SANDBOX=native-local`.
3. All other requirements of this specification (grants, confirm, mint
   fail-closed, Policy coverage) apply unchanged.
4. *Informative.* Native-local expresses a trust decision about a personal
   machine. It is not a convenience mode.

## 10.4 Stronger isolation

1. Containers, microVMs, seccomp profiles, read-only filesystems, and per-family
   network egress policy are conforming implementations of `sandbox`.
2. A pack MUST NOT need to change to run under stronger isolation. Isolation is
   a runtime property.

## 10.5 Reference behaviour (informative)

The reference runtime implements §10.2 with a process allow-list (bare names or
absolute paths; a bare name matches a path ending in `/<name>`), a fixed cwd at
the pack root when `wrap.workspace` is omitted, and `HCP_SANDBOX` in the child
environment. It requires both `sandbox: false` and `nativeLocal: true` to enter
native-local.

## 10.6 Workspace / exec plane (RFC 0003)

Wrap names the bin. The exec plane names where that process may read and write.
Packs MUST NOT name a driver (object store, microVM, host path). Isolation is a
runtime property (§10.4).

### Pack field

Optional `wrap.workspace`:

| Field | Values | Default |
|-------|--------|---------|
| `mode` | `none` \| `ephemeral` \| `workspace` | `none` (pack root, HCP/1) |
| `home_env` | env key names | `["HOME"]` when `mode` is `workspace`, else none |
| `file_flags` | flags whose next argv token is a file | `--file`, `--json-file`, `--output`, `-o`, `--env-file` |

`ephemeral` is a fresh jail per exec. `workspace` binds the jail to
`privacy.land: local` for the Principal; the runtime persists it.

### File references

In `sandbox` mode a runtime MUST rewrite `workspace:` prefixes into the jail,
MUST reject host-absolute paths under `/etc`, `/home`, `/root`, and `/Users`
(`error: sandbox: host path not allowed`), MUST spawn argv as an array, and
MUST write back `--output` / `-o` (and new jail files when `mode` is
`workspace`) according to its driver. A runtime MAY accept more URI schemes in
file references and MUST rewrite them into the jail before spawn; those schemes
are not HCP types.

A runtime MUST implement at least a local driver. Additional drivers MUST use
prepare → rewriteArgv → spawn → writeback → cleanup. A pack MUST NOT change to
run under another conforming driver.

*Informative.* `hcp wrap <bin>` scaffolds `wrap.bin` from an existing CLI.

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)