> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Run cloud agents" icon="rocket">
    Dispatch a one-off agent to make code changes, triage issues, or investigate a bug — all without keeping a terminal open.
  </Card>

  <Card title="Schedule recurring agents" icon="clock">
    Set a cron schedule so an agent runs every night, every Monday morning, or at any interval you choose.
  </Card>

  <Card title="Manage environments" icon="box">
    Define isolated cloud environments with specific repos, branches, and setup commands, then reuse them across many agent runs.
  </Card>

  <Card title="Store secrets securely" icon="lock">
    Upload API keys and credentials to Warp's managed secret store and have them injected automatically into agent containers.
  </Card>
</CardGroup>

## 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.

```bash theme={null}
# 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

<Steps>
  <Step title="Authenticate">
    Make sure your `WARP_API_KEY` is set, or pass `--api-key` to each command.
  </Step>

  <Step title="Create a cloud environment">
    Set up an environment that points to your repository so the agent has code to work with.

    ```bash theme={null}
    oz environment create \
      --name "my-app" \
      --repo owner/my-app \
      --setup-command "npm install"
    ```
  </Step>

  <Step title="Run a cloud agent">
    Dispatch an agent with a prompt. Use `--environment` to specify the environment the agent should run in.

    ```bash theme={null}
    oz agent run-cloud \
      --prompt "Add input validation to the login form in src/auth/login.ts" \
      --environment <environment_id>
    ```
  </Step>

  <Step title="Check the results">
    ```bash theme={null}
    oz task list --state succeeded
    oz task get <task_id> --conversation
    ```
  </Step>
</Steps>

## Output formats

All `oz` commands support `--output-format` for scripting and CI use:

```bash theme={null}
# Machine-readable JSON
oz task list --output-format json

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

## Next steps

<CardGroup cols={2}>
  <Card title="Cloud environments" icon="server" href="/cloud/environments">
    Create and manage the isolated environments your agents run in.
  </Card>

  <Card title="Secrets" icon="key" href="/cloud/secrets">
    Securely store credentials and inject them into agent runs.
  </Card>

  <Card title="Scheduling" icon="calendar" href="/cloud/scheduling">
    Run agents on a cron schedule for recurring automation.
  </Card>
</CardGroup>