Boxes is a web-based orchestrator for AI coding agents, similar to Claude Code on the web. It runs Claude Code and OpenAI Codex over the Agent Client Protocol (ACP).
Each box is a Docker container with a workspace, a home directory and a Nix store. It contains one or more threads, and each thread is one conversation with one agent. Threads of the same box share the workspace, so Claude and Codex can work on the same checkout.
Note
This project is mostly vibe coded. I know what I am doing and have a good general idea of the architecture - but I will not pretend to have read much of the code. This is a personal project to scratch my own itch.
- Isolation. Each box is a docker container of its own, with a private network and its own files. An agent installs
the tools it needs with
nix, and they stay in the box across restarts and image updates. - Controlled egress. A private network has no route to the outside. The egress proxy is the only way out, and it optionally limits which hosts the processes in a box can reach.
- Credentials that stay out of the box. You enter a credential on the settings page. The processes in a box see a placeholder only, and the proxy puts the real credential on the wire.
- Parallel threads. Several threads can run on one checkout, which keeps the context of each conversation small. A turn continues even when you close the browser.
- Built-in review tool. Read, comment on and edit the files of a workspace, with Git change marks, and hand the comments back to the agent.
- Terminal access. A shell in the box, as the same user as the agent, attached to a persistent tmux session.
- Agent sets. A named collection of an
AGENTS.mdfile and skills. A set can also take skills from Git repositories. One global set applies to every box, and a box can add one more. - Push notifications. The browser tells you when a thread needs a decision, even when no tab is open. You can install Boxes as a Progressive Web App (PWA).
Note
As mentioned above, this is a personal project. The documentation below is not so much to help you use Boxes (though it probably would) but to help me make sure this project stays on course and works as intended.
- Quickstart — Deploy with Docker Compose, put a reverse proxy in front, and do the first steps in the dashboard
- Docker Compose setup — The services, the volume and the Docker socket
- Environment variables — Every variable the orchestrator reads, and its default
- Credentials — The credentials Boxes uses, how to enter them, and their path into a box
- Boxes — Create, suspend and delete a box, and what is in one
- Box status — The status badges in the box list and the box details
- Threads — Start, fork and end a conversation with an agent
- Code review — Inspect, comment on and edit the files of a workspace
- Terminal — An interactive shell in a box
- Agent sets — Give the agents instructions and skills
- Built-in skills — The skills the box image carries, and how to replace one
- Push notifications — Let the browser tell you when a thread needs you
- Glossary — The terms the documentation uses
- Orchestrator — The service that serves the dashboard and drives Docker
- Agent communication — The way the dashboard, the orchestrator and an agent speak ACP
- Egress proxy — Host filtering and credential injection
- Storage — The contents of the data volume, and the files a box keeps
- REST API — The HTTP API under
/apiused by the dashboard - Development — Repository layout, technologies and tests