Connect a runner

A runner starts the containers in which tasks execute. The dashboard assigns the work to a runner with the required tools and model access.

Connect your own machine

Install Docker and the Devboxes CLI on the execution machine. With Docker running, enter:

devboxes login
devboxes connect
devboxes credentials setup
devboxes doctor
devboxes listen

Use devboxes connect --organization <id> --name <name> to choose an organization and a recognizable machine name. Replace both placeholders with your values.

Keep listen running. A registered machine that is not listening cannot start new tasks. The Runners page shows connection and availability information.

Set concurrency deliberately

The listener runs one task at a time by default. To allow more:

devboxes listen --max-concurrent 2

Choose a limit the machine and model account can support. Each additional task needs compute resources and can add provider usage. Increasing concurrency does not fix unavailable credentials or an unqualified image.

Use Devboxes Cloud

Choose Devboxes Cloud as the project's runner target when the option is available. You do not install a local listener for that project. Connect a supported organization provider account so the cloud task can access its model.

Cloud availability and account permissions depend on the deployment. The project picker indicates when cloud execution is unavailable.

Take a runner out of service

To stop the listener, press Ctrl+C in the terminal running devboxes listen. Wait for the process to exit. Closing the listener does not by itself revoke its registration or erase a task's external changes.

To revoke a runner's access, an owner or admin can delete it from Runners. First stop any runs assigned to that machine and wait until none is running. Open Runners, find the machine, choose its delete action, and confirm Delete runner. A running assignment blocks deletion; resolve it before trying again.

Deletion revokes the machine's API key and access to its encrypted device credential store. It cannot retract credentials already loaded by a local process or remove files from the host. A saved machine ID can be used with an authorized devboxes connect sign-in to restore the registration.

For a temporary availability problem, run devboxes doctor on the host and read its failed checks before deleting the registration. Check Docker and the listener first, then repair model credentials when the error identifies that connection.