Hand DevBox a ticket. It plans the change, writes the code, runs the tests,
reviews its own work and opens a draft pull request. You review and merge.
Comment on the pull request, and it pushes the fix to the same branch.
DevBox runs on your infrastructure, with your model keys. It is built for a
whole engineering org: one shared harness that picks up Linear tickets,
answers on GitHub pull requests, works across your repos, and remembers what
it learned in them.
Why we built it
We are RudderStack, a customer data infrastructure company. Since April our
engineers have handed tickets to DevBox. Today it merges about 35% of our
internal pull requests, with about an 80% merge rate.
Read the story behind it.
Coding tools like Claude Code and Codex make one developer faster. We wanted the
other half: a shared teammate the whole org can delegate to, that runs where our
code and secrets already live, and that gets better at our repos over time.
DevBox works alongside those tools.
Features
- Staged, gated pipeline. Orientation, planning, plan review, implementation, self-review. No code is written until the plan passes review.
- Closed feedback loop. Review comments, @mentions and failed CI runs route back to the running task (with the GitHub App).
- Versioned memory. Learnings are distilled into your repo and land as a commit on the pull request, reviewed like code.
- Credential isolation. Sandboxes hold placeholder tokens. An egress proxy injects the real ones and scopes writes to your repos.
- Per-stage model routing. OpenAI or Anthropic, with model and reasoning effort set per stage.
- Self-hosted. Docker Compose or Kubernetes, one isolated sandbox per task.
How it works
- The control plane (
control-plane/) stores tasks, starts a sandbox for
each one through OpenSandbox and
relays messages and progress. It makes no LLM calls.
- The harness (
harness/) runs in the sandbox, built on
DeepAgents, and takes the task
from plan to pull request.
- iron-proxy sits between the sandboxes and GitHub and the LLM. It swaps
dummy tokens for real ones and allows writes only to your repos.
docs/architecture.md has the details.
Quickstart
About 15 minutes, most of it the first image build. The steps assume macOS; see the notes below for Linux.
You need: Docker Desktop
with 8 GB of memory for Docker (Compose 2.13 or newer),
Bun 1.4.4 or newer, make, openssl, a GitHub token or
gh logged in, and an OpenAI or Anthropic API key.
-
Get the code.
git clone https://github.com/rudderlabs/devbox.git && cd devbox
[!TIP]
Set it up with Claude Code. Run claude in this directory and ask
it to help you set up DevBox. The repo ships a DevBox skill
(.claude/skills/devbox, also /devbox): Claude checks your tools,
writes devbox.config.json with you, and hands you the
bun run quickstart command to run. Run it yourself, in another terminal
or with a ! in front in Claude Code, so you type your keys at its hidden
prompts and they never go through the chat. Other coding agents can read
the same skill in skills/devbox/.
-
Pick your repo and model. Copy the example config, then set your repo's
URL and your LLM in it.
cp devbox.config.example.json devbox.config.json
{
"repos": [{ "url": "https://github.com/your-org/your-repo.git", "branch": "main" }],
"llm": { "provider": "openai", "baseUrl": "https://api.openai.com/v1", "model": "gpt-5.6-sol" }
}
DevBox only ever writes to the repos listed here.
Anthropic and per-stage models: docs/configuration.md.
Or skip this step: when there is no devbox.config.json, bun run quickstart
asks for your repos and model and writes it.
-
Start DevBox.
bun run quickstart
It checks your config and the tools you need, and asks whether to run on Docker Compose or a local kind cluster and whether to set up Linear and the GitHub App now (say no for a first try; Next steps adds them later). Then it starts DevBox with bun run up, which asks for your GitHub token (or takes it from gh) and your LLM key, and offers to save them in the macOS Keychain, never in a file. It builds the images (about 10 minutes the first time) and logs the CLI in.
-
Give it a task.
bun run devbox create "Add a /health endpoint to your-org/your-repo"
It prints the task's key, for example DBX-API-1.
Explore the CLI: bun run devbox --help lists every command: ls,
show, wait, restart and more.
[!WARNING]
Linux: add your user to the docker group
(sudo usermod -aG docker $USER, then log out and back in). bun run up
uses the Secret Service (libsecret) instead of the Keychain.
[!TIP]
On a corporate network or VPN that blocks public DNS, run
bun run up --dns-resolver <host:port> with a DNS server that works there.
After you change devbox.config.json, run bun run up again. After you
change the model, try it on a new task.
Task lifecycle
Next steps
Run tasks from Linear (recommended)
Delegate an issue to DevBox, or @mention it, and it moves the issue to started, posts its progress in the issue's agent session and opens a draft
pull request. Follow-ups in the session reach the task. Nobody on the team
needs the CLI.
Linear sends webhooks, so it needs a public HTTPS URL that reaches port 3000
on your machine. With ngrok:
ngrok http 3000 # in another terminal
bun run linear:setup --public-url https://<your-tunnel-host> # registers the app in Linear
bun run up # applies it
bun run linear:status # checks the URL reaches DevBox
linear:setup opens Linear's "create app" page, filled in for you. Click
Create, then paste the client ID and the two secrets it asks for.
[!IMPORTANT]
Tunnels on a laptop. A free tunnel gets a new URL each time it restarts,
and Linear keeps sending to the old one. Use a URL that doesn't change: a
free ngrok static domain
(ngrok http --url=<your-domain> 3000) or a named
Cloudflare tunnel.
If the URL changed anyway, see
When the public URL changes.
If delegating does nothing, bun run linear:status tells you whether the
URL reaches DevBox, and Troubleshooting
maps each message to a fix.
docs/linear.md covers Kubernetes, private teams and
rotating secrets.
Let your team @mention DevBox on pull requests (GitHub App)
Your token alone is enough for DevBox to open pull requests. A GitHub App adds:
commits from a bot instead of your account, tokens that refresh on their own,
and @<app> mentions, reviews and failed CI runs on its pull requests that
reach the task.
bun run github:setup --public-url https://<your-tunnel-host> # same URL as Linear
bun run up
bun run github:status
docs/github.md covers the modes, trust lists and token scope.
Teach DevBox your repo
Put your conventions and build and test commands in AGENTS.md, CLAUDE.md
or .agents/knowledge/. DevBox reads them before every task and adds what it
learns there in each pull request
(docs/extending.md).
Run on Kubernetes
A Helm chart runs each task in its own pod, with the same egress proxy. Try it
locally with bun run k8s:kind, then follow
docs/kubernetes/README.md for the installer,
GitOps and the Amazon EKS guide.
Manage secrets
bun run secrets ls shows what DevBox saved in your keychain, and
bun run secrets rm <NAME> removes one. Environment variables
(GITHUB_TOKEN, LLM_API_KEY) win over saved values
(docs/configuration.md).
Secure by default
- No real secrets in the sandbox. The proxy adds them on the way out
(where secrets go).
- Writes only to your repos. Everything else on GitHub is read-only
(what iron-proxy allows).
- Only trusted commenters. It reads pull request comments only from orgs
and users you list. The list is empty by default
(trust settings).
- No keys in files. Your GitHub token and model key live in your keychain
or environment, never in the config (secrets).
To report a vulnerability, see SECURITY.md.
Not in v1
- GitHub only. No GitLab or Bitbucket.
- Two LLM APIs: OpenAI's Responses API and Anthropic's Messages API. A
self-hosted model needs a server that speaks the Responses API with
reasoning, on port 80 or 443 under a DNS name.
- New tasks come from the CLI and Linear. On GitHub, DevBox only picks up
follow-ups on its own pull requests; it doesn't start work from GitHub
issues. Slack gets only completion updates for Linear tasks. No Jira and no
web UI.
- Stopping a task from Linear isn't supported yet.
- No stable extension interface. docs/extending.md shows where hooks would go.
FAQ
It works on its own branch and opens draft pull requests. Merging stays with you, and your branch protection rules still apply.
Your code stays in your sandboxes and on GitHub. What the model needs to see goes to the LLM endpoint you configure, as with any coding tool.
No. DevBox sends nothing to RudderStack. Tracing with Langfuse is optional, off by default, and goes to the Langfuse instance you set up.
The keys are never in the sandbox, so there is nothing to steal there. DevBox reads pull request comments only from people you trust. See Secure by default.
With a personal token, DevBox acts as you. Set up the GitHub App to get a bot identity.
No. The CLI does everything. Linear makes it a team tool: anyone can delegate an issue and follow along without the CLI.
No. Those help one developer at the keyboard, and we use them every day.
DevBox is the org's shared harness that picks up tickets in the background.
Docs
License
DevBox is open source and licensed under the MIT License.
