agentbox README

The project's README from github.com/madarco/agentbox. As one markdown file: README.md.

AgentBox 

Run multiple agents in parallel, with a single command, on your PC, self-hosted, or in the cloud

Works with iterm2 - cmux - tmux - Herdr

AgentBox

How it works

agentbox claude # launch a new VM with claude and your project inside

Full Documentation

Complete setup:

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

AgentBox demo

Install

npm -g install @madarco/agentbox

Want to help test what's coming? npm -g install @madarco/agentbox@nightly puts you on the nightly channel — 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 or OrbStack), 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)

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

Access

Inspect

Lifecycle

Sync & state

Advanced

Run agentbox <command> --help for command-specific options.

Documentation

Full documentation lives at agent-box.sh/docs:

Development

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.

Menu-bar tray app (dev)

The macOS tray app lives in the sibling repo ../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:

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), with no changes to AgentBox. Build and test against the bundled example provider locally:

# 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 (and the authoring reference docs/provider-plugins.md). Reference packages: examples/agentbox-provider-sample (stub) and examples/agentbox-provider-example (a real, Vercel-backed provider).

Contributing

Bug reports, docs fixes, and provider work are welcome — see CONTRIBUTING.md. First-time contributors sign a one-line CLA on their first pull request. Security issues go through SECURITY.md, not a public issue.

For new sandbox providers, see Build a provider and the authoring reference docs/provider-plugins.md.

Author

Marco D'Alia - @madarco - Linkedin

License

MIT. See LICENSE.

agentbox (madarco/agentbox)

Searching Database…

538 ·GitHub
Agentbox
Что это такое?AgentBox — это CLI-утилита, которая запускает несколько кодинг-агентов параллельно, каждый в своей изолированной виртуальной машине, одной командой — на вашем ПК, на своём сервере или в облаке.
Это программа, которую я ставлю на свой компьютер, или сервис, работающий в облаке?Это CLI, который вы запускаете на своей машине; создаваемые «коробки» могут быть локальными Docker-контейнерами, вашим собственным удалённым сервером по SSH или облачными песочницами вроде Hetzner, Vercel, E2B или DigitalOcean.
Как запустить свою первую «коробку»?Выполните 'agentbox create' или 'agentbox claude', чтобы сразу запустить Claude Code. При самом первом запуске собирается Docker-образ agentbox/box:dev (~1 ГБ, один раз); 'agentbox install' — это мастер настройки облачных провайдеров.
Что нужно установить заранее, чтобы всё заработало?Docker — для локальных «коробок». Для облачных провайдеров нужен токен: добавьте его через 'agentbox install' или команды входа вроде 'agentbox vercel login' (сохраняется в ~/.agentbox/secrets.env); удалённый Docker просто использует ваш ~/.ssh/config.
Есть ли подводные камни?Да: первая сборка образа скачивает около 1 ГБ, Daytona помечен как поддерживаемый лишь частично, а live-снапшоты там пока экспериментальные.
Что входит в каждую «коробку»?Полноценный компьютер: отдельный браузер, общий доступ к экрану, постоянные шеллы и уже разогретая среда VS Code / Cursor IDE, а скиллы и плагины для Claude Code, Codex и OpenCode копируются туда автоматически.
Зачем нужны чекпоинты?Чекпоинт — это «тёплый» снапшот состояния «коробки»; 'agentbox checkpoint create' делает такой снимок, чтобы новые «коробки» стартовали с него, а не загружались с нуля.
Можно ли запускать «коробки» на инфраструктуре, которая не поддерживается из коробки?Да — провайдеры сделаны как плагины: вы публикуете npm-пакет на основе @madarco/agentbox-provider-sdk, и AgentBox запускает агентов в вашем облаке, без каких-либо изменений в самом AgentBox.
Есть ли приложение в строке меню на macOS?Да — 'agentbox install app' кладёт нотаризованное приложение в трей в /Applications, а 'agentbox app' запускает или останавливает его из командной строки.
What are similar projects?openrig, ordewell, pstack-claude, context-mode, operator-memory, claudecodeui, happy, arc-code
Which topics is it in?iterm2, herdr-plugin, remote-development, agent-sandbox, parallel, tmux, sandboxing, virtual-machine, vps, codex-cli, virtualization, ide
Creator
madarco
Size
46.4 MB
Stars
538
Updated
CommitSep 23Releasetray-latestSep 21
Age
5mo
Commits · 90 Days