Skip to content
Back to search

agentbox

Run multiple agents in parallel sandboxed VMs, with a single command, on your PC or in the cloud

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

Its scripts were only partly scanned.

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/madarco/agentbox 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/madarco/agentbox'

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/madarco--agentbox/badge.svg)](/listings/madarco--agentbox)

HTML

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

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm -g install @madarco/agentbox
agentbox install

# Launch a new VM with claude, copy all your settings and workspace
agentbox claude

# Also install required project libraries and launch your dev server
> Run setup wizard? -> Yes

# Also use a cloud:
agentbox hetzner claude # or vercel, daytona

# Ctrl+a d to detach, claude keep going, to reconnect later:
agentbox attach 1

# To open a persistent shell inside the box:
agentbox shell 1

# Create a second box:
agentbox claude
agentbox attach 2
agentbox shell 2

# Open your web project on a .local url tunnel on your pc
agentbox url 2
# Or the in-box browser via webVNC:
agentbox screen 2
# Or connect to vscode/cursor inside the box:
agentbox code 2

# See status and quickly switch between agents:
agentbox dashboard

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.

.claude-plugin/plugin.json · Manifest · 22 lines
  1. {
  2. "name": "agentbox",
  3. "version": "0.1.0",
  4. "description": "Drive AgentBox from Claude Code on the host: create isolated sandboxes for coding agents, run them in parallel, queue background jobs, push via the host relay.",
  5. "author": {
  6. "name": "Marco D'Alia"
  7. },
  8. "homepage": "https://github.com/madarco/agentbox",
  9. "repository": "https://github.com/madarco/agentbox",
  10. "license": "MIT",
  11. "keywords": [
  12. "claude-code",
  13. "agentbox",
  14. "sandbox",
  15. "docker",
  16. "hetzner",
  17. "daytona"
  18. ],
  19. "skills": [
  20. "./skills/"
  21. ]
  22. }
