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.
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
Markdown
[](/listings/madarco--agentbox)HTML
<a href="/listings/madarco--agentbox"><img src="/api/listings/madarco--agentbox/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- {
- "name": "agentbox",
- "version": "0.1.0",
- "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.",
- "author": {
- "name": "Marco D'Alia"
- },
- "homepage": "https://github.com/madarco/agentbox",
- "repository": "https://github.com/madarco/agentbox",
- "license": "MIT",
- "keywords": [
- "claude-code",
- "agentbox",
- "sandbox",
- "docker",
- "hetzner",
- "daytona"
- ],
- "skills": [
- "./skills/"
- ]
- }
README.md · README · 220 lines
- <h1 style="font-weight:normal">
- AgentBox
- <a href="./LICENSE"><img src="https://img.shields.io/github/license/madarco/agentbox.svg?colorB=ff0000"></a>
- <a href="https://www.npmjs.com/package/@madarco/agentbox"><img src="https://img.shields.io/npm/d18m/%40madarco%2Fagentbox?label=npm" /></a>
- <img src="https://img.shields.io/github/stars/madarco/agentbox" />
- </h1>
- Run multiple agents in parallel, with a single command, on your PC, self-hosted, or in the cloud
- 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)
- <br>
- <p align="center">
- 
- </p>
- ## How it works
- ```sh
- agentbox claude # launch a new VM with claude and your project inside
- ```
- - 📦 **Teleport** - Move your project to a dedicated VM, local or in the cloud, with a single command.
- - 🤖 **Automatic** - Bring all your skills, plugins, and settings for **Claude Code**, **Codex**, **Open Code**
- - 🌐 **A full Computer** — Dedicated browser, screen sharing, persistent shells and warmed up VS Code / Cursor IDE, with each box.
- - 💾 **Checkpoints** — Sub <1s startup of new boxes from a previous checkpoint, auto pause to save cost/resources when not in use.
- - 🔒 **Safe** - Your git credentials are kept on your local machine, with permission requests to push to the remote repository.
- Full [Documentation](https://agent-box.sh/docs)
- ### Complete setup:
- ```sh
- 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
- ```
- ## Demo
- 
- ## Install
- ```sh
- npm -g install @madarco/agentbox
- ```
- Want to help test what's coming? `npm -g install @madarco/agentbox@nightly` puts you on the
- [nightly channel](https://agent-box.sh/docs/nightly) — pre-release builds, with stable releases still
- reaching you automatically. `agentbox self-update --channel stable` opts back out.
- 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).
- Uses `portless` to give box web apps the same URL from inside the box and on the host.
- ## Cloud Providers
- | | local docker | remote docker | hetzner | daytona | vercel | e2b |
- | ------------------- | ------------------------- | ---------------------- | ---------------------- | ------------------ | ------------------ | ------------------ |
- | Support | ✅ | ✅ | ✅ | ⚠️ Partial | ✅ | ✅ |
- | Base image | Dockerfile | Dockerfile (on the remote) | Setup script (Ubuntu) | Dockerfile | Setup script | Dockerfile (`Template.build`) |
- | Live snapshots | ✅ | ✅ (`docker commit`) | ✅ | 🧪 Experimental | ✅ | ✅ |
- | Private preview URLs| ✅ (portless or OrbStack) | ✅ (portless over SSH) | ✅ (portless) | ✅ (native) | ✅ (native) | ✅ (native) |
- **Cloud setup** (optional — skip for local Docker)
- - `agentbox install` — interactive setup wizard to choose which providers to use and configure them.
- - `agentbox vercel login` — interactive Vercel Sandbox token setup, saved to `~/.agentbox/secrets.env`
- - `agentbox hetzner login` — interactive Hetzner Cloud token setup, saved to `~/.agentbox/secrets.env`
- - `agentbox daytona login` — interactive Daytona API key setup, saved to `~/.agentbox/secrets.env`
- - `agentbox e2b login` — interactive E2B API key setup, saved to `~/.agentbox/secrets.env`
- - `agentbox digitalocean login` — interactive DigitalOcean Personal Access Token setup, saved to `~/.agentbox/secrets.env`
- - `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`.
- - `agentbox prepare [--provider daytona|hetzner|vercel|e2b|digitalocean|docker:<host>]` — build the image and initial snapshot (e2b builds from a Dockerfile via `Template.build()`)
- - `agentbox hetzner claude`, `agentbox hetzner codex`, `agentbox hetzner create`, etc.
- ## How to use
- `<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.
- **Create & run**
- - `agentbox create` — Create and start a new agent box (Docker container with FUSE overlay)
- - `agentbox claude` — Create a sandboxed box and launch Claude Code in a detachable tmux session
- **Access**
- - `agentbox url` — Open a box's web app URL in the browser (even with no `expose:` service)
- - `agentbox screen` — Open a box's VNC (noVNC) viewer in the browser
- - `agentbox code` — Open a box in VS Code or Cursor via the Dev Containers extension
- - `agentbox shell` — Open an interactive bash shell in a box
- - `agentbox open` — Open a box's merged workspace in Finder
- - `agentbox logs` — Print recent log lines from a box service; `-f` to stream
- - `agentbox dashboard` — Box list + the selected box's live agent session
- **Inspect**
- - `agentbox list` (`ls`) — List boxes in current project or `-g` for all
- - `agentbox status` — Show service + task status from a box's `agentbox-ctl` daemon
- - `agentbox top` — Live resource monitor (cpu/mem/pids/disk) for a box, project, or all boxes
- **Lifecycle**
- - `agentbox start` — Start a stopped box (docker start + re-mount the FUSE overlay)
- - `agentbox stop` — Stop a box (preserves the upper volume, `node_modules` included)
- - `agentbox destroy` (`rm`) — Destroy a box and discard its upper volume
- - `agentbox pause` / `agentbox unpause` — Freeze / resume a box (sub-second)
- **Sync & state**
- - `agentbox download` — Download a box's `/workspace` back into your host workspace (gitignore-aware)
- - `agentbox cp <src> [dst]` — Copy individual files between host and box (like `docker cp`; direction picked by `name:` prefix)
- - `agentbox checkpoint` (alias `checkpoints`) — List and manage project checkpoints (warm box state to start new boxes from); bare command lists, `checkpoint create` captures
- **Advanced**
- - `agentbox wait` — Block until the box reports all autostart units ready
- - `agentbox prune` — Clean up orphan state records (and with `--all`, orphan docker resources)
- - `agentbox self-update` — Update agentbox, wipe the box image so it rebuilds, reload the relay
- - `agentbox config` — Read / write layered config (global, per-project, workspace `defaults:`)
- - `agentbox relay` — Manage the host relay process (`status` / `stop` / `start` / `restart`)
- - `agentbox app` — Control the macOS menu-bar app process (`status` / `start` / `stop` / `restart`); install it with `agentbox install app`
- Run `agentbox <command> --help` for command-specific options.
- ## Documentation
- Full documentation lives at **[agent-box.sh/docs](https://agent-box.sh/docs)**:
- - [Quickstart](https://agent-box.sh/docs) and [Core concepts](https://agent-box.sh/docs/core-concepts)
- - [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)
- - [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)
- - 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)
- - Full [CLI reference](https://agent-box.sh/docs/cli)
- ## Development
- ```sh
- git clone https://github.com/madarco/agentbox && cd agentbox
- pnpm install && pnpm build
- node apps/cli/dist/index.js --help
- ```
- The full development workflow, stack, end-to-end smoke tests, and teardown live in [`docs/development.md`](./docs/development.md).
- ### Menu-bar tray app (dev)
- 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`:
- ```sh
- pnpm tray:dev # rebuild the dev .app and relaunch it (the one you'll use most)
- pnpm tray:build # just rebuild (scripts/make-app.sh)
- pnpm tray:start # launch the dev build
- pnpm tray:stop # quit any running instance
- pnpm tray:restart # quit + relaunch the dev build
- ```
- > 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.
- ### Custom providers (plugins)
- 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:
- ```sh
- # build the SDK, then build + register the example provider
- pnpm --filter @madarco/agentbox-provider-sdk build
- cd examples/agentbox-provider-example && npm install && npm run build
- node ../../apps/cli/dist/index.js plugin add . # register it
- node ../../apps/cli/dist/index.js doctor # shows the provider's group
- # verify the SDK artifact in isolation (packs + installs the tarball, asserts exports)
- pnpm --filter @madarco/agentbox-provider-sdk pack:test
- ```
- 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).
- # Contributing
- 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.
- 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).
- # Author
- [Marco D'Alia](https://www.madarco.net) - [@madarco](https://x.com/madarco) - [Linkedin](https://www.linkedin.com/in/marcodalia/)
- # License
- MIT. See [LICENSE](./LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.