Build Farm with Agents

Agents run build jobs on machines connected to OneDev. The server updates connected agents automatically when necessary. This example installs a Docker-hosted agent and runs a container job through it.

Connect an Agent

1. Start your OneDev server following the installation guide. Configure a Server URL reachable from the agent machine.
2. Open Administration > Agents, click +, and choose Run via Docker Container.
3. Click Show Command to generate an agent token and installation command. Keep that token private. On the agent machine, run the generated command with a unique hostname and a persistent work directory.
4. The serverUrl must be reachable inside the agent container. On Docker Desktop, use http://host.docker.internal:6610 when the server runs on the same host. For another machine, use the server's reachable address. localhost inside the container points to the container itself.
5. Verify that the agent appears Online.

The generated Docker command mounts the Docker socket so the agent can launch job containers. Keep the host and container work-directory mapping from the generated command. For a host-installed agent instead, see Plain Old Build.

Configure a Remote Docker Executor

Open Administration > Job Executors and add a Remote Docker Executor. For the example below, use:

• Name: tutorial-agent-docker
• Agent Selector: "Name" is "tutorial-docker-agent"
• Applicable Jobs: "Project" is "tutorial-issues" and "Job" is "Agent Docker Check"

Replace the agent and project names with your own. Set Concurrency to the number of jobs you want this executor to run concurrently on each matching agent. Use Test with a suitable image, then save.

When no executors are configured, OneDev discovers an executor automatically; there is no saved “auto-discover executor” to delete. The explicit executor name in the job below ensures it uses the remote executor you created.

Run a Job

Create .onedev-buildspec.yml in the test project:

version: 53
jobs:
- name: Agent Docker Check
  jobExecutor: tutorial-agent-docker
  steps:
  - !CommandStep
    name: Verify Linux container
    runInContainer: true
    image: alpine:3.20
    interpreter: !PosixInterpreter
      shell: sh
      commands: |
        uname -s
        test "$(uname -s)" = Linux
        echo agent-container-test-passed
    useTTY: false
    runAs: '0:0'
    condition: SUCCESSFUL
  retryCondition: never
  timeout: 300

Run Agent Docker Check. Its log should name the selected agent, print Linux and agent-container-test-passed, and finish successfully.

To expand the farm, install agents with distinct names on more machines and adjust the Agent Selector to match them. Jobs wait for an eligible online agent with available executor capacity. An agent that does not match the selector will not run the job.