Overview
The four Devboxes objects, runner paths, and guide reading order.
Devboxes runs AI coding agents against your repositories. You dispatch a task, a runner executes it inside an isolated container, and you watch the transcript, answer questions, review the diff, and receive the result.
The four things you work with
| Object | What it is | Start here |
|---|---|---|
| Project | A repository paired with the container image its runs use | Creating a project |
| Blueprint | The ordered shell and agent steps for a run | Blueprints |
| Agent session | One run's transcript, prompts, result, diff, and controls | Agent sessions |
| Runner | A dashboard-managed machine or your own registered Docker machine | Install the CLI |
A dispatch from the dashboard, the Devboxes CLI, or Slack creates the same kind of run. It waits until a runner can serve the selected model provider, then works through the blueprint until it completes, fails, or you stop it.
Where provider credentials live
| Your runner machine | Dashboard-managed runner | |
|---|---|---|
| Credential source | Encrypted device store or a local auth-file reference | Organization encrypted store |
| Configure | devboxes credentials setup | Model providers |
| Share with every runner | devboxes credentials sync | Already organization-wide |
Devboxes rejects a new dispatch when no matching provider credential is available. If availability disappears after acceptance, the run stays Queued until a matching runner can claim it. Inside a task container, credentials live only on memory-backed storage.
Anyone who can dispatch to your runner can execute code in a container that receives the selected provider credential. Treat organization membership, the Docker host, and every synced or local credential as one trust boundary. See Security.
Read this guide in order
Invited as a member of an existing organization? Start with Working as a member. Otherwise follow this thread:
- Install the CLI
- Quickstart
- Devboxes CLI
- Dispatch from Slack
- Repository connections
- Creating a project
- Blueprints
- Dispatching runs
- Agent sessions
- Managing credentials
- Roles & access
- Working as a member
- Configuration
- Security
- Troubleshooting
Choose your next task
Install the CLI
Choose the npm package or a standalone runner binary.
Join existing work
Follow runs in an organization someone else configured.
Review the trust boundary
Decide where to run containers and which credentials to expose.
Next: Install the CLI — putting the devboxes command
on your machine.