> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Managed: Docker backend

Run the Automation Platform managed worker daemon with the Docker backend to execute cloud agent tasks in isolated containers on your infrastructure.

Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the Automation Platform (Slack, Linear, schedules, API, `oz agent run-cloud`).

## When to use the Docker backend

-   You want the simplest managed setup and have Docker available on the worker host.
-   You want per-task isolation without running a Kubernetes cluster.
-   You’re not already deploying workloads into Kubernetes.

* * *

## Prerequisites

Complete the shared [managed prerequisites](https://docs.warp.dev/factories/self-hosting/#managed-prerequisites), then prepare:

-   **A machine to run the worker** - Use a Linux VM, server, or local machine for production. Docker Desktop on macOS or Windows works for testing.
-   **Docker** - Install a **linux/amd64** or **linux/arm64** Docker daemon that runs Linux containers. Windows containers are not supported. The worker host can use any OS because Docker Desktop on macOS and Windows runs a compatible Linux VM. Verify the daemon with `docker info`.
-   **Task images** - Use a glibc-based image, such as Debian, Ubuntu, or a non-Alpine variant of an official image. Musl-based images such as Alpine Linux are not supported. Add required tools, binaries, scripts, and system packages to the [environment’s custom image](https://docs.warp.dev/platform/environments/).

### Install Docker

If Docker is not already installed, follow the [official Docker installation guide](https://docs.docker.com/get-docker/) for your platform. Verify Docker is running:

```bash
docker info
```

**Expected outcome:** `docker info` prints daemon details without errors.

* * *

## Set your API key

Export your self-hosted worker API key so the worker can authenticate to the Automation Platform:

```bash
export WARP_API_KEY="YOUR_API_KEY"
```

## Install and run the worker

The `oz-agent-worker` is open source. See the [oz-agent-worker repository](https://github.com/warpdotdev/oz-agent-worker) for source code, issues, and contribution guidelines.

There are three ways to install and run the worker: as a Docker container, via Homebrew, or as a prebuilt binary from GitHub Releases. Docker is the recommended default.

The worker can be configured entirely via CLI flags, or via a YAML [config file](https://docs.warp.dev/factories/self-hosting/reference/#config-file) for more complex setups.

### Option 1: Docker (recommended)

The worker needs access to the Docker daemon to spawn task containers. Mount the host’s Docker socket into the worker container:

```bash
docker run -v /var/run/docker.sock:/var/run/docker.sock \
  -e WARP_API_KEY="$WARP_API_KEY" \
  warpdotdev/oz-agent-worker --worker-id "my-worker"
```

**Expected outcome:** The worker connects to the Automation Platform and logs that it’s listening for tasks.

### Option 2: Homebrew

Install the worker binary with [Homebrew](https://brew.sh/) on macOS or Linux from the [`warpdotdev/warp` tap](https://github.com/warpdotdev/homebrew-warp):

```bash
brew install warpdotdev/warp/oz-agent-worker
```

Run the binary directly. It uses the same Docker-daemon discovery described in [Docker connectivity](#docker-connectivity) below:

```bash
oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker"
```

### Option 3: GitHub Releases binary

Download the archive for your platform from the [oz-agent-worker releases page](https://github.com/warpdotdev/oz-agent-worker/releases), extract it, and run the binary. The example below uses Linux amd64; choose the archive that matches your OS and CPU architecture:

```bash
tar -xf oz-agent-worker-linux-amd64.tar.gz
./oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker"
```

Once started, the worker connects to the Automation Platform, waits for tasks routed to its `--worker-id`, runs each task in an isolated Docker container, and reports status and results back. The worker automatically reconnects if the connection drops.

You can run multiple workers with the same `--worker-id` for redundancy — the Automation Platform distributes tasks across connected workers.

* * *

## Docker backend configuration

The worker can take configuration either via CLI flags or via a YAML [config file](https://docs.warp.dev/factories/self-hosting/reference/#config-file). CLI flags take precedence over config file values.

**Common CLI flags:**

```bash
docker run -v /var/run/docker.sock:/var/run/docker.sock \
  -e WARP_API_KEY="$WARP_API_KEY" \
  warpdotdev/oz-agent-worker \
  --worker-id "prod-runner-1" \
  --log-level debug \
  --max-concurrent-tasks 4 \
  --idle-on-complete 10m \
  -v /opt/shared-cache:/cache:ro \
  -e NPM_TOKEN=your_token \
  -e GITHUB_TOKEN
```

Caution

When running the worker via Docker, there are two levels of `-e` flags. Docker’s `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker’s `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct:

```bash
# Docker -e: passes WARP_API_KEY to the worker container
# Worker -e: passes MY_SECRET to task containers
docker run \
  -e WARP_API_KEY="$WARP_API_KEY" \
  warpdotdev/oz-agent-worker \
  --worker-id "my-worker" \
  -e MY_SECRET=hunter2
```

**Equivalent config file** (`config.yaml`):

```yaml
worker_id: "prod-runner-1"
log_level: "debug"
max_concurrent_tasks: 4
idle_on_complete: "10m"
backend:
  docker:
    volumes:
      - "/opt/shared-cache:/cache:ro"
    environment:
      - name: NPM_TOKEN
        value: "your_token"
      - name: GITHUB_TOKEN  # inherits from host environment
```

Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](https://docs.warp.dev/factories/self-hosting/reference/) for the full flag and config schema.

* * *

## Docker connectivity

The worker uses the standard Docker client discovery mechanism to find the Docker daemon. If the worker runs in Docker, mount relevant config files such as `~/.docker/config.json` into the worker container for Docker context and credential discovery.

1.  **`DOCKER_HOST`** environment variable (e.g., `unix:///var/run/docker.sock`, `tcp://localhost:2375`).
2.  **Default socket** (`/var/run/docker.sock` on Linux, `~/.docker/run/docker.sock` for rootless Docker).
3.  **Docker context** via `DOCKER_CONTEXT` environment variable.
4.  **Config file** (`~/.docker/config.json`) for context settings.

Additional Docker environment variables the worker respects:

-   `DOCKER_API_VERSION` — Specify Docker API version.
-   `DOCKER_CERT_PATH` — Path to TLS certificates.
-   `DOCKER_TLS_VERIFY` — Enable TLS verification.

**Example: Connecting to a remote Docker daemon**

```bash
export DOCKER_HOST="tcp://remote-host:2376"
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH="/path/to/certs"
oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker"
```

* * *

## Private Docker registries

The worker automatically uses credentials from your Docker config (`~/.docker/config.json`) when pulling task images. If your [environments](https://docs.warp.dev/platform/environments/) use images from a private registry, authenticate the worker’s host first. Sidecar images, including the `oz` binary and its dependencies, come from public registries and do not require authentication.

```bash
docker login your-registry.example.com
```

When running the worker via Docker, mount the Docker config into the container:

```bash
docker run \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.docker/config.json:/root/.docker/config.json:ro \
  -e WARP_API_KEY="$WARP_API_KEY" \
  warpdotdev/oz-agent-worker --worker-id "my-worker"
```

* * *

## Routing runs to this worker

Once your Docker worker is connected, route tasks to it with `--host "<your-worker-id>"`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](https://docs.warp.dev/factories/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples.

* * *

## Related pages

-   [Self-hosting quickstart](https://docs.warp.dev/factories/self-hosting/quickstart/) — ~10-minute path to a running Docker worker.
-   [Self-hosted worker reference](https://docs.warp.dev/factories/self-hosting/reference/) — Full CLI flag and config file schema.
-   [Environments](https://docs.warp.dev/platform/environments/) — Define the Docker image, repos, and setup commands for tasks.
-   [Security and networking](https://docs.warp.dev/platform/execution-security/) — Data boundaries, egress, and Docker socket considerations.
-   [Troubleshooting](https://docs.warp.dev/factories/self-hosting/troubleshooting/) — Common issues with the Docker backend.