How Devboxes works
Understand projects, blueprints, runs, sessions, and the machines that execute the work.
A task starts with a repository and a result you need. Devboxes gives the coding agent an environment to work in and keeps its instructions, activity, and outcomes available to your team.
The parts you work with
| Term | What it means |
|---|---|
| Organization | Your team's projects, members, integrations, and shared configuration. |
| Project | A repository and the environment in which its tasks run. |
| Workspace image | The container image containing the tools a project needs. |
| Runner | A connected machine or cloud worker that starts task containers. |
| Provider account | A connection to a model provider, using a supported subscription or API key. |
| Blueprint | A versioned sequence of commands, agent tasks, or supported integration steps. |
| Run | One execution of a task. It has a status, steps, and an outcome. |
| Session | The continuing conversation and work history. A follow-up can create another run in the same session. |
From request to outcome
Choose a project and blueprint, select an available model, and describe the task. Devboxes checks the configuration and queues the run. An eligible runner starts it when its environment and credentials are ready.
Open the session to follow progress. The transcript shows the agent's work and requests for input. The review view shows captured changes. A run can produce a summary, private files, or published results such as a pull request; it can also report a publication failure separately from work already completed.
Send related follow-up work to the same session. Use a new task for unrelated work so instructions and review remain easy to follow.
Choose where tasks run
A self-hosted runner uses Docker on a machine you connect with the Devboxes CLI. Devboxes Cloud is available only when enabled for your deployment. Both need access to the selected model and repository.
Connecting a runner is different from hosting Devboxes itself. You can use the hosted dashboard while running task containers on your own machine.
Choose how to start work
Use the dashboard for setup, live sessions, and review. Use the CLI to start tasks from a repository checkout or inspect results in scripts. A configured chat integration lets a team request work from its chat workspace. The MCP server exposes the same task operations to other agents.
Start with the first-task guide, or ask your team which existing project and blueprint to use.