Esc
  • SuggestedWhat is HCP?
  • SuggestedBuild a pack
  • SuggestedPack classes
  • SuggestedSpecification
  • SuggestedCLI reference
.md

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

On this page

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:

FieldValuesDefault
modenone | ephemeral | workspacenone (pack root, HCP/1)
home_envenv key names["HOME"] when mode is workspace, else none
file_flagsflags 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.