rudderlabs/devbox

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.

Watch the full launch video (2 min)

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.

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.

• 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.

• 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.

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.

1. 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/.

2. 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.

3. 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.

4. 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.

5. Watch it work.

   bun run devbox logs -f DBX-API-1

   You see it orient, plan, review its plan, implement, test and review its own diff. At the end, a draft pull request opens on your repo, under your GitHub account.

6. Ask for changes.

   bun run devbox send DBX-API-1 "Also add a test"

   It pushes new commits to the same pull request.

7. Stop it.

   bun run down

   Your tasks are kept for the next bun run up. bun run reset deletes them.

Explore the CLI: bun run devbox --help lists every command: ls, show, wait, restart and more.

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.

docs/linear.md covers Kubernetes, private teams and rotating secrets.

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.

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).

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.

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).

• 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.

• 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.

• docs/configuration.md: devbox.config.json, secrets and the keychain, environment variables, trust settings, per-stage models.
• docs/architecture.md: the components, how the control plane and the harness talk, and the task states.
• docs/linear.md: connecting DevBox to Linear.
• docs/github.md: connecting DevBox to GitHub as an App.
• docs/kubernetes/README.md: running DevBox on Kubernetes.
• docs/extending.md: where DevBox could be extended. Not a stable interface.
• CONTRIBUTING.md: running the tests and lint.

DevBox is open source and licensed under the MIT License.