Self-hosting overview

Self-hosting runs cloud agent workloads on your infrastructure. You control the compute, network access, runtime secrets, and execution workspaces while Warp tracks each run.

Note

Self-hosting requires an Enterprise plan. To enable it for your team, contact sales.

Managed and unmanaged architectures

Choose an architecture based on which system starts each run. With the managed architecture, the Automation Platform routes work to oz-agent-worker. Use it for runs started from Slack, Linear, schedules, the API, the Oz web app, or oz agent run-cloud.

With the unmanaged architecture, your CI system, scheduler, or script invokes oz agent run directly. Warp tracks the session but does not start or stop the process.

Aspect	Managed	Unmanaged
Run lifecycle	The Automation Platform routes each run to a worker	Your system starts and stops each CLI process
Host support	Linux	Linux, macOS, and Windows
Execution	Docker container, Kubernetes Job, direct host process, or external runtime	The host environment you provide
Triggers	Integrations, schedules, API, web app, and CLI	CI, cron, scripts, and internal schedulers

Use managed and unmanaged runs together when different workflows need different ownership. For example, route Slack-triggered work to a managed worker and invoke unmanaged agents from CI.

Choosing an architecture

Use the unmanaged architecture when any of these conditions apply:

• Agents must run on macOS or Windows.
• Your system should own both the trigger and process lifecycle.
• You want to add oz agent run to an existing CI job or script.

Choosing a managed backend

Use the managed architecture when the Automation Platform should accept the trigger and route the run. Then choose a backend:

• Docker backend - Use the default backend when Docker is available. Each task runs in a container.
• Kubernetes backend - Use an existing cluster to run each task as a Kubernetes Job.
• Direct backend - Run tasks on the worker host when a container runtime is unavailable or host access is required.
• Command backend - Keep a worker connected and dispatch each task to an external job API, queue, or runtime.
• One-shot Direct - Let an external scheduler allocate a host and start one Direct worker for one task.

Managed prerequisites

All managed deployments require:

• Outbound network access - The worker and agent runtime must reach Warp. You do not need to open inbound ports. See Security and networking for endpoints and data boundaries.
• A worker ID - Choose the value used to route runs with --host. Multiple long-lived workers can share an ID for load balancing. Use a unique ID for each one-shot Direct job.
• Worker credentials - Docker, Kubernetes, Direct, and Command workers can use a self-hosted worker API key. Store it in your secret manager and provide it as WARP_API_KEY or --api-key.

An external orchestrator that creates runs through oz agent run-cloud or the API also needs an agent API key associated with the Default Service Account. In the Oz web app settings, create an Agent key and choose Default Service Account. The same agent key can authenticate the worker when one job both starts the worker and creates the run. Otherwise, give the worker a self-hosted worker key and the run creator an agent key. See API keys for the Oz CLI for the key types and creation flow.

Backend pages list the remaining runtime-specific requirements, such as Docker, Kubernetes, or the Oz CLI binary.

Managed architecture

oz-agent-worker connects to the Automation Platform, waits for tasks addressed to its worker ID, and handles each task with the configured backend. Docker, Kubernetes, and Direct run the agent on worker infrastructure. Command hands the task to an external runtime.

Start with the self-hosting quickstart for a Docker worker. For exact flags and YAML fields, use the self-hosted worker reference.

Routing runs to self-hosted workers

Set the run’s host to the connected worker’s ID. From the Oz CLI:

oz agent run-cloud \
  --host "my-worker" \
  --prompt "Refactor the authentication module"

Combine --host with other run-cloud flags when the run also needs an environment, model, or other configuration.

Use the same worker ID when you create or update schedules and integrations:

oz schedule create \
  --name "daily-cleanup" \
  --cron "0 9 * * *" \
  --prompt "Remove unused code and open a pull request." \
  --host "my-worker"
oz schedule update SCHEDULE_ID --host "my-worker"

oz integration create slack --host "my-worker"
oz integration update linear --host "my-worker"

API requests set the same worker ID in config.worker_host:

{
  "prompt": "Refactor the authentication module",
  "config": { "worker_host": "my-worker" }
}

In the Oz web app, select the worker from the host options when you create a run, schedule, or integration. See the relevant trigger or Warp Platform API documentation for other creation options.

Host selection is independent of the environment. A managed run can use the same environment with Warp-hosted or self-hosted execution; the selected backend determines how the worker applies its image and setup configuration.

Unmanaged architecture

With unmanaged execution, your system invokes oz agent run where the work should happen. The agent uses the tools, credentials, and network access available on that host. Warp records the session and lets authorized teammates view or steer it.

Use unmanaged execution for an existing CI pipeline, Kubernetes Job, VM, or developer machine when Warp does not need to route the task.

Security and observability

Repository clones and execution workspaces stay on your infrastructure. Agent context and model requests still travel through Warp’s services. See the self-hosted execution flow for the architecture and Security and networking for data boundaries, ZDR, and BYOLLM.

View managed and unmanaged runs in the cloud agent dashboard. Managed workers can also export OpenTelemetry metrics; see Monitoring.

Related pages

• Self-hosting quickstart - Start a managed Docker worker and route a test run.
• External orchestrators - Choose and deploy the Command backend or one-shot Direct.
• Unmanaged architecture - Invoke oz agent run from your own scheduler or CI system.
• Self-hosted worker reference - Look up worker flags and backend configuration fields.
• Deployment patterns - Compare Warp-hosted, self-hosted, and CLI-only execution.
• Troubleshooting - Diagnose worker startup, routing, and task failures.