Oz: run AI coding agents in the cloud

Oz is Warp’s cloud agent orchestration platform. Launch headless AI coding agents in isolated cloud environments, automate tasks, and schedule recurring runs.

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 Mode	Oz (cloud agents)
Runs in	Your local terminal	Isolated cloud container
Requires terminal open	Yes	No
Environment setup	Your local machine	Defined cloud environment
Secrets	Your local environment variables	Warp Managed Secrets
Scheduling	Manual	Cron-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:

Flag	Environment variable	Description
--api-key	WARP_API_KEY	API key for authentication
--output-format	WARP_OUTPUT_FORMAT	Output 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.