devbox — Claude Code skill: what it does, how to install
devbox is a Claude Code skill that runs a coding agent on your own infrastructure to handle repository tasks. It plans, implements, reviews work, and opens draft pull requests.
MIT ★ 341 updated 2026-11-17
npx skills add rudderlabs/devbox --skill devbox -a claude-codeWhat devbox does
The agent processes tasks from CLI, Linear, Jira, ClickUp, or GitHub mentions. Every task gets a dedicated sandbox via iron-proxy, which swaps dummy tokens for real ones to ensure security. Infrastructure management runs via bun run scripts in the repository root.
Running the agent requires bun installed on the host. You must configure devbox.config.json and provide API keys in the system keychain or environment variables. Destructive actions like bun run reset require explicit user confirmation. Without a valid configuration or proper --target file for Kubernetes, the agent cannot initialize the sandbox or connect to integrations.
What it helps with
- automate pull request creation from tasks
- integrate coding agent with Linear or Jira
- diagnose integration status with built-in commands
- deploy agent infrastructure via Docker Compose or K8s
Example prompts for the agent
bun run devbox createto submit a new taskbun run github:statusto verify GitHub connectivity! bun run k8s:install --target <file>to deploy on Kubernetes
How to install devbox
1Skills CLI (Vercel)
npx skills add rudderlabs/devbox --skill devbox -a claude-code2Manually: put the files in place
~/.claude/skills/devbox/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/devbox/
1Skills CLI (Vercel)
npx skills add rudderlabs/devbox --skill devbox -a codex2Manually: put the files in place
.agents/skills/devbox/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rudderlabs/devbox --skill devbox -a cursor2Manually: put the files in place
.cursor/skills/devbox/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rudderlabs/devbox skills/devbox2Manually: put the files in place
.github/skills/devbox/SKILL.md1Skills CLI (Vercel)
npx skills add rudderlabs/devbox --skill devbox -a gemini-cli2Platform CLI
gemini skills install https://github.com/rudderlabs/devbox --path skills/devboxManually: put the files in place
.devin/skills/devbox/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about devbox
How to install devbox in Claude Code?
Run npx skills add rudderlabs/devbox --skill devbox -a claude-code in your project terminal.
What does devbox do?
It acts as a self-hosted coding agent that plans, writes, reviews code, and submits draft pull requests based on incoming issues.
What is required to run devbox?
You need bun installed, a configured devbox.config.json file, and necessary secrets stored in your system keychain or environment variables.
Source text
SKILL.md · MIT
---
name: devbox
description: How devbox works and how to run it — the self-hosted coding agent that takes a task, opens a draft pull request and takes follow-ups. Use when setting devbox up (bun run quickstart, devbox.config.json, Docker Compose, kind, Kubernetes, Helm, GitOps, EKS), when using it (bun run devbox create/logs/send, CLI profiles), when connecting the GitHub App, GitLab, Linear, Jira, ClickUp or Slack, when upgrading or uninstalling it, or when something about it fails (bun run up, k8s:install, *:status, iron-proxy, sandboxes, secrets, the keychain, tunnels).
---
# devbox
devbox is a coding agent that runs on the user's own infrastructure and works
on their GitHub repos. A task goes in through the CLI (or a Linear or Jira
issue, a ClickUp task, or a GitHub `@mention`); the agent plans, implements,
reviews its own work and opens a draft pull request; follow-ups push new
commits to the same pull request.
```
devbox CLI ──HTTP──> control plane ──OpenSandbox──> sandbox, one per task (harness)
(API, Postgres) │ dummy tokens
v
iron-proxy ── real tokens ──> GitHub, LLM
```
The sandbox never holds a real credential: iron-proxy swaps dummy tokens for
the real ones and allows writes only to the configured repos. Details:
[docs/architecture.md](../../docs/architecture.md).
## Rules for working with devbox
- **Run every command from the root of the devbox repo.** All commands are
`bun run <script>` from its `package.json`.
- **Never put a secret in a file, a command line or the chat.** devbox finds
secrets itself: the environment, then the system keychain, then
`gh auth token` (GitHub token only), then a hidden prompt. If one is missing,
tell the user which variable it is and let them provide it
([docs/configuration.md#secrets](../../docs/configuration.md#secrets)).
- **Hidden prompts need a terminal you don't have.** `bun run quickstart`,
`up`, `k8s:install`, `k8s:kind` and the `*:setup` commands may ask questions.
Pass the flags that answer them ahead, and when a secret is still needed,
ask the user to run the command themselves (in Claude Code: `! bun run …`).
- **Ask before destructive commands:** `bun run reset` (deletes the database
and every task's workspace), `k8s:uninstall --purge`, `*:disable --forget`,
`bun run secrets rm|clear`.
- **Diagnose with the status commands first:** `github:status`,
`linear:status`, `jira:status`, `clickup:status`, `k8s:check`,
`bun run devbox show <task>`.
- **Read the linked doc before changing a setting** instead of guessing a
field: the config parsers reject unknown keys.
## What do you need?
| Goal | Read |
|---|---|
| Set devbox up on this machine for the first time | [references/quickstart.md](references/quickstart.md) |
| Run tasks, follow them, switch control planes | [references/using.md](references/using.md) |
| Connect the GitHub App, GitLab, Linear, Jira, ClickUp or Slack | [references/integrations.md](references/integrations.md) |
| Run on Kubernetes: installer, GitOps, EKS, upgrade, uninstall | [references/kubernetes.md](references/kubernetes.md) |
| Something fails | [references/troubleshooting.md](references/troubleshooting.md) |
## Deployment modes
| Mode | Where it runs | Start / apply | Config |
|---|---|---|---|
| Docker Compose | this machine | `bun run up` (or `bun run quickstart --compose`) | `devbox.config.json` |
| kind | a local Kubernetes cluster in Docker | `bun run k8s:kind` (or `bun run quickstart --kind`) | `devbox.config.json` + `devbox.kind.json` |
| Kubernetes, installer | any cluster | `bun run k8s:install --target <file>` | `devbox.config.json` + the target file |
| Kubernetes, GitOps | any cluster | the Helm chart in `deploy/helm/devbox` | Helm values + your own Secrets |
`devbox.config.json` holds `repos` and `llm` for every mode. On Compose it also
holds `publicUrl`, `integrations`, `github` (trust lists) and `sandbox`. On
Kubernetes those live in the target file (`--target`) instead
([docs/configuration.md](../../docs/configuration.md)).
## Commands
| Command | Does |
|---|---|
| `bun run quickstart` | To a running local devbox, with chosen integrations; writes `devbox.config.json` from the user's answers when there is none |
| `bun run up` / `bun run down` / `bun run reset` | Start, stop (keeps tasks), or wipe the Compose stack |
| `bun run devbox <command>` | The CLI: `create`, `ls`, `show`, `logs`, `send`, `wait`, `restart`, `whoami`, `profile` |
| `bun run secrets ls\|rm\|clear` | Show or remove the secrets saved in the keychain |
| `bun run github:setup\|status\|disable` | The GitHub App |
| `bun run linear:setup\|status\|disable` | Linear |
| `bun run gitlab:setup\|status\|disable` | GitLab merge request notes and pipelines |
| `bun run jira:setup\|status\|disable` | Jira |
| `bun run clickup:setup\|status\|disable` | ClickUp |
| `bun run k8s:kind` | A local kind cluster with devbox installed |
| `bun run k8s:install\|connect\|check\|refresh-snapshot\|uninstall` | Kubernetes, with `--target <file>` |
The integration commands act on Compose without `--target`, and on that
Kubernetes deployment with it (`--target devbox.kind.json` on kind).
## What devbox does not do (v1)
Say so instead of looking for a way around it:
- Code hosts: GitHub, and GitLab (gitlab.com or self-managed, one instance
per deployment). No Bitbucket. [docs/gitlab.md](../../docs/gitlab.md).
- 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.
- Work comes in from the CLI, Linear, Jira (Cloud only), ClickUp (one
workspace per deployment) and GitHub, plus GitLab merge request notes and
failed pipelines. Slack only gets completion updates for Linear tasks. No
web UI.
- A task can't be stopped from Linear, Jira or ClickUp yet. A ClickUp
automation never starts work.
- No stable extension interface ([docs/extending.md](../../docs/extending.md)).
© rudderlabs · MIT · rudderlabs/devbox