Create a Project

A Project is one repository and branch that devboxes works on, or a taskbox without a repository. Owners and admins create Projects.

The onboarding prompt creates a Project for your repository, with a workspace that holds everything the repository needs. After you create a Project, set up its workspace and give its agents variables and secrets.

Create a Project

To do it yourself:

You need a repository connection, a model account, and a Runner.

{
  "organizationId": "<organization id>",
  "name": "Web app",
  "repository": {
    "connection": { "kind": "manual", "id": "<connection id>" },
    "repositoryFullName": "my-org/web-app",
    "branch": "main"
  },
  "runnerMachineId": "<runner id>",
  "modelSelection": {
    "candidates": [{ "accountId": "<model account id>", "modelId": "claude-sonnet-4-5" }],
    "outputTokenLimit": 8192
  }
}

devboxes invoke projects.create --input @project.json

Use "kind": "github-app" with the installation's id when you connected GitHub with the App. branch is the branch that new tasks start from. For a taskbox, use "repository": null. runnerMachineId is the Runner that runs the Project's tasks; use null to run them on capacity that devboxes manages in Germany, unless the Organization runs tasks only on its own Runners. On that capacity, machineSize sets the machine of each task; without it, the Project uses medium.

The result contains the Project's id. devboxes starts preparing the Project's workspace. You can start tasks right away. The first one begins when the workspace is ready. For a Project with a repository on capacity that devboxes manages, devboxes also reads the repository and sets the workspace's packages and services for you, unless you set them first. An agent does this reading on devboxes' own model, not on your model account, and devboxes charges for neither its compute nor its model. The agent also records what the repository uses and the checks devboxes recommends adding, and projects.list shows it as stackProfile.

projects.list shows where this reading stands as onboarding, and where devboxes' check of the Project's workspace stands as calibration. Each has a status of running, succeeded, failed or refused. devboxes reads and checks repositories for an Organization a limited number of times in 30 days. Past that, or while devboxes' own model is unavailable, a reading or check is refused, and code is SYSTEM_MODEL_ALLOWANCE_USED or SYSTEM_MODEL_UNAVAILABLE. One that stopped at the model's usage limit has the code SYSTEM_MODEL_USAGE_LIMIT. When the reading didn't succeed, set the workspace's packages and services yourself.

Create a taskbox

A taskbox is a Project without a repository, for work that only uses your connected tools, such as a weekly report from your support inbox. Create it with "repository": null and no other repository fields. Its tasks start in an empty workspace, and the files an agent writes there carry over to the next task of the same Session.

A taskbox has no branch, pull request, or code Review. Work with a Blueprint that has a publish node or binds a repositories operation fails with REPOSITORY_REQUIRED, and naming a repository connection in projects.configure fails with REPOSITORY_UNAVAILABLE. projects.list shows a taskbox with repositoryId: null.

Choose a machine size

Each task on capacity that devboxes manages gets a machine of its own, of the Project's machineSize:

Choose large or xl when a build or test run needs more memory than medium has, such as a large Next.js build. Once devboxes has checked the Project's workspace, projects.list shows the size it recommends for the Project's work as recommendedMachineSize; change machineSize to follow it. Each size has its own hourly price; Billing lists the prices and explains how the time is charged. A task keeps the size its Project had when the task was started. Tasks on a Runner run on the Runner's machine and ignore machineSize.

Change a Project

projects.configure changes the Runner, the machine size, the models, the commands, how many fix rounds a Review may run, and the tool cache:

{
  "organizationId": "<organization id>",
  "projectId": "<project id>",
  "runnerMachineId": "<runner id>",
  "machineSize": "medium",
  "modelSelection": {
    "candidates": [{ "accountId": "<model account id>", "modelId": "claude-sonnet-4-5" }],
    "outputTokenLimit": 8192
  },
  "commands": [
    { "name": "setup", "run": "pnpm install --frozen-lockfile" },
    { "name": "dev", "run": "pnpm dev --port 3000", "ready": "curl -fsS http://127.0.0.1:3000" },
    { "name": "test", "run": "pnpm test" }
  ],
  "reviewFixBudget": 2,
  "toolCachePaths": [".gradle/caches/modules-2", ".gradle/wrapper", ".npm"]
}

devboxes invoke projects.configure --input @configure.json

projects.configure replaces all of these settings, so send the current values of the ones you keep. Tasks that already started keep their settings.

If you reinstall the devboxes GitHub App, the Project still uses the removed installation. To move it to the new one, add "connection": { "kind": "github-app", "id": "<connection id>" }. The connection id is the id that repositories.github-connect-complete returns or that repositories.connections lists. devboxes refuses an installation that cannot reach the Project's repository and a connection to another host. Without connection, the Project keeps its current one.

To let devboxes merge the Project's pull requests after their Review, see Merge approved pull requests.

Add the repository's commands

A Project's commands are the repository's own commands, for example to install the dependencies, run the tests, or start the dev server. A Blueprint runs them by name, so one Blueprint works for every Project that defines the commands it names.

Set them in commands with projects.configure, as shown above. A command with a ready check is a service: it keeps running in the background, and devboxes waits until the check succeeds.