Creating a project
The three create steps, the runner image, and why a new project's first run waits.
A project pairs one repository with a runner image — the container every run
for that project executes in. Create project is a three-step wizard: pick
the repository, choose the image, then pick the run target. When you finish,
Devboxes asks an external builder for the image and holds the project's first
run in the queue until that image is ready. Only organization owners and admins
can create a project; other members get
Project repository credentials are limited to owners and admins. (403).
Pick a repository
The first step lists repositories from your connected Git providers. Choose a
connection, search, and Import the one you want. A repository already used
by another project keeps its Import button but disabled; hovering it shows
This repository is already used by <project>. If no connection is listed yet,
set one up first — see Connecting a repository.
Choose the image
Every image already includes the base OS, Git, SSH, jq, shell tools, Opencode, Agent Browser, and Chromium. On top of that you pick one Preset:
| Preset | Ships |
|---|---|
| Minimal | no preset tools |
| Frontend | Node.js, npm, pnpm, Bun |
| Python | Python, uv, pip, Poetry |
Package manager and Setup script default to the preset's conventions; edit them to match the repository.
Under Tools and versions, the preset's tools appear pinned to the versions the image already ships. Add extra tools from the catalog, and change any version from its dropdown. Only versions that differ from the preset's defaults rebuild the image — re-selecting a version the preset already ships changes nothing. The always-included agent tools cannot be overridden here.
A tool left without a version is rejected with Runner image tool versions are invalid.
Pick a run target
The last step records where this project's runs execute:
- Cloud target — runs with no runner setup when dashboard-managed runners are enabled for the deployment. A disabled option reads Not available on this deployment.
- Self-hosted — runs on your own machines. Set up the runner separately; see Quickstart.
What happens after you create
Devboxes sends the image spec to the external builder and stores the build with the project.
- If the builder already has that exact image, it returns a completed build and an image reference at once.
- Otherwise the image is pending. Devboxes re-checks the builder about once a minute until the build reports done and hands back a reference.
A run you dispatch for a brand-new project is accepted and sits in Queued. No runner claims it until the image has both a completed build and an image reference. Once the image is ready, the queued run is claimed on the next check with no action from you — see Dispatching runs.
Two failures surface at create time. Runner image builder is not configured. (503) means the
builder URL or its callback token is unset — creation is blocked until both are set. Runner image build dispatch failed. (502) means the builder rejected the request; confirm it is
reachable and try again.
Next: Blueprints — defining what the agent does with the project.