Add a Runner

A Runner is one of your own machines, for example a build server. It needs Docker. Runners are tested with a native Docker Engine on Linux, rootful or rootless, and with OrbStack on a Mac. The Runner also accepts an engine that reports itself as Docker Desktop. It refuses other Docker engines, such as Colima, Rancher Desktop, and Lima.

Task containers reach the Runner at host.docker.internal. Rootless Docker allows that only with two settings: DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK=false in the environment of its docker service, and "host-gateway-ips": ["10.0.2.2"] in ~/.config/docker/daemon.json. Before the first task, the Runner checks that a container reaches it. When a task container can't reach the Runner, the Runner stops with DOCKER_ENGINE_UNSUPPORTED before the task starts.

The Runner starts Task containers with Docker's init process, as docker run --init does, so the engine must include its docker-init binary. Docker Engine, Docker Desktop, and OrbStack include it.

Owners and admins add Runners. A Runner works only while the person who registered it is still an active owner or admin of the Organization. If that person leaves the Organization or becomes a member, the Runner stops, and another owner or admin registers the machine again.

Add a Runner

On the machine, give your coding agent this prompt:

To do it yourself:

1. Sign in on the machine:

   devboxes login

2. Add the machine:

   devboxes machine add

   The command asks which Organization should run tasks on the machine and what to name it. It saves the machine's key in the file token in the Runner's state directory, which only your user account can read. Anyone with this file can run tasks as this Runner, so keep it out of source control. Scripts pass --organization <id> and --name <name> instead.

   On an Arm machine, for example a Mac with Apple silicon, the Runner runs tasks for linux/arm64. A task on such a Runner waits while devboxes builds the Project's workspace for linux/arm64, once per workspace. When that build fails, the task fails and its error gives the reason. A workspace that includes a package without an Arm build cannot run on an Arm Runner. The task's error and the armNotice of images.configure name those packages and give a prompt for your coding agent to find alternatives that build for Arm.

3. Start the Runner. devboxes machine add offers to start it. To start it later:

   devboxes runner listen

   Keep it running. The Runner picks up the tasks of its Projects and runs them in Docker. To start it again after a reboot, run the same command as a system service.

   A task's container talks only to the Runner, which passes its requests on to devboxes. On Linux, the Runner listens for its containers on the Docker bridge address, for example 172.17.0.1. A firewall that refuses incoming connections by default, such as ufw, blocks them, and the task then fails after 10 minutes. Allow incoming TCP connections from the Docker bridge network to the Runner's port, which relay.json in the Runner's state directory names.

4. Find the Runner's id by its name with capacity.list, and choose the Runner for a Project with that id in runnerMachineId. See Create a Project.

What a Runner connects to

Runners lists what a Runner and its tasks connect to, the telemetry settings that tasks run with, and how tasks on a Runner search the web.

Check your Runners

You see for a Runner whether it is ready, offline, or disabled. The operation is capacity.list.

Turn a Runner off or remove it

Turn a Runner off or on with capacity.configure, and remove it with capacity.remove. A Runner that is off takes no new tasks. Tasks that are already running finish.

Clean up after a failed task

When a task succeeds, is cancelled, or pauses because its model account's usage limit or credit is exhausted, the Runner deletes its Docker container and its folder. When a task fails, the Runner keeps both so that you can inspect them, for example with docker logs devboxes-task-<task id>. The Runner never deletes them, even when it restarts. Delete them yourself when you no longer need them.

For a failed task, the Runner keeps two things on the machine:

• A stopped Docker container named devboxes-task-<task id>.
• A folder named after the task ID in the Runner's state directory. The folder holds devboxes-executor, the program that runs the task in the container. The file is larger than 100 MB.

A task that fails before its container exists leaves only the folder.

The state directory is $HOME/.config/devboxes/runner on Linux and $HOME/Library/Application Support/devboxes/runner on macOS. If XDG_CONFIG_HOME is set, it is $XDG_CONFIG_HOME/devboxes/runner. The --state-directory option of devboxes runner listen changes it. The directory holds the Runner's relay key, so devboxes runner listen refuses to start when it, its relay.json, or the Runner key file is not yours or its group or others have any permission. On Windows, the files' access-control lists decide instead.

The Runner records the end of a task, and the machine cost of its Run, when it sees the stopped container. If you delete a container before that, for example while the Runner is stopped, the Run's machine cost is missing from sessions.usage. Clean up a task only after the Runner has printed one of these lines for it:

1. List the stopped task containers and the task folders:

   docker ps -a --filter label=devboxes.task --filter status=exited
   ls "<state directory>"

2. Delete the failed tasks' containers that still exist, and their folders:

   docker rm --volumes devboxes-task-<task id>
   rm -rf "<state directory>/<task id>"

   On macOS, for example, the folder is "$HOME/Library/Application Support/devboxes/runner/<task id>".

Track what your machines cost

Give a Runner an hourly cost in EUR with capacity.configure. sessions.usage then shows the machine cost of a Session's work.