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

• Enterprise plan with self-hosting enabled — Contact sales if self-hosting is not yet enabled for your team.
• A Linux machine with Docker — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with docker info. Docker Desktop on macOS or Windows works for testing.
• A self-hosted worker API key - In the Warp Factories web app user settings, click Generate new token and select Self-hosted worker. The key is tied to your team and does not require an agent selection. See creating a self-hosted worker API key for the full flow.
• The Oz CLI (for routing a test run) — See Installing the CLI.

---

Run your first self-hosted agent

~10 minutes

1. Export your API key

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

export WARP_API_KEY="YOUR_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.

---

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.

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 a Self-hosted worker key 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.