Run your first task

This guide uses a self-hosted Docker runner. You need a Devboxes account with an owner or admin role, access to a GitHub repository and one issue in it, Docker running on the execution machine, and a supported model subscription or API key.

Already joining a configured team? Ask an owner or admin which project and model to use, then start at 5. Start the run. A member role can follow work but cannot dispatch runs from the dashboard or CLI.

1. Sign in

Accept your invitation and sign in at app.devboxes.ai. Complete any email verification and terms acceptance shown by the app. Without an invitation, use the access request on devboxes.ai.

2. Connect a repository

Open Credentials → Repository and choose Connect GitHub App. This walkthrough uses the built-in Implement GitHub Issue blueprint. For other Git hosts, see repository connections and choose a blueprint suited to that host.

For the GitHub App, select the repositories Devboxes may use. Keep this first connection limited to the repository you will test. See repository connections for permissions and connection errors.

3. Create a project

Open Projects → Create project. Select the repository, choose a workspace image preset, and review its package manager and setup command. Use Frontend for a JavaScript or TypeScript repository, Python for Python, or Minimal when you want to choose the tools yourself.

Choose Self-hosted as the runner target. Finish creating the project. Its image may still need to build and qualify; the project shows that status.

4. Connect the execution machine

Install the CLI, then run these commands on the machine that will execute tasks:

devboxes login
devboxes connect
devboxes credentials setup
devboxes doctor
devboxes listen

Approve sign-in in your browser. During setup, connect a supported model subscription or API key. doctor checks the machine's setup. Keep listen running so the machine can accept work.

The runner uses local credentials unless you explicitly sync supported credentials to the organization. You do not need to sync them for this local-runner walkthrough.

5. Start the run

Choose a small issue in the connected repository. Its description should state the expected change, constraints, and checks to run. A focused regression test or reproducible bug is a useful first task.

Open Sessions → Dispatch run. Select the project, Implement GitHub Issue, and an available model. Set the destination branch used by your repository.

End the task input with these two lines, replacing the example URL and branch:

ISSUE_URL=https://github.com/your-team/your-repository/issues/123
DESTINATION_BRANCH=main

Use the same destination branch in the form and task input. Review any additional required inputs, then submit. This blueprint implements the issue and prepares a pull request for review; it does not merge it.

6. Read the result

Open the new session. Follow the Transcript, answer any questions, and inspect Review when changes are available. Check the result summary and which tests actually ran. Open any published pull request to review it through your usual process.

A queued run has already been accepted. Do not submit a duplicate because it has not started. Check the queued-run checklist instead.