Warp Oz Cloud Agents

oz-platform

Use the Oz REST API and CLI to:

• Spawn cloud agents
• Get the status of a cloud agent
• Schedule cloud agents to run repeatedly
• Create and manage the environments in which cloud agents run
• Provide secrets for cloud agents to use

Looking up documentation

Prefer current, authoritative sources when answering questions or authoring skills about Oz platform behavior:

• Start with https://docs.warp.dev/llms.txt to discover the relevant documentation page.
• Every docs.warp.dev page has an agent-readable Markdown version at the same URL with .md appended. Fetch that version when reading documentation; for example, https://docs.warp.dev/agents/capabilities/computer-use.md.
• For CLI commands and flags, also confirm the installed version's behavior with {{warp_cli_binary_name}} help or {{warp_cli_binary_name}} help <subcommand>.

Treat the examples below as starting points, not the sole source of truth for details that can evolve, such as computer-use artifacts, CLI flags, and API behavior. If they conflict with the live Markdown documentation or CLI help, follow the live source.

Command Line

The Oz CLI is installed as {{warp_cli_binary_name}}. To get help output, use {{warp_cli_binary_name}} help or {{warp_cli_binary_name}} help <subcommand>. Prefer --output-format text to review the response, or --output-format json to parse fields with jq. You can find more information at https://docs.warp.dev/reference/cli.md.

The most important commands are:

• {{warp_cli_binary_name}} agent run-cloud: Spawn a new cloud agent. You can configure the prompt, model, environment, and other settings.
• {{warp_cli_binary_name}} run list and {{warp_cli_binary_name}} run get <run-id>: List all cloud agent runs, and get details about a particular run.
• {{warp_cli_binary_name}} environment list and {{warp_cli_binary_name}} environment get: List available environments, and get more information about a particular environment.
• {{warp_cli_binary_name}} schedule list and {{warp_cli_binary_name}} schedule get: List scheduled tasks with most recent runs, and get more information about a particular scheduled run.

Most subcommands support the --output-format json flag to produce JSON output, which you can pipe into jq or other commands.

Examples

Start a cloud agent, and then monitor its status:

$ {{warp_cli_binary_name}} agent run-cloud --prompt "Update the login error to be more specific" --environment UA17BXYZ
# ...
Spawned agent with run ID: 5972cca4-a410-42af-930a-e56bc23e07ac

$ {{warp_cli_binary_name}} run get 5972cca4-a410-42af-930a-e56bc23e07ac
# ...

Schedule an agent to summarize feedback every day at 8am UTC:

$ {{warp_cli_binary_name}} schedule create --cron "0 8 * * *" \
    --name "GitHub issue summary" \
    --prompt "Collect all feedback from new GitHub issues and provide a summary report" \
    --environment UA17BXYZ

List and inspect scheduled agents:

$ {{warp_cli_binary_name}} schedule list
$ {{warp_cli_binary_name}} schedule get <schedule-id>

Create a secret for cloud agents to use:

$ {{warp_cli_binary_name}} secret create JIRA_API_KEY --team --value-file jira_key.txt --description "API key to access Jira"

REST API

Oz has a REST API for starting and inspecting cloud agents.

All API requests require authentication using an API key. The user can generate API keys in their Warp settings, on the Platform page (accessible via {{warp_url_scheme}}://settings/platform).

You can find the API and SDK reference here: https://docs.warp.dev/reference/api-and-sdk.md.

TypeScript / JavaScript SDK

The TypeScript SDK is available via NPM. It is fully async, and works with Node, Bun, and Deno.

• Package link: https://www.npmjs.com/package/oz-agent-sdk
• Source Code: https://github.com/warpdotdev/oz-sdk-typescript
• API reference: https://raw.githubusercontent.com/warpdotdev/oz-sdk-typescript/HEAD/api.md

Python SDK

The Python SDK is available from PyPi. It can be used synchronously or asynchronously.

• Package link: https://pypi.org/project/oz-agent-sdk/
• Source Code: https://github.com/warpdotdev/oz-sdk-python
• API reference: https://raw.githubusercontent.com/warpdotdev/oz-sdk-python/refs/heads/main/api.md

API Examples

curl -L -X POST {{warp_server_url}}/api/v1/agent/run \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
        "prompt": "Update the login error to be more specific",
        "config": {
            "environment_id": "UA17BXYZ"
        }
    }'

curl -L -X GET {{warp_server_url}}/api/v1/agent/runs/5972cca4-a410-42af-930a-e56bc23e07ac \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json'

GitHub Actions Integration

You can trigger Oz cloud agents from GitHub Actions workflows. This enables automation like:

• Triaging issues when they're created or labeled
• Running checks on pull requests
• Responding to CI events or deployment triggers

Use GitHub Actions when the trigger itself lives in GitHub: An event like an issue being opened, a PR being labeled, a push, or a CI workflow completing.

For periodic/recurring work, prefer {{warp_cli_binary_name}} schedule create to enhance scheduled run tracking with the Oz platform.

The agent will have access to the gh CLI to communicate back to the repository. Prefer prompting the agent to use gh vs. requiring the agent to respond with structured output for the GitHub workflow to parse.

Action Setup

Use warpdotdev/oz-agent-action@main in your workflow. Required inputs:

• prompt: The task description for the agent
• warp_api_key: API key (store in GitHub secrets, e.g., ${{ secrets.WARP_API_KEY }})
• profile: Optional agent profile identifier (can use repo variable, e.g., ${{ vars.WARP_AGENT_PROFILE || '' }})

The action outputs agent_output with the agent's response.

Minimal Workflow Example

name: Run Oz Agent
on:
  issues:
    types: [opened, labeled]

jobs:
  agent:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: warpdotdev/oz-agent-action@main
        id: agent
        with:
          prompt: |
            Analyze the GitHub issue and provide a summary.
            Issue: ${{ github.event.issue.title }}
            ${{ github.event.issue.body }}

            Respond to the issue with a comment containing your summary using the `gh` CLI.
          warp_api_key: ${{ secrets.WARP_API_KEY }}
          profile: ${{ vars.WARP_AGENT_PROFILE || '' }}
      - name: Use Agent Output
        run: echo "${{ steps.agent.outputs.agent_output }}"

Common Patterns

Conditional steps: Use if: steps.agent.outputs.agent_output to branch on agent results.

Templating: Use actions/github-script@v7 to construct dynamic prompts from issue templates, repo context, or code.

Error handling: Check action success with if: success() or if: failure().

Git operations: The action runs with checked-out code and Git credentials, so agents can commit and push changes.

Environments

All cloud agents run in an environment. The environment defines:

• Which programs are preinstalled for the agent (based on a Docker image)
• The Git repositories to check out before the agent starts
• Setup commands to run, such as npm install or cargo fetch

You should almost always run cloud agents in an environment. Otherwise, they may not have the necessary code or tools available.

Cloud agents run in a sandbox, so they can install additional programs into their environment. They also have Git credentials to create PRs and push branches.

Cloud environments DO NOT store secret values, like API keys. Use the {{warp_cli_binary_name}} secret commands instead.