Quickstart

At the end of this tutorial, a devboxes agent has installed the repository's dependencies and run its tests on your own machine.

You need:

a repository on GitHub, and permission to install a GitHub App on the account that holds it;
Claude Code or Codex, and a clone of the repository on your machine;
Docker on the same machine: Docker Engine on Linux, or OrbStack or Docker Desktop on a Mac;
a Claude or ChatGPT subscription, or an API key of a model provider.

Create your account and Organization

Open app.devboxes.ai/sign-up. Under Create your devboxes account, choose GitHub or Google, or enter your email and a password and choose Create account.
Under Create your organization, enter your company's name in Organization name, up to 18 characters, and choose Create organization.
Under Who is devboxes for?, choose A team or Just me. You can change it later under Settings > Organization.
devboxes asks How do you want to set up devboxes? Choose I write code.

The page Set up devboxes for your code opens. Keep the page open while you work through the steps.

The first step shows the commands that install the devboxes CLI and sign it in. Copy them into a terminal on the machine that holds the repository:

curl -fsSLO https://devboxes.ai/install
printf "%s  install\n" 07727182ac5362fe5345beb5b88999a4973b5a6c127acf205e3540c419977b14 | $(command -v sha256sum || echo shasum -a 256) -c - && sh install
devboxes login

devboxes login asks how you want to sign in. Choose the way you created your account. For GitHub or Google, the CLI shows a link and a code: open the link, check that the page shows the same code, and approve. For email, type the six-digit code that devboxes emails you.

The step turns to The devboxes CLI is signed in.

Connect your AI

In the Claude or ChatGPT row, choose Sign in, then Open the sign-in page. Sign in on the provider's page, then finish the step:

For Claude, the page shows a code. Paste it into Code from Claude, and choose Connect.
For ChatGPT, the step shows a code. Enter it on ChatGPT's page.

To use an API key instead, open Use an API key, choose the provider, and paste the key.

The step turns to Your AI is connected.

Connect your repository

Choose Install the GitHub app. GitHub opens in a new tab.
On GitHub, choose the account that holds your repository, give the app access to the repository, and install it.
Go back to the setup tab. The step turns to Your repository is connected.

Set up your repository

Choose Copy prompt above the prompt in this step.
Open Claude Code or Codex in your repository's folder, and paste the prompt.

The agent inspects the repository and creates a devboxes Project for its default branch, with a workspace that holds the languages, packages and services the repository needs. It adds the repository's commands to the Project: install, dev, test, lint and build. It then writes a Blueprint in which an agent makes a change, the tests and the linter run, the commits are published only when both pass, and a review follows. Answer the agent when it asks you something that only you can decide.

The step turns to Your project is set up.

Choose to run tasks on your machine

In this tutorial, we stay on the Free plan and run tasks on your own machine.

In Choose a plan, choose Stay on Free. Up to 3 tasks at a time run free on your own machine.
In a terminal on the machine with Docker, run:
```
devboxes machine add
```
It asks for the machine's name and offers to start it. Start it, and leave it running.
Back on the page, choose Run tasks on your machine's name.

The step turns to Tasks run on your machine's name.

Start your first task

Choose Start a task. The composer holds your Project and the Blueprint that setup added, Turn an issue into a pull request.
Type Install the dependencies and run the tests. and press Enter.

devboxes starts the task with that Blueprint. The page then becomes the task's Session, and you watch the agent work. The first task waits while devboxes builds the Project's workspace, which takes several minutes. When the Session finishes, it says what the agent did and how the tests went.

Back on the setup page, every step is ticked off, and the page says You're set. Open your first task leads to the Session, next to the status of its Run.