README.md · README · 220 lines
  1. <h1 style="font-weight:normal">
  2. AgentBox&nbsp;
  3. <a href="./LICENSE"><img src="https://img.shields.io/github/license/madarco/agentbox.svg?colorB=ff0000"></a>
  4. <a href="https://www.npmjs.com/package/@madarco/agentbox"><img src="https://img.shields.io/npm/d18m/%40madarco%2Fagentbox?label=npm" /></a>
  5. <img src="https://img.shields.io/github/stars/madarco/agentbox" />
  6. </h1>
  7. Run multiple agents in parallel, with a single command, on your PC, self-hosted, or in the cloud
  8. Works with [iterm2](https://agent-box.sh/docs/integrations-iterm2) - [cmux](https://agent-box.sh/docs/integrations-cmux) - [tmux](https://agent-box.sh/docs/integrations-tmux) - [Herdr](https://agent-box.sh/docs/integrations-herdr)
  9. <br>
  10. <p align="center">
  11. ![AgentBox](./docs/cover.jpg)
  12. </p>
  13. ## How it works
  14. ```sh
  15. agentbox claude # launch a new VM with claude and your project inside
  16. ```
  17. - 📦 **Teleport** - Move your project to a dedicated VM, local or in the cloud, with a single command.
  18. - 🤖 **Automatic** - Bring all your skills, plugins, and settings for **Claude Code**, **Codex**, **Open Code**
  19. - 🌐 **A full Computer** — Dedicated browser, screen sharing, persistent shells and warmed up VS Code / Cursor IDE, with each box.
  20. - 💾 **Checkpoints** — Sub <1s startup of new boxes from a previous checkpoint, auto pause to save cost/resources when not in use.
  21. - 🔒 **Safe** - Your git credentials are kept on your local machine, with permission requests to push to the remote repository.
  22. Full [Documentation](https://agent-box.sh/docs)
  23. ### Complete setup:
  24. ```sh
  25. npm -g install @madarco/agentbox
  26. agentbox install
  27. # Launch a new VM with claude, copy all your settings and workspace
  28. agentbox claude
  29. # Also install required project libraries and launch your dev server
  30. > Run setup wizard? -> Yes
  31. # Also use a cloud:
  32. agentbox hetzner claude # or vercel, daytona
  33. # Ctrl+a d to detach, claude keep going, to reconnect later:
  34. agentbox attach 1
  35. # To open a persistent shell inside the box:
  36. agentbox shell 1
  37. # Create a second box:
  38. agentbox claude
  39. agentbox attach 2
  40. agentbox shell 2
  41. # Open your web project on a .local url tunnel on your pc
  42. agentbox url 2
  43. # Or the in-box browser via webVNC:
  44. agentbox screen 2
  45. # Or connect to vscode/cursor inside the box:
  46. agentbox code 2
  47. # See status and quickly switch between agents:
  48. agentbox dashboard
  49. ```
  50. ## Demo
  51. ![AgentBox demo](docs/demo.gif)
  52. ## Install
  53. ```sh
  54. npm -g install @madarco/agentbox
  55. ```
  56. Want to help test what's coming? `npm -g install @madarco/agentbox@nightly` puts you on the
  57. [nightly channel](https://agent-box.sh/docs/nightly) — pre-release builds, with stable releases still
  58. reaching you automatically. `agentbox self-update --channel stable` opts back out.
  59. Requirements: macOS (arm64 or Intel) or Linux, Docker ([Docker Desktop](https://www.docker.com/products/docker-desktop/) or [OrbStack](https://orbstack.dev/)), Node `>=20.10`. The first `agentbox create` / `agentbox claude` builds the `agentbox/box:dev` image (~1 GB, one-time).
  60. Uses `portless` to give box web apps the same URL from inside the box and on the host.
  61. ## Cloud Providers
  62. | | local docker | remote docker | hetzner | daytona | vercel | e2b |
  63. | ------------------- | ------------------------- | ---------------------- | ---------------------- | ------------------ | ------------------ | ------------------ |
  64. | Support | ✅ | ✅ | ✅ | ⚠️ Partial | ✅ | ✅ |
  65. | Base image | Dockerfile | Dockerfile (on the remote) | Setup script (Ubuntu) | Dockerfile | Setup script | Dockerfile (`Template.build`) |
  66. | Live snapshots | ✅ | ✅ (`docker commit`) | ✅ | 🧪 Experimental | ✅ | ✅ |
  67. | Private preview URLs| ✅ (portless or OrbStack) | ✅ (portless over SSH) | ✅ (portless) | ✅ (native) | ✅ (native) | ✅ (native) |
  68. **Cloud setup** (optional — skip for local Docker)
  69. - `agentbox install` — interactive setup wizard to choose which providers to use and configure them.
  70. - `agentbox vercel login` — interactive Vercel Sandbox token setup, saved to `~/.agentbox/secrets.env`
  71. - `agentbox hetzner login` — interactive Hetzner Cloud token setup, saved to `~/.agentbox/secrets.env`
  72. - `agentbox daytona login` — interactive Daytona API key setup, saved to `~/.agentbox/secrets.env`
  73. - `agentbox e2b login` — interactive E2B API key setup, saved to `~/.agentbox/secrets.env`
  74. - `agentbox digitalocean login` — interactive DigitalOcean Personal Access Token setup, saved to `~/.agentbox/secrets.env`
  75. - `agentbox remote-docker doctor <host>` — run boxes on a machine you already own, over SSH. No login and no token: it connects as you, using your own `~/.ssh/config`. Then `agentbox docker:<host> claude`.
  76. - `agentbox prepare [--provider daytona|hetzner|vercel|e2b|digitalocean|docker:<host>]` — build the image and initial snapshot (e2b builds from a Dockerfile via `Template.build()`)
  77. - `agentbox hetzner claude`, `agentbox hetzner codex`, `agentbox hetzner create`, etc.
  78. ## How to use
  79. `<box>` is optional almost everywhere — it defaults to the box for the current project, or use its short index (`1`, `2`, …), name, or id prefix.
  80. **Create & run**
  81. - `agentbox create` — Create and start a new agent box (Docker container with FUSE overlay)
  82. - `agentbox claude` — Create a sandboxed box and launch Claude Code in a detachable tmux session
  83. **Access**
  84. - `agentbox url` — Open a box's web app URL in the browser (even with no `expose:` service)
  85. - `agentbox screen` — Open a box's VNC (noVNC) viewer in the browser
  86. - `agentbox code` — Open a box in VS Code or Cursor via the Dev Containers extension
  87. - `agentbox shell` — Open an interactive bash shell in a box
  88. - `agentbox open` — Open a box's merged workspace in Finder
  89. - `agentbox logs` — Print recent log lines from a box service; `-f` to stream
  90. - `agentbox dashboard` — Box list + the selected box's live agent session
  91. **Inspect**
  92. - `agentbox list` (`ls`) — List boxes in current project or `-g` for all
  93. - `agentbox status` — Show service + task status from a box's `agentbox-ctl` daemon
  94. - `agentbox top` — Live resource monitor (cpu/mem/pids/disk) for a box, project, or all boxes
  95. **Lifecycle**
  96. - `agentbox start` — Start a stopped box (docker start + re-mount the FUSE overlay)
  97. - `agentbox stop` — Stop a box (preserves the upper volume, `node_modules` included)
  98. - `agentbox destroy` (`rm`) — Destroy a box and discard its upper volume
  99. - `agentbox pause` / `agentbox unpause` — Freeze / resume a box (sub-second)
  100. **Sync & state**
  101. - `agentbox download` — Download a box's `/workspace` back into your host workspace (gitignore-aware)
  102. - `agentbox cp <src> [dst]` — Copy individual files between host and box (like `docker cp`; direction picked by `name:` prefix)
  103. - `agentbox checkpoint` (alias `checkpoints`) — List and manage project checkpoints (warm box state to start new boxes from); bare command lists, `checkpoint create` captures
  104. **Advanced**
  105. - `agentbox wait` — Block until the box reports all autostart units ready
  106. - `agentbox prune` — Clean up orphan state records (and with `--all`, orphan docker resources)
  107. - `agentbox self-update` — Update agentbox, wipe the box image so it rebuilds, reload the relay
  108. - `agentbox config` — Read / write layered config (global, per-project, workspace `defaults:`)
  109. - `agentbox relay` — Manage the host relay process (`status` / `stop` / `start` / `restart`)
  110. - `agentbox app` — Control the macOS menu-bar app process (`status` / `start` / `stop` / `restart`); install it with `agentbox install app`
  111. Run `agentbox <command> --help` for command-specific options.
  112. ## Documentation
  113. Full documentation lives at **[agent-box.sh/docs](https://agent-box.sh/docs)**:
  114. - [Quickstart](https://agent-box.sh/docs) and [Core concepts](https://agent-box.sh/docs/core-concepts)
  115. - [Teleport a project](https://agent-box.sh/docs/teleport-a-project), [Run an agent](https://agent-box.sh/docs/run-an-agent), [Access your box](https://agent-box.sh/docs/access-your-box)
  116. - [Configuration](https://agent-box.sh/docs/configuration), [Services & tasks](https://agent-box.sh/docs/services-and-tasks), [Sync & git](https://agent-box.sh/docs/sync-and-git)
  117. - Cloud providers: [Hetzner](https://agent-box.sh/docs/hetzner), [Daytona](https://agent-box.sh/docs/daytona), [Vercel](https://agent-box.sh/docs/vercel), [E2B](https://agent-box.sh/docs/e2b), [DigitalOcean](https://agent-box.sh/docs/digitalocean)
  118. - Full [CLI reference](https://agent-box.sh/docs/cli)
  119. ## Development
  120. ```sh
  121. git clone https://github.com/madarco/agentbox && cd agentbox
  122. pnpm install && pnpm build
  123. node apps/cli/dist/index.js --help
  124. ```
  125. The full development workflow, stack, end-to-end smoke tests, and teardown live in [`docs/development.md`](./docs/development.md).
  126. ### Menu-bar tray app (dev)
  127. The macOS tray app lives in the sibling repo [`../agentbox-tray`](https://github.com/madarco/agentbox-tray). When you have it checked out next to this repo, these scripts build and run your **local** dev build (ad-hoc signed, at `../agentbox-tray/AgentBoxTray.app`) — separate from the notarized copy `agentbox install app` puts in `/Applications`:
  128. ```sh
  129. pnpm tray:dev # rebuild the dev .app and relaunch it (the one you'll use most)
  130. pnpm tray:build # just rebuild (scripts/make-app.sh)
  131. pnpm tray:start # launch the dev build
  132. pnpm tray:stop # quit any running instance
  133. pnpm tray:restart # quit + relaunch the dev build
  134. ```
  135. > Note: `agentbox app start|restart` targets the **installed** `/Applications` copy, not this dev build. Use the `pnpm tray:*` scripts while iterating on the tray here; run `agentbox install app` to refresh `/Applications` from the current CLI build.
  136. ### Custom providers (plugins)
  137. AgentBox's provider surface is open — you can run agents on your own cloud/infra by shipping a **provider plugin** (its own npm package built on [`@madarco/agentbox-provider-sdk`](https://www.npmjs.com/package/@madarco/agentbox-provider-sdk)), with no changes to AgentBox. Build and test against the bundled example provider locally:
  138. ```sh
  139. # build the SDK, then build + register the example provider
  140. pnpm --filter @madarco/agentbox-provider-sdk build
  141. cd examples/agentbox-provider-example && npm install && npm run build
  142. node ../../apps/cli/dist/index.js plugin add . # register it
  143. node ../../apps/cli/dist/index.js doctor # shows the provider's group
  144. # verify the SDK artifact in isolation (packs + installs the tarball, asserts exports)
  145. pnpm --filter @madarco/agentbox-provider-sdk pack:test
  146. ```
  147. Full guide: [Build a provider](https://agent-box.sh/docs/build-a-provider) (and the authoring reference [`docs/provider-plugins.md`](./docs/provider-plugins.md)). Reference packages: [`examples/agentbox-provider-sample`](./examples/agentbox-provider-sample) (stub) and [`examples/agentbox-provider-example`](./examples/agentbox-provider-example) (a real, Vercel-backed provider).
  148. # Contributing
  149. Bug reports, docs fixes, and provider work are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). First-time contributors sign a one-line [CLA](./.github/CLA.md) on their first pull request. Security issues go through [SECURITY.md](./SECURITY.md), not a public issue.
  150. For new sandbox providers, see [Build a provider](https://agent-box.sh/docs/build-a-provider) and the authoring reference [`docs/provider-plugins.md`](./docs/provider-plugins.md).
  151. # Author
  152. [Marco D'Alia](https://www.madarco.net) - [@madarco](https://x.com/madarco) - [Linkedin](https://www.linkedin.com/in/marcodalia/)
  153. # License
  154. MIT. See [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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