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 |
|---|---|---|
|
reference backend |
Separate guest kernel, copy-in/copy-out disks, default no network. |
|
convenience backend |
Local development and smoke tests using the same OCI image. |
|
convenience backend |
Linux/rootless-friendly local execution. |
|
convenience backend |
Mac-native execution when Apple’s |
|
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:
Resolve and unpack the OCI image.
Create an ephemeral ext4 root disk from the image rootfs.
Create a read-only input ext4 disk with the workspace and
job.json.Create a writable output ext4 disk.
Boot QEMU with
den.sandbox=runand network disabled by default.den-sandbox-runner.serviceruns the command inside the guest.The guest writes
/output/result.jsonand/output/stdout.log, then powers off.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. |
|
copied input |
Copied from the input disk for QEMU; mounted read-only for container backends. |
|
writable output |
Copied out after QEMU exits; mounted writable for container backends. |
|
runtime temporary storage |
Bounded by the backend. |
|
runtime state |
Bounded by the backend. |
|
image runtime prefix |
Comes from the selected Den image. |
|
agent tool prefix |
Comes from |
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