Skip to main content
Oz is Warp’s cloud agent orchestration platform. Unlike local Agent Mode — which runs an AI coding agent inside your terminal session — Oz dispatches agents to isolated cloud environments that execute headlessly, with no terminal window required. You can fire off a task, close your laptop, and come back to a finished pull request. Oz handles provisioning the environment, cloning your repository, injecting secrets, and reporting results back to you.

​
What you can do with Oz

Run cloud agents

Dispatch a one-off agent to make code changes, triage issues, or investigate a bug — all without keeping a terminal open.

Schedule recurring agents

Set a cron schedule so an agent runs every night, every Monday morning, or at any interval you choose.

Manage environments

Define isolated cloud environments with specific repos, branches, and setup commands, then reuse them across many agent runs.

Store secrets securely

Upload API keys and credentials to Warp’s managed secret store and have them injected automatically into agent containers.

​
How Oz differs from local Agent Mode

Local Agent ModeOz (cloud agents)
Runs inYour local terminalIsolated cloud container
Requires terminal openYesNo
Environment setupYour local machineDefined cloud environment
SecretsYour local environment variablesWarp Managed Secrets
SchedulingManualCron-based

​
The oz CLI

The oz CLI is the primary way to interact with Oz from your terminal. All oz commands share a few global options:
FlagEnvironment variableDescription
--api-keyWARP_API_KEYAPI key for authentication
--output-formatWARP_OUTPUT_FORMATOutput format: pretty (default), json, ndjson, or text
--debug—Enable debug logging

​
Runs and tasks

When you dispatch a cloud agent, Oz creates a run — the execution record for that agent invocation. Every run has:
  • A unique run ID (available as OZ_RUN_ID inside the agent container)
  • A state: queued → pending → claimed → in-progress → succeeded or failed
  • A conversation transcript you can retrieve after the run completes
Use oz task list to see recent runs, and oz task get <task_id> to inspect a specific run’s status and conversation. 
# List the 10 most recent runs
oz task list

# Filter to only failed runs
oz task list --state failed

# Get the status of a specific run
oz task get <task_id>

# Retrieve the full conversation for a run
oz task get <task_id> --conversation

​
Quick start: run your first cloud agent

1

Authenticate

Make sure your WARP_API_KEY is set, or pass --api-key to each command.
2

Create a cloud environment

Set up an environment that points to your repository so the agent has code to work with.
oz environment create \
  --name "my-app" \
  --repo owner/my-app \
  --setup-command "npm install"
3

Run a cloud agent

Dispatch an agent with a prompt. Use --environment to specify the environment the agent should run in.
oz agent run-cloud \
  --prompt "Add input validation to the login form in src/auth/login.ts" \
  --environment <environment_id>
4

Check the results

oz task list --state succeeded
oz task get <task_id> --conversation

​
Output formats

All oz commands support --output-format for scripting and CI use: 
# Machine-readable JSON
oz task list --output-format json

# Newline-delimited JSON for streaming pipelines
oz task list --output-format ndjson

​
Next steps

Cloud environments

Create and manage the isolated environments your agents run in.

Secrets

Securely store credentials and inject them into agent runs.

Scheduling

Run agents on a cron schedule for recurring automation.

Build docs developers (and LLMs) love

Get started for freeTalk to us