Skip to content
Back to search

sandbox

Fast cold-boot MicroVM sandboxes for AI agents on cocoon

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cocoonstack/sandbox with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cocoonstack/sandbox'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cocoonstack--sandbox/badge.svg)](/listings/cocoonstack--sandbox)

HTML

<a href="/listings/cocoonstack--sandbox"><img src="/api/listings/cocoonstack--sandbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # sandbox
  2. MicroVM sandboxes for AI agents, built on
  3. [cocoon](https://github.com/cocoonstack/cocoon): a fast-boot guest stack, an
  4. in-guest product daemon, a per-node control plane with warm pools, and SDKs
  5. for Go and Python. Warm claims are sub-millisecond; a pool miss clones from a
  6. golden snapshot in tens of milliseconds; cold boot is ~0.2–0.4 s on bare metal.
  7. **Documentation: [cocoonstack.github.io/sandbox](https://cocoonstack.github.io/sandbox/)**
  8. (source in [`docs/`](docs/)); the architecture overview is in
  9. [`docs/index.md`](docs/index.md).
  10. ## Quick start
  11. On a Linux node with KVM, [cocoon](https://github.com/cocoonstack/cocoon) v0.6.9
  12. or newer, Cloud Hypervisor and `jq`, as root, from a checkout with Go installed.
  13. Not on a node that already runs sandboxd on the same cocoon root: at start
  14. sandboxd removes every `sbx-` VM it does not own.
  15. ```bash
  16. make sandboxd
  17. cocoon image pull ghcr.io/cocoonstack/sandbox/rt:24.04
  18. cat >config.json <<'EOF'
  19. {
  20. "listen": "127.0.0.1:7777",
  21. "api_token": "change-me",
  22. "pools": [
  23. {"template": "ghcr.io/cocoonstack/sandbox/rt:24.04", "net": "none", "size": "small", "warm": 2}
  24. ]
  25. }
  26. EOF
  27. dist/sandboxd -config config.json &
  28. # Wait for the golden snapshot and the warm pool.
  29. until curl -sf -H 'Authorization: Bearer change-me' http://127.0.0.1:7777/v1/info |
  30. jq -e '(.pools | length) > 0 and all(.pools[]; .golden and .warm >= .target)' >/dev/null; do sleep 1; done
  31. # Claim, exec and release three times; prints each latency.
  32. (cd e2e && GOWORK=off go run ./cmd/demo -addr 127.0.0.1:7777 -token change-me \
  33. -template ghcr.io/cocoonstack/sandbox/rt:24.04)
  34. ```
  35. A stopped sandboxd leaves its VMs for the next start. To remove them:
  36. ```bash
  37. kill %1
  38. cocoon vm list --format json | jq -r '.[].config.name | select(startswith("sbx-"))' |
  39. while read -r vm; do cocoon vm stop --force "$vm"; cocoon vm rm --force "$vm"; done
  40. ```
  41. `demo` is a small program over the [Go SDK](docs/sdk.md); the
  42. [Python SDK](docs/sdk-python.md) has the same calls. [Deploying
  43. sandboxd](docs/deploy.md) covers release binaries, the full config and systemd.
  44. ## Related projects
  45. - [cocoon](https://github.com/cocoonstack/cocoon) — the microVM engine underneath
  46. - [vk-sandbox](https://github.com/cocoonstack/vk-sandbox) — the Kubernetes provider that claims from sandboxd
  47. - [sandbox-operator](https://github.com/cocoonstack/sandbox-operator) — the Kubernetes apiserver and e2b-compatible data plane over warm pools
  48. ## Layout
  49. - `silkd/` — in-guest product daemon (Rust), baked into the base image;
  50. newline-JSON frames over vsock 2048 ([reference](docs/silkd.md))
  51. - `sandboxd/` — per-node control plane (Go): warm pools, the claim API and the
  52. relays to silkd ([deploy](docs/deploy.md), [API](docs/sandboxd-api.md))
  53. - `sdk/go/` — [Go SDK](docs/sdk.md); `sdk/go/silkd/` is its connection layer
  54. and `sdk/go/silkd/silkdtest/` a test fake
  55. - `sdk/python/` — [Python SDK](docs/sdk-python.md), stdlib-only and synchronous
  56. - `mcp/` — `sandbox-mcp`, an [MCP](docs/mcp.md) stdio server
  57. - `sdk/openai/` — `cocoonstack-sandbox-openai`, a sandbox provider for the
  58. [OpenAI Agents SDK](docs/openai-adapter.md)
  59. - `sdk/langchain/` — `cocoonstack-sandbox-langchain`, a
  60. [LangChain toolkit](docs/langchain.md)
  61. - `protocol/wire/` — the frame vocabulary and `fixtures/`, the golden corpus the
  62. Rust, Go and Python tests check, so wire drift fails CI
  63. - `e2e/` — in-process full-stack tests (real pool/engine/relay/SDK, fake
  64. cocoon + guest) and the [bare-metal drivers](docs/deploy.md#acceptance-drivers)
  65. - `boot/kernel/` — kernel version pin (`VERSION` + matching tarball `SHA256`,
  66. bump both together) and config fragments
  67. - `boot/init/` — `sandbox-init`, the entire initramfs userland (static Rust)
  68. - `boot/Dockerfile` — multi-stage: kernel → init → cpio → scratch image with
  69. `/boot/vmlinuz-sandbox` + `/boot/initrd.img-sandbox`
  70. - `os-image/` — VM images consuming the boot artifact: `base`, `rt`, `python`,
  71. `python-rt`, `node`, `node-rt`, `browser`, `android`, `e2b-rt`, `e2b-ci`
  72. - `scripts/` — benchmarks and bare-metal e2e, see
  73. [Verifying a node](docs/deploy.md#verifying-a-node)
  74. - `packaging/` — the systemd unit deploy installs
  75. ## CI
  76. - `silkd.yml` / `sandboxd.yml` — Rust and Go test+lint suites
  77. - `boot-init.yml` — the boot/init crate's own fmt+clippy+test gate
  78. - `python.yml` — ruff + pytest for the three Python packages, mypy for the
  79. base SDK
  80. - `shell.yml` — shellcheck over every tracked shell script
  81. - `images.yml` — the single image entry point: on a push touching
  82. `boot/**`, `silkd/**`, or `os-image/**` it builds the
  83. changed carriers (via `build-carrier.yml`,
  84. `workflow_call`) then os-images, in order, so the chain is deterministic
  85. - `build-os-images.yml` — bakes base + flavors FROM the carriers, sha-pinned
  86. when rebuilt in the same run
  87. - `release.yml` — on a version tag, checks the tag against silkd's version,
  88. then builds the release binaries and archives
  89. - `publish-pypi.yml` — on an `sdk-*-v*` tag, builds and publishes the
  90. matching package via PyPI Trusted Publishing (OIDC, per-package
  91. environment)
  92. ## Boot chain
  93. ```
  94. cloud-hypervisor
  95. → guest kernel (amd64: PVH ELF vmlinux, everything =y, no decompress stage; arm64: flat Image)
  96. → uncompressed ~1.5MB cpio: /init = sandbox-init (static Rust)
  97. → resolve virtio-blk serials via sysfs (2ms poll, no udev)
  98. → mount EROFS layers → overlayfs + ext4 COW → switch_root
  99. → exec /sbin/init (systemd, trimmed; cocoon-agent + silkd start at sysinit)
  100. ```
  101. The cmdline keys `sandbox-init` consumes are in the
  102. [boot contract](docs/deploy.md#boot-contract).
  103. ## Development
  104. ```bash
  105. make help # every target; the ones below are the daily set
  106. make lint test # Rust: boot/init + silkd (fmt --check, clippy -D warnings, tests)
  107. make go-lint # Go: protocol/wire + sandboxd + sdk/go + e2e + mcp, GOOS linux AND darwin
  108. make go-test # Go: go test -race plus one pass of every benchmark, across the Go modules
  109. make sh-lint # shellcheck every tracked shell script
  110. make sandboxd # build dist/sandboxd
  111. make bench # claim-tier + data-plane benchmarks; removes every sbx-* VM
  112. make boot # kernel + initramfs artifact image (docker)
  113. make silkd-image # silkd release binary in a scratch carrier image
  114. make images # base + python images against the local boot + silkd images
  115. ```
  116. ## License
  117. The server stack — sandboxd, silkd, the boot chain, the OS images, and the
  118. MCP server — is a product, and is licensed under [AGPL-3.0](LICENSE). The client SDKs
  119. (`sdk/go`, `sdk/python`, `sdk/openai`, `sdk/langchain`) and the
  120. `protocol/wire` module the Go SDK requires are licensed under Apache-2.0
  121. (see the `LICENSE` file in each directory) and carry no copyleft obligation.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.