How devboxes works

devboxes runs coding agents on your repositories. You describe a task in plain language. An agent works on it in its own branch and reports back with its commits and a summary. When the task's Blueprint publishes the commits, devboxes also opens a pull request for the branch.

Where work comes from

You can start tasks from these places:

• Claude Code or Codex, through the devboxes MCP server.
• The devboxes CLI in your terminal.
• Slack, Microsoft Teams, Google Chat, Discord, or Telegram, by mentioning @devboxes.
• Linear or Jira, by delegating or assigning an issue to devboxes.
• GitHub, by labelling an issue devboxes.
• CI or your own integration, with a delegation token.

All of them run the same devboxes operations, so a task works the same way wherever it started.

Organizations

An Organization is your team in devboxes. Projects, Blueprints, and Sessions belong to it, and you can belong to several Organizations. A member's role decides which operations they can run.

Projects

A Project is one repository and branch that devboxes works on, or a taskbox whose tasks use only your connected tools. The Project sets the model, the Runner, and the workspace that its tasks use. The workspace holds the packages and services that your repository needs, so an agent can install, build, and test your code.

Blueprints

A Blueprint describes a kind of work that your team asks devboxes to do again and again, for example fixing bugs. A Blueprint is a graph of steps: agent steps with their instructions and the results you expect, your repository's own commands such as its tests, publishing the commits, and a Review. Its edges decide which step runs next, so a Blueprint can publish only when the tests pass. It also holds the actions the agent may take.

A task uses one committed version of a Blueprint. A committed version never changes, so a running task keeps the steps and permissions it started with. To change a Blueprint, you commit a new version. Blueprints and approvals explains how a task runs the graph.

Sessions and Runs

A Session is one task. devboxes works on it in its own branch, so you can review its commits on their own. The branch is named after the Session's title, such as devboxes/add-contributing-md-1a2b3c4d. A Run is one stretch of agent work inside a Session. When you give a Session more work, the next Run picks up where the last one stopped, on the same branch.

Runners

A Runner is a machine of yours with Docker that runs your agents, for example a build server. A Project runs its tasks either on capacity that devboxes manages or on one of your Runners.

Paying for work

Up to 3 Runs at once on your own Runners cost nothing in devboxes; Runs beyond those take paid Runner slots. Work on capacity that devboxes manages is paid from the monthly usage that Basic and Premium include, and from prepaid credit. Your model provider bills the model usage to your model account. See How billing works.

Review

A Review is a second agent that checks the pull request of a finished task. The reviewer reports findings and does not change the code itself. If you allow fixes, devboxes starts an agent that fixes the findings and then checks the result again. A person merges, on GitHub or by asking devboxes to merge it, unless the Project lets devboxes merge a pull request once its Review approves it and its checks pass. Review and merging explains when devboxes merges.

Chat and issue trackers

In a connected Slack, Microsoft Teams, Google Chat, Discord, or Telegram channel, people mention @devboxes and ask for work. devboxes answers in the thread, starts tasks in the channel's Projects, and posts results and questions in the same thread. When the Chat policy allows it, people can also ask about every other task in those Projects, except tasks from an issue tracker and tasks of an erased conversation. They can continue such a task unless another open thread is working on it, and cancel it from any of those threads when their own request started its latest work.

In Linear or Jira, an issue that you delegate or assign to devboxes starts work in the bound Project, and so does a GitHub issue that you label devboxes. devboxes answers on the issue and posts results as comments.

Anyone who can post in a connected channel can start tasks in its Projects, even without membership in your Organization. devboxes in Chat explains who can act in a channel.

Personas and memory

A Persona is optional text that shapes how devboxes answers in Chat and on issues: a name, a voice, and instructions. Without one, devboxes answers as itself.

Organization memory holds what your team wants devboxes to know in every conversation, such as conventions, corrections and facts about your work. devboxes reads it whenever it answers, and saves to it what people in a channel say is meant for everyone. It records who added each entry and where it came from. Every member can add, replace and erase entries.

Your preferences tell devboxes how you like it to work with you. devboxes applies them when it answers you in a thread you wrote in, so people in that thread can notice their effect. Only you can list them.

Delegation tokens

A delegation token lets an agent, a CI job, or your own integration act for you without your account. The token has fine-grained permissions and runs only the operations you grant, in one Organization and within what your role allows. A token expires after the time you choose, or works until you revoke it. See delegations.