> 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`).

Note

This page covers the [managed architecture](https://docs.warp.dev/platform/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](https://docs.warp.dev/platform/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](https://docs.warp.dev/platform/self-hosting/managed-direct/). If you’d rather invoke agents yourself, see [Unmanaged](https://docs.warp.dev/platform/self-hosting/unmanaged/).

## 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

-   **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team.
-   **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work.
-   **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`.
-   **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to the Automation Platform. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See [API Keys](https://docs.warp.dev/reference/cli/api-keys/) for the full creation flow.

Caution

Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement.

### 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 agent API key so the worker can authenticate to the Automation Platform:

```bash
export WARP_API_KEY="your_agent_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/platform/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/platform/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/platform/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:

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.

Note

If the worker itself runs in Docker, you must mount any relevant config files (e.g., `~/.docker/config.json`) into the worker container for Docker context and credential discovery to work.

**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 Docker backend reads registry credentials from the worker’s Docker config. You can also override the Warp Agent sidecar image when the worker host must pull it from an internal registry.

See [Pulling self-hosted images from a private registry](https://docs.warp.dev/platform/self-hosting/private-container-registry/) for image mirroring, authentication, and worker configuration.

* * *

## 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/platform/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/platform/self-hosting/quickstart/) — ~10-minute path to a running Docker worker.
-   [Self-hosted worker reference](https://docs.warp.dev/platform/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.
-   [Private container registry](https://docs.warp.dev/platform/self-hosting/private-container-registry/) — Mirror worker and task images and configure private-registry pulls.
-   [Security and networking](https://docs.warp.dev/platform/self-hosting/security-and-networking/) — Data boundaries, egress, and Docker socket considerations.
-   [Troubleshooting](https://docs.warp.dev/platform/self-hosting/troubleshooting/) — Common issues with the Docker backend.