Unmanaged architecture

With the unmanaged architecture, you orchestrate agent runs by invoking oz agent run directly from your existing CI pipelines, Kubernetes pods, VMs, or dev boxes. The agent runs on whatever host the command is executed from; Warp tracks the session for you but does not start or stop agents.

Note

Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you’d rather have Oz trigger and route runs from Slack, Linear, schedules, or the API, use the managed architecture instead.

When to use unmanaged

• CI/CD pipelines — Run agents as part of a build or deployment workflow. This is how the warpdotdev/oz-agent-action GitHub Action works.
• Kubernetes pods — Run agents inside pods with access to your cluster’s network and services.
• Dev boxes and VMs — Run agents in pre-provisioned development environments. Especially useful for large monorepos with long setup times.
• Existing orchestrators — Drop oz agent run into any system that schedules work (Jenkins, Buildkite, internal job schedulers).

Unmanaged works on any platform Warp supports (Linux, macOS, Windows) with no dependency on Docker or any other sandboxing platform.

---

Unmanaged quickstart

~5 minutes

No Docker, no worker daemon, no environment required — just the Oz CLI on any host that can reach the internet.

Prerequisites

• The Oz CLI installed on the machine where agents will run. See Installing the CLI for platform-specific instructions.
• A Warp API key — For automation, create a team-scoped API key in the Warp app at Settings > Cloud platform > Oz Cloud API Keys. See API Keys for details.

1. Authenticate

Export your API key so the CLI can authenticate requests automatically:

export WARP_API_KEY="your_team_api_key"

2. Run an agent

Invoke oz agent run in the directory where you want the agent to operate. The agent has access to whatever tools, network resources, and credentials the host provides.

oz agent run --prompt "Refactor the authentication module" --share team

Expected outcome: The agent starts immediately in the current working directory, and a tracked session appears in the Oz dashboard.

3. Control sharing

Use --share to control who can attach to the session and steer the agent:

• --share — Share the session with yourself (accessible on other devices or in a browser).
• --share team or --share team:view — Give all team members read-only access.
• --share team:edit — Give all team members read/write access.
• --share user@example.com — Give a specific user read-only access.
• --share user@example.com:edit — Give a specific user read/write access.

The --share flag can be repeated to combine multiple sharing targets. If you authenticate with a team API key, agents are automatically team-scoped.

---

Example: GitHub Actions

Warp maintains the warpdotdev/oz-agent-action action for running agents in GitHub Actions. The action wraps oz agent run and is a drop-in for CI workflows:

- name: Run Oz agent
  uses: warpdotdev/oz-agent-action@v1  # wraps `oz agent run` under the hood
  with:
    prompt: "Review the code changes on this branch"
    warp_api_key: ${{ secrets.WARP_API_KEY }}

See GitHub Actions integration for full details.

Example: Kubernetes

Run an agent inside a Kubernetes pod with access to your cluster’s services:

apiVersion: batch/v1
kind: Job
metadata:
  name: oz-agent-task
spec:
  template:
    spec:
      containers:
      - name: oz-agent
        image: warpdotdev/warp-agent:latest
        command: ["agent", "run", "--prompt", "Run the test suite and report failures"]
        env:
        - name: WARP_API_KEY
          valueFrom:
            secretKeyRef:
              name: warp-credentials
              key: api-key
      restartPolicy: Never

Caution

For production deployments, pin to a specific Docker image digest (e.g., warpdotdev/warp-agent@sha256:...) instead of latest to ensure reproducible builds.

Note

Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements.

---

Tracking and observability

Unmanaged agents are tracked on Warp’s backend. Each run creates a persistent session that your team can:

• View in the Oz dashboard.
• Attach to via Agent Session Sharing to monitor or steer.
• Query through the Oz API/SDK for custom dashboards or monitoring.

Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — MCP servers, secrets, Warp Drive context, and saved prompts all apply.

---

Related pages

• Self-hosting overview — Compare managed and unmanaged, plus the architecture decision guide.
• GitHub Actions integration — Run agents in CI with the official action.
• Deployment patterns — Pattern 1 (CLI-only) explains the unmanaged model conceptually.
• Oz CLI — Full CLI reference for oz agent run and related commands.
• Agent Session Sharing — Attach to running sessions to monitor or steer them.