Skip to content

Document Docker Sandboxes comparison for box #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
konard merged 2 commits into from
May 10, 2026
Merged

Document Docker Sandboxes comparison for box #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80db384
Initial commit with task details
konard May 10, 2026
949988d
Add Docker Sandboxes comparison docs
konard May 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 173 additions & 0 deletions docs/case-studies/issue-86/CASE-STUDY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
# Case Study: Issue #86 - Docker Sandboxes Feature Comparison

## Summary

Issue #86 asks for a complete non-AI comparison of Docker Sandboxes against
`box`, with data preserved in `docs/case-studies/issue-86`, a requirements
breakdown, missing best practices, and solution plans.

The comparison is implemented in
[docs/docker-sandboxes-comparison.md](../../docker-sandboxes-comparison.md).
The strongest Docker Sandboxes practices to consider are not agent integrations;
they are environment-control practices: microVM isolation, deny-by-default
network policies, host-side credential proxying, workspace/worktree lifecycle
management, port forwarding, templates, kits, and resource governance. The
strongest `box` advantages are its universal toolchain breadth, public image
source, per-language modular images, matching `-dind` variants, GHCR plus Docker
Hub publishing, and no product-login requirement.

## Data Preserved

| File | Purpose |
|---|---|
| [`issue.md`](./issue.md) | Issue snapshot. |
| [`DATA-COLLECTION.md`](./DATA-COLLECTION.md) | Research commands, source links, source-code search notes, and metadata summary. |
| [`data/issue-86.json`](./data/issue-86.json) | Machine-readable issue metadata. |
| [`data/docker-sandbox-templates-tags.json`](./data/docker-sandbox-templates-tags.json) | Docker Hub metadata for Docker Sandboxes template images. |
| [`data/konard-box-latest-tag.json`](./data/konard-box-latest-tag.json) | Docker Hub metadata for `konard/box:latest`. |
| [`data/konard-box-dind-latest-tag.json`](./data/konard-box-dind-latest-tag.json) | Docker Hub metadata for `konard/box-dind:latest`. |
| [`data/docker-sbx-releases.json`](./data/docker-sbx-releases.json) | `docker/sbx-releases` repository metadata. |
| [`data/docker-sbx-releases-list.txt`](./data/docker-sbx-releases-list.txt) | Recent `sbx` release list. |
| [`data/docker-sbx-kits-contrib.json`](./data/docker-sbx-kits-contrib.json) | `docker/sbx-kits-contrib` repository metadata. |
| [`data/docker-sbx-kits-contrib-root.txt`](./data/docker-sbx-kits-contrib-root.txt) | Public kit repository root listing. |
| [`data/docker-code-search-sandbox-templates.txt`](./data/docker-code-search-sandbox-templates.txt) | Docker-owned GitHub code search results for `sandbox-templates`. |
| [`data/docker-docs-sandboxes-paths.txt`](./data/docker-docs-sandboxes-paths.txt) | Docker docs source path listing for Sandboxes docs. |

## Requirements Extracted From Issue #86

| ID | Requirement | Status in this PR |
|---|---|---|
| REQ-86.1 | Create a full comparison matrix in `./docs`. | Done in [`docs/docker-sandboxes-comparison.md`](../../docker-sandboxes-comparison.md). |
| REQ-86.2 | Exclude AI-related items because `box` is universal. | Done. AI-agent integrations are marked `Excluded` and not treated as gaps. |
| REQ-86.3 | Find image source if possible, otherwise use documentation. | Done. Public Dockerfile/source for `docker/sandbox-templates` images was not found in Docker-owned GitHub search results, so docs and Docker Hub metadata are used. |
| REQ-86.4 | List all missing best practices. | Done in the comparison matrix and the gap plan below. |
| REQ-86.5 | Clearly show where `box` is better. | Done in the matrix and the `Where box is better` section. |
| REQ-86.6 | Collect issue-related data under `docs/case-studies/issue-86`. | Done. Metadata and command outputs are preserved in `data/`. |
| REQ-86.7 | Search online for additional facts and data. | Done through Docker docs, Docker product page, Docker Hub API, GitHub repos, and GitHub code search. |
| REQ-86.8 | List each requirement from the issue. | Done in this table. |
| REQ-86.9 | Propose possible solutions and plans for each requirement. | Done in this case study and the root comparison document. |
| REQ-86.10 | Check known existing components/libraries that solve similar problems. | Done in the component table below. |
| REQ-86.11 | Execute everything in one PR. | Done in PR #87. |

