Self-hosting quickstart

Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting.

Prerequisites

• Managed self-hosting access and credentials - Complete the shared managed prerequisites, then create an Agent API key associated with the Default Service Account. This key authenticates both the worker and the oz agent run-cloud command in this quickstart. A self-hosted worker key authenticates the worker only.
• A Linux machine with a rootful Docker daemon and GNU stat - This quickstart does not cover macOS or Windows. On those hosts, follow the Homebrew or release binary setup instead.
• The Oz CLI - Install it on the machine that will route the test run. See Installing the CLI.

Run your first self-hosted agent

~10 minutes

1. Export your API key

Export the Agent API key so the worker container and the Oz CLI can authenticate to the Automation Platform:

export WARP_API_KEY="YOUR_AGENT_API_KEY"

2. Start the worker

On the Linux host, run the oz-agent-worker container and mount the Docker socket so the worker can spawn task containers. Choose any --worker-id meaningful for your team — you'll use this value to route tasks to this worker.

export DOCKER_SOCKET_GID="$(stat -c '%g' /var/run/docker.sock)"

docker run \
  --group-add "$DOCKER_SOCKET_GID" \
  -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 begins listening for tasks. You should see log output confirming the connection (something like Connected to Oz / Waiting for tasks).

3. Route a run to your worker

In a separate terminal on any machine with the Oz CLI, route a cloud agent run to your worker by passing --host with the worker ID you chose:

oz agent run-cloud --prompt "List the files in the current directory" --host "my-worker"

Expected outcome: The Automation Platform accepts the task, routes it to your worker, and the worker spawns a Docker container to execute the agent. You'll see the run appear in the <a href=https://oz.warp.dev>cloud agent dashboard with status moving from QUEUED → INPROGRESS → SUCCEEDED.

4. Verify the run

Open the <a href=https://oz.warp.dev>cloud agent dashboard, find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via Agent Session Sharing to monitor or steer it.

Troubleshooting

Worker won't start
Verify Docker is running (docker info) and that the daemon platform is linux/amd64 or linux/arm64. Musl-based (Alpine) worker hosts are not supported.

Worker won't connect
Verify you created an Agent key associated with the Default Service Account and that it has not expired. Ensure the machine has outbound internet access to oz.warp.dev:443. Increase log verbosity with --log-level debug to see connection details.

Task stays queued and never runs
Confirm the --host value you passed to oz agent run-cloud matches your --worker-id exactly (case-sensitive). Check that the worker's team matches the team creating the task.

For more, see Troubleshooting.

Next steps

• Self-hosting overview — Compare managed and unmanaged architectures and choose a backend.
• Managed: Docker — Full Docker backend setup, including private registries, volume mounts, and runtime configuration.
• Routing runs to self-hosted workers — How to route tasks from schedules, integrations (Slack, Linear), the API, and the Oz web app.