# 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: ```text 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: ```bash 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: ```bash 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: ```bash den sandbox inspect ``` Clean sandbox output and work directories: ```bash 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: ```text 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: ```bash den sandbox run --backend docker --image registry.den-os.org/den-agent:2026.6 -- python --version ``` Default-deny network should fail for network access: ```bash 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: ```bash den sandbox verify --output build/sandbox-output ``` For a local image that is intentionally outside the release trust policy: ```bash den sandbox run --backend docker --image den:dev --allow-unsigned -- den status ```