Den Sandbox Reference

den sandbox runs commands inside a Den runtime image and writes an in-toto execution receipt for the run. The portable artifact is an OCI image. The reference isolation backend is QEMU with a separate guest kernel; Docker, Podman, and Apple container are convenience backends for local workflows.

Release Image Contract

Release images use the Den OCI registry:

registry.den-os.org/den:2026.6
registry.den-os.org/den-agent:2026.6

These names are the planned final release references. Do not treat them as available until the 2026.6 promotion receipt is public and verifies.

den:dev remains a local-only developer smoke image. Do not document it as a release artifact.

Command Surface

Run a command:

den sandbox run \
  --backend qemu \
  --image registry.den-os.org/den-agent:2026.6 \
  --workspace . \
  --output build/sandbox-output \
  --network none \
  --memory 4g \
  --cpus 2 \
  --timeout 1200 \
  -- python -m pytest

Verify the receipt:

den sandbox verify --output build/sandbox-output

Before execution, Den resolves the image tag to a digest and verifies Den registry images with Cosign against the den-os/den release workflow identity. Local or unsigned development images require an explicit --allow-unsigned.

Inspect defaults:

den sandbox inspect

Clean sandbox output and work directories:

den sandbox clean --yes

Backends

Backend

Support level

Purpose

qemu

reference backend

Separate guest kernel, copy-in/copy-out disks, default no network.

docker

convenience backend

Local development and smoke tests using the same OCI image.

podman

convenience backend

Linux/rootless-friendly local execution.

apple-container

convenience backend

Mac-native execution when Apple’s container CLI is available.

gvisor, kata, firecracker

future

Stronger OCI or microVM backends after the v1 command contract is stable.

QEMU Data Path

The QEMU backend uses copy-in/copy-out disks:

  1. Resolve and unpack the OCI image.

  2. Create an ephemeral ext4 root disk from the image rootfs.

  3. Create a read-only input ext4 disk with the workspace and job.json.

  4. Create a writable output ext4 disk.

  5. Boot QEMU with den.sandbox=run and network disabled by default.

  6. den-sandbox-runner.service runs the command inside the guest.

  7. The guest writes /output/result.json and /output/stdout.log, then powers off.

  8. The host extracts the output disk and writes sandbox.receipt.json.

Filesystem Policy

Path

Mode

Notes

/

guest root disk

Created from the selected OCI image.

/workspace

copied input

Copied from the input disk for QEMU; mounted read-only for container backends.

/output

writable output

Copied out after QEMU exits; mounted writable for container backends.

/tmp

runtime temporary storage

Bounded by the backend.

/run

runtime state

Bounded by the backend.

/opt/den

image runtime prefix

Comes from the selected Den image.

/opt/agent

agent tool prefix

Comes from den-agent.

Do not mount the host home directory, Docker socket, SSH agent, cloud metadata, or package-manager credential stores.

Receipt Predicate

Sandbox execution receipts use the existing Den in-toto Statement envelope and set:

predicate.kind = "sandbox-execution"

The predicate metadata records:

  • backend,

  • OCI image reference and digest when available,

  • target platform,

  • workspace digest,

  • argv,

  • environment allowlist,

  • network policy,

  • resource policy,

  • timeout,

  • exit code,

  • timeout status,

  • log files.

The receipt is an integrity and provenance document. Signed release images and registry attestations are separate release-layer controls.

Smoke Checks

Basic command execution:

den sandbox run --backend docker --image registry.den-os.org/den-agent:2026.6 -- python --version

Default-deny network should fail for network access:

den sandbox run --backend docker --network none --image registry.den-os.org/den-agent:2026.6 -- \
  python -c 'import urllib.request; urllib.request.urlopen("https://example.com", timeout=2)'

Receipt verification:

den sandbox verify --output build/sandbox-output

For a local image that is intentionally outside the release trust policy:

den sandbox run --backend docker --image den:dev --allow-unsigned -- den status