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.

Note

This quickstart sets up the managed architecture, where the Automation Platform orchestrates the agent and your worker provides the compute. Prefer a CLI-only path with no Docker requirement? Jump to the Unmanaged quickstart to run oz agent run directly on any host.

---

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 Docker - Use a VM, server, or local machine with a Docker daemon that runs Linux containers. Verify it with docker info. Docker Desktop on macOS or Windows works for testing.
• 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

Run the oz-agent-worker container, mounting the host’s 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.

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 begins listening for tasks. You should see log output confirming the connection (something like Connected to Oz / Waiting for tasks).

Caution

For production deployments, pin to a specific image digest (e.g., warpdotdev/oz-agent-worker@sha256:...) instead of the latest tag.

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 cloud agent dashboard with status moving from QUEUED → INPROGRESS → SUCCEEDED.

4. Verify the run

Open the 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.