## Source Findings

### Docker Sandboxes

Docker Sandboxes is an early-access `sbx` product documented as isolated
microVM sandboxes with per-sandbox filesystem, network, and Docker daemon
state. The docs describe:

- standalone `sbx` CLI install for macOS, Windows, and Ubuntu;
- KVM requirement on Ubuntu;
- Docker Desktop not required for current `sbx` usage;
- microVM isolation with a separate Linux kernel per sandbox;
- direct workspace mounts and same absolute workspace paths;
- branch mode based on Git worktrees under `.sbx/`;
- multiple workspaces with read-only options;
- private Docker Engine in `-docker` template variants;
- post-start port publishing with `sbx ports`;
- deny-by-default network policies with allow/deny rules and logs;
- host-side credential injection through an HTTP/HTTPS proxy;
- templates and saved template import/export;
- experimental kits for tools, files, env, credentials, network rules, and commands.

Public source found:

- `docker/sbx-releases`: public release metadata for the `sbx` binary.
- `docker/sbx-kits-contrib`: public kit examples, specs, tests, and helper code.
- `docker/docs`: public documentation source for Sandboxes docs.

Public source not found in this pass:

- Dockerfiles or build source for the published `docker/sandbox-templates`
image variants. The comparison therefore uses public documentation and Docker
Hub metadata for image-template behavior.

### `box`

The local repository provides:

- public Dockerfiles and installation scripts for Ubuntu 24.04 images;
- non-root `box` user;
- broad language/runtime coverage;
- theorem prover images;
- Playwright/Puppeteer browser dependency layer in the JS base;
- per-language modular images;
- full image assembled with multi-stage `COPY --from`;
- `dind-box` variants with Docker Engine, Buildx, Compose, and containerd;
- `DIND_DATA_ROOT`, storage-driver, log, wait, and daemon-skip runtime knobs;
- Docker Hub and GHCR publication;
- native amd64/arm64 build requirements and docs-only CI skip behavior.

## Missing Best Practices And Solution Plans

| Priority | Best practice from Docker Sandboxes | `box` gap | Solution plan |
|---|---|---|---|
| P0 | MicroVM isolation for untrusted work. | `box` is a container image and does not itself provide a hypervisor boundary. | Add a hardened runtime guide and evaluate Sysbox, Kata Containers, Firecracker, Cloud Hypervisor, Lima/Colima, QEMU, and gVisor tradeoffs. |
| P0 | Deny-by-default outbound network policy. | `box` has no egress policy store, allowlist, or network log. | Start with docs for `--network none`, internal Docker networks, and allowlisted proxies. Then design an optional launcher with policy files and logs. |
| P0 | Host-side credential proxying. | Secrets are passed manually through env, files, CLI state, or mounts. | Document safe credential flows first: SSH agent, Git credential helpers, Docker secrets, OS keychains, 1Password/pass/SOPS. Add a proxy only after a non-AI use case is clear. |
| P1 | Branch/worktree mode. | Users manage branches, worktrees, mounts, and cleanup manually. | Add a documented script or CLI wrapper that creates a Git worktree, runs `box`, and removes the disposable workspace. |
| P1 | Workspace trust checklist. | No dedicated docs for reviewing sandbox-modified hooks, CI files, build files, `.env`, IDE configs, or executables. | Add a security section to docs with review commands and risk examples. |
| P1 | Templates and declarative kits. | `box` supports Dockerfile extension but has no reusable feature/catalog layer. | Evaluate Dev Container Features, OCI artifacts, and a simple non-AI feature spec before inventing a new format. |
| P1 | DIND storage and resource governance. | `dind-box` has runtime knobs but lacks user-facing size/resource recipes. | Document `DIND_DATA_ROOT`, named Docker volumes, `--cpus`, `--memory`, `--pids-limit`, cleanup, and BuildKit cache options. |
| P1 | Port forwarding workflow. | Docker `-p` exists, but no `box`-specific post-start helper or convention. | Add Docker CLI and Compose examples; consider a launcher if lifecycle helpers are added. |
| P2 | Template snapshot import/export. | Docker supports `commit`/`save`/`load`, but no `box` workflow explains when this is appropriate. | Recommend Dockerfiles for reproducibility; document snapshots only for experiments. |
| P2 | Supply-chain metadata. | Public build source exists, but SBOM/provenance/scanning artifacts are not documented as a release output. | Evaluate Syft, Trivy, Grype, Docker Scout, cosign, SLSA, and in-toto for CI artifacts. |

## Known Components And Libraries To Evaluate

| Problem area | Existing components |
|---|---|
| MicroVM or stronger container isolation | Kata Containers, Firecracker, Cloud Hypervisor, QEMU, Lima, Colima, Sysbox, gVisor. |
| Docker-in-Docker safety | Sysbox, rootless Docker, Docker official `docker:dind`, fuse-overlayfs, BuildKit rootless mode. |
| Network policy and logging | Docker internal networks, Docker `--network none`, nftables, iptables, Cilium, Envoy, mitmproxy, Squid, tinyproxy, Open Policy Agent. |
| Secret and credential handling | Docker secrets, SSH agent forwarding, Git credential helpers, 1Password CLI, pass/gopass, SOPS, OS keychains. |
| Workspace lifecycle | Git worktree, Docker Compose, Dev Containers CLI/spec, Dagger, Make scripts. |
| Reusable environment features | Dev Container Features, OCI artifacts, Dockerfiles, Docker Compose profiles, Nix flakes, mise. |
| Supply-chain evidence | Syft, Grype, Trivy, Docker Scout, cosign, SLSA, in-toto. |
| Policy/spec validation | JSON Schema, CUE, Open Policy Agent/Rego, YAML schema validation. |

## Why `box` Should Not Copy AI-Specific Features

Docker Sandboxes includes built-in agent integrations for tools such as Claude
Code, Codex, Copilot, Gemini, OpenCode, Kiro, Droid, and Docker Agent. Those are
useful for Docker Sandboxes' product goal, but they are not requirements for
`box`. Adding those tools to the base image would make `box` heavier, less
universal, and more coupled to fast-changing AI products.

The reusable non-AI pattern is different: keep `box` as a public universal base
and let downstream images or future feature catalogs add agent-specific tools
when needed.

## Recommended Roadmap

1. Add documentation for secure `box` run profiles: minimal mounts, no host
Docker socket, optional Sysbox runtime, DIND storage volumes, resource
limits, and cleanup.
2. Add workspace trust guidance for disposable development boxes.
3. Prototype a small branch/worktree launcher in `experiments/` before adding
it as supported tooling.
4. Evaluate Dev Container Features or OCI artifacts as a non-AI feature system.
5. Add supply-chain metadata planning for SBOM, scanning, and provenance.
6. Revisit microVM-backed execution after the container-only workflow is fully
documented, because image source and runtime isolation are separate concerns.

## Validation

The requested docs were absent before this PR:

```bash
test -s docs/docker-sandboxes-comparison.md && test -s docs/case-studies/issue-86/CASE-STUDY.md
```

That command exited with status 1 before the docs were added. After this PR it
passes.

Validation run for this PR:

```bash
test -s docs/docker-sandboxes-comparison.md && test -s docs/case-studies/issue-86/CASE-STUDY.md && test -s docs/case-studies/issue-86/DATA-COLLECTION.md && test -s docs/case-studies/issue-86/issue.md
node -e "for (const f of ['docs/case-studies/issue-86/data/docker-sandbox-templates-tags.json','docs/case-studies/issue-86/data/konard-box-latest-tag.json','docs/case-studies/issue-86/data/konard-box-dind-latest-tag.json','docs/case-studies/issue-86/data/docker-sbx-releases.json','docs/case-studies/issue-86/data/docker-sbx-kits-contrib.json','docs/case-studies/issue-86/data/issue-86.json']) JSON.parse(require('fs').readFileSync(f,'utf8'));"
node -e "const fs=require('fs'), path=require('path'); const files=['docs/docker-sandboxes-comparison.md','docs/case-studies/issue-86/CASE-STUDY.md','docs/case-studies/issue-86/DATA-COLLECTION.md','docs/case-studies/issue-86/issue.md']; let bad=[]; for (const f of files) { const text=fs.readFileSync(f,'utf8'); for (const m of text.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) { const href=m[1].split('#')[0]; if (!href || /^[a-z]+:/i.test(href) || href.startsWith('mailto:')) continue; const p=path.resolve(path.dirname(f), href); if (!fs.existsSync(p)) bad.push(`${f}: ${m[1]}`); } } if (bad.length) { console.error(bad.join('\n')); process.exit(1); }"
git diff --check
```
105 changes: 105 additions & 0 deletions docs/case-studies/issue-86/DATA-COLLECTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Data Collection: Issue #86

Evidence date: 2026-05-10 UTC.

This folder preserves the local evidence and external metadata used to compare
Docker Sandboxes with `box`. Full upstream documentation pages were not copied
into this repository; the case study links to the public pages and stores the
commands plus compact metadata snapshots needed to reproduce the analysis.

## Preserved Files

| File | Purpose |
|---|---|
| [`issue.md`](./issue.md) | Human-readable issue snapshot. |
| [`data/issue-86.json`](./data/issue-86.json) | GitHub issue JSON with title, body, URL, timestamps, and comments. |
| [`data/docker-sandbox-templates-tags.json`](./data/docker-sandbox-templates-tags.json) | Docker Hub tag metadata for `docker/sandbox-templates`. |
| [`data/konard-box-latest-tag.json`](./data/konard-box-latest-tag.json) | Docker Hub tag metadata for `konard/box:latest`. |
| [`data/konard-box-dind-latest-tag.json`](./data/konard-box-dind-latest-tag.json) | Docker Hub tag metadata for `konard/box-dind:latest`. |
| [`data/docker-sbx-releases.json`](./data/docker-sbx-releases.json) | GitHub repository metadata for `docker/sbx-releases`. |
| [`data/docker-sbx-releases-list.txt`](./data/docker-sbx-releases-list.txt) | Recent `docker/sbx-releases` release list. |
| [`data/docker-sbx-kits-contrib.json`](./data/docker-sbx-kits-contrib.json) | GitHub repository metadata for `docker/sbx-kits-contrib`. |
| [`data/docker-sbx-kits-contrib-root.txt`](./data/docker-sbx-kits-contrib-root.txt) | Root directory listing for `docker/sbx-kits-contrib`. |
| [`data/docker-code-search-sandbox-templates.txt`](./data/docker-code-search-sandbox-templates.txt) | GitHub code search output for `sandbox-templates` in Docker-owned repositories. |
| [`data/docker-docs-sandboxes-paths.txt`](./data/docker-docs-sandboxes-paths.txt) | Top-level Docker docs paths under `content/manuals/ai/sandboxes`. |

## Commands Used

```bash
gh issue view https://github.com/link-foundation/box/issues/86 --json title,body,comments,url,createdAt,updatedAt
gh api repos/link-foundation/box/issues/86/comments --paginate
gh pr view 87 --repo link-foundation/box --json title,body,isDraft,url,headRefName,baseRefName,commits,statusCheckRollup
gh api repos/link-foundation/box/pulls/87/comments --paginate
gh api repos/link-foundation/box/issues/87/comments --paginate
gh api repos/link-foundation/box/pulls/87/reviews --paginate
gh search code --owner docker 'sandbox-templates' --limit 50
gh search code --owner docker 'DOCKER_SANDBOXES_DOCKER_SIZE' --limit 20
gh repo view docker/sbx-releases --json nameWithOwner,url,description,homepageUrl,updatedAt,licenseInfo,isPrivate
gh release list --repo docker/sbx-releases --limit 20
gh repo view docker/sbx-kits-contrib --json nameWithOwner,url,description,homepageUrl,updatedAt,licenseInfo,isPrivate
gh api repos/docker/sbx-kits-contrib/contents --jq '.[].name'
gh api repos/docker/docs/contents/content/manuals/ai/sandboxes?ref=main --jq '.[].path'
curl -fsSL 'https://hub.docker.com/v2/repositories/docker/sandbox-templates/tags?page_size=100'
curl -fsSL 'https://hub.docker.com/v2/repositories/konard/box/tags/latest'
curl -fsSL 'https://hub.docker.com/v2/repositories/konard/box-dind/tags/latest'
```

## Docker Sandboxes Source Findings

The public evidence found for Docker Sandboxes is split across documentation,
release metadata, template image metadata, and kit source:

| Artifact | Finding |
|---|---|
| `docker/sbx-releases` | Public release repository for `sbx`, with releases such as `v0.28.3` on 2026-04-29 and nightly releases. It did not expose template image Dockerfiles in the files inspected. |
| `docker/sbx-kits-contrib` | Public Apache-2.0 repository containing kit specs, examples, tests, and directories such as `code-server`, `trivy`, `mise`, `task`, and model-runner related kits. |
| `docker/docs` | Public docs contain the product behavior, template names, kit format, security model, policy commands, and Docker storage sizing variable. |
| `docker/sandbox-templates` Docker Hub metadata | Public image tags and manifests exist. Source Dockerfiles for these template images were not found in Docker-owned GitHub code search results during this pass. |

Because public template image source was not found, the comparison treats
Docker's docs and Docker Hub metadata as the authoritative public evidence for
template features.

## Docker Hub Metadata Summary

| Image/tag | Docker Hub reported size | Last updated | Relevant notes |
|---|---:|---|---|
| `docker/sandbox-templates:shell` | 485.8 MiB | 2026-05-09 | Generic no-agent template. |
| `docker/sandbox-templates:shell-docker` | 550.0 MiB | 2026-05-06 | Generic template with Docker Engine inside. |
| `docker/sandbox-templates:codex` | 664.6 MiB | 2026-05-06 | AI-specific, excluded from gaps. |
| `docker/sandbox-templates:codex-docker` | 728.8 MiB | 2026-05-06 | AI-specific, excluded from gaps. |
| `docker/sandbox-templates:opencode-docker` | 964.7 MiB | 2026-05-06 | AI-specific, excluded from gaps. |
| `konard/box:latest` | 5.47 GiB on amd64 | 2026-05-01 | Full universal `box` image. |
| `konard/box-dind:latest` | 5.59 GiB on amd64 | 2026-05-01 | Full universal `box` image plus Docker-in-Docker. |

Docker Hub tag `full_size` is registry-reported compressed image metadata and
should be used only as an approximate comparison point. The `box` full image is
larger because it intentionally includes many language runtimes and tools.

## Local `box` Evidence Read

| Local file | Evidence used |
|---|---|
| [`README.md`](../../../README.md) | Runtime/tool list, modular image matrix, registry links, dind-box description, DIND security notes. |
| [`REQUIREMENTS.md`](../../../REQUIREMENTS.md) | Functional requirements, security requirements, multi-arch requirements, local-first install policy. |
| [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) | Build architecture, multi-stage assembly, native ARM64 policy, modular design. |
| [`Dockerfile`](../../../Dockerfile) and [`ubuntu/24.04/full-box/Dockerfile`](../../../ubuntu/24.04/full-box/Dockerfile) | Full image assembly and system packages. |
| [`ubuntu/24.04/js/Dockerfile`](../../../ubuntu/24.04/js/Dockerfile) | Non-root `box` user and browser automation dependencies. |
| [`ubuntu/24.04/dind/Dockerfile`](../../../ubuntu/24.04/dind/Dockerfile) | DIND layer design and private daemon comments. |
| [`ubuntu/24.04/dind/install.sh`](../../../ubuntu/24.04/dind/install.sh) | Docker Engine, CLI, Buildx, Compose, containerd, and fuse-overlayfs installation. |
| [`ubuntu/24.04/dind/dind-entrypoint.sh`](../../../ubuntu/24.04/dind/dind-entrypoint.sh) | Runtime knobs for `DIND_DATA_ROOT`, storage driver, daemon wait, and user handoff. |

## Official Docker Documentation Links

- Docker Sandboxes product page: https://www.docker.com/products/docker-sandboxes/
- Docker Sandboxes docs: https://docs.docker.com/ai/sandboxes/
- Get started: https://docs.docker.com/ai/sandboxes/get-started/
- Architecture: https://docs.docker.com/ai/sandboxes/architecture/
- Usage: https://docs.docker.com/ai/sandboxes/usage/
- Isolation: https://docs.docker.com/ai/sandboxes/security/isolation/
- Default security posture: https://docs.docker.com/ai/sandboxes/security/defaults/
- Policies: https://docs.docker.com/ai/sandboxes/security/policy/
- Credentials: https://docs.docker.com/ai/sandboxes/security/credentials/
- Workspace trust: https://docs.docker.com/ai/sandboxes/security/workspace/
- Templates: https://docs.docker.com/ai/sandboxes/customize/templates/
- Kits: https://docs.docker.com/ai/sandboxes/customize/kits/
Loading
Loading