Oz

oz

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

Command Line

The Oz CLI is installed as oz. To get help output, use oz help or oz 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/platform/cli.

The most important commands are:

• oz agent run-cloud: Spawn a new cloud agent. You can configure the prompt, model, environment, and other settings.
• oz run list and oz run get <run-id>: List all cloud agent runs, and get details about a particular run. This includes the session link to view that session in the cloud.
• oz environment list and oz environment get: List available environments, and get more information about a particular environment.
• oz schedule list and oz 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:

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

$ oz run get 5972cca4-a410-42af-930a-e56bc23e07ac
# ...

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

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

Create a secret for cloud agents to use:

$ oz 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 full OpenAPI specification here: https://docs.warp.dev/platform/agent-api-and-sdk/agent.md

In addition, there are SDKs for:

• TypeScript and JavaScript: https://www.npmjs.com/package/warp-agent-sdk
• Python: https://pypi.org/project/warp-agent-sdk/

All SDKs have sync and async support, and documentation at the links above.

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
• Scheduling periodic tasks via workflow dispatch

Action Setup

Use warpdotdev/warp-agent-action@v1 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@v4
      - uses: warpdotdev/warp-agent-action@v1
        id: agent
        with:
          prompt: |
            Analyze the GitHub issue and provide a summary.
            Issue: ${{ github.event.issue.title }}
            ${{ github.event.issue.body }}
          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 oz secret commands instead.

Creating Environments

For detailed guidance on creating environments with oz environment create, see create-environment.md. This includes:

• Repository detection and analysis
• Docker image selection (Warp pre-built images or custom)
• Setup command determination
• Full workflow with mandatory confirmation points

Using Third-Party Coding CLIs

Oz environments support running third-party coding agent CLIs such as Claude Code, Codex, Gemini CLI, Amp, Copilot CLI, and OpenCode. The -agents tagged variants of prebuilt Oz Docker images (e.g. warpdotdev/dev-rust:1.85-agents) come with the most popular CLIs preinstalled. Base tags (without -agents) do not include coding agent CLIs.

For detailed per-CLI documentation (installation, authentication, non-interactive flags, and artifact reporting prompts), see references/third-party-clis.md.

Key concepts

1. Docker images: Use the -agents tagged variant of any warpdotdev/dev-* image (e.g. warpdotdev/dev-base:latest-agents) to get Claude Code, Codex, and Gemini CLI preinstalled. Base tags are smaller and do not include coding agent CLIs. 2. Secrets: Store API keys as Oz secrets (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) so they are available at runtime. 3. Non-interactive mode: Each CLI has a flag for headless execution (e.g. claude -p, codex exec, gemini -p). 4. Artifact reporting: When a third-party CLI creates a PR, parse its output for the PR URL and branch name, then call report_pr to register the artifact in the Warp UI.

Quick example

$ oz agent run-cloud \
    --environment <ENV_ID> \
    --prompt 'Run Claude Code to summarize the architecture: claude -p "Summarize the architecture of this project"'

Oz CLI - Create Environment

Guide agent to create Warp Environments using oz environment create.

Overview

Oz Environment = configured development environment with 3 phases: 1. Base Environment Setup: System packages, runtimes, core dependencies (reusable foundation) 2. Code Fetching: Clone repository with specific code 3. Workspace Setup: Project-specific setup commands (install deps, builds, migrations)

Pre-Execution

MANDATORY: Create task list with exactly 3 steps: 1. Verify included repos 2. Create or select docker image 3. Determine setup commands

Track progress, mark complete.

Phase 1: Base Environment Setup

1. Repository Detection

Determine which repositories to work with. Formats:

• GitHub URL: https://github.com/owner/repo, https://github.com/owner/repo.git, git@github.com:owner/repo.git
• owner/repo string
• Local filepath → run git -C <path> remote get-url origin to determine owner/repo
• Current working directory → run git remote get-url origin

If repo not available locally:

• Clone to temporary dir (e.g. /tmp/warp-env-<random>)
• Perform minimal/partial clone for dependency/Docker files only
• No full history, tags, or large blobs
• Only need working tree to read build/dependency files

HARD REQUIREMENT:

• Treat temp directory as internal-only
• NEVER cd into it or change user's working directory
• Always reference via absolute paths: cat /tmp/warp-env-123/requirements.txt

2. Docker Image Selection

Analyze repo contents to detect language/tooling:

• Dockerfile or devcontainer.json
• Dependency files: requirements.txt, poetry.lock, pipenv, package.json, yarn.lock, pnpm-lock.yaml, go.mod, Cargo.toml, etc.

3. Propose Base Image or Custom Image

Determine languages/frameworks across all repos.

Warp pre-built images (all on ubuntu with Node.js + Python):

• warpdotdev/dev-base:latest - Node.js + Python only
• warpdotdev/dev-dotnet:8.0 - .NET + Node.js + Python
• warpdotdev/dev-go:1.23 - Go + Node.js + Python
• warpdotdev/dev-java:21 - Java + Node.js + Python
• warpdotdev/dev-ruby:3.3 - Ruby + Node.js + Python
• warpdotdev/dev-rust:1.85 - Rust + Node.js + Python

Each image also has an -agents variant (e.g. warpdotdev/dev-rust:1.85-agents) that includes preinstalled coding agent CLIs (Claude Code, Codex, Gemini CLI). Use the -agents variant when the user needs third-party coding CLIs; otherwise prefer the base tag for smaller image size.

Prefer Warp images when they match detected languages.

Alternative approaches:

• Single dominant language: Propose language-specific base (Debian/Ubuntu-based). Choose version based on repo contents.
• Mixed-language/uncertain: Strongly recommend custom image instead.

Recommendation format: Explicitly state single clear language vs mixed/uncertain stack.

MANDATORY STOP POINT: Present: "I recommend the following base image/custom image approach: [RECOMMENDATION]. This should provide [BRIEF_REASONING]. Does this work for your needs, or do you want to choose a different base image or define a custom image?"

DO NOT CONTINUE until user responds.

4. Custom Image Creation (if needed)

Only if user confirms custom image needed:

a) Verify Docker Desktop installed and running

• macOS: brew install --cask docker if missing, then open Docker

b) Create Dockerfile

• Focus: language runtimes, system packages, global tools
• NOT project-specific dependencies
• Propose Dockerfile, get confirmation
• Build and tag as warp-env:<repo_name>

c) Build for AMD64/x86_64 architecture d) Push to Docker Hub: docker push

• Use docker login if needed

Phase 2: Code Fetching

Handled automatically by Oz - repository cloned into environment.

Phase 3: Workspace Setup

6. Setup Commands Analysis

Analyze repo documentation (README.md, WARP.md, docs/) to identify setup commands.

Be intelligent about base image:

• Official language images (node:, python:, golang:, rust:): Include runtime/package managers, NOT project deps → likely need dependency install commands
• Specialized dev images (debian:bookworm with tools): Check what's included
• Custom images: Consider what Dockerfile handles

Common scenarios:

• Node.js with node:* → NEED npm install or yarn install
• Python with python:* → NEED pip install -r requirements.txt or poetry install
• Go with golang:* → May NOT need go mod download (fetched during build)
• Rust with rust:* → May need cargo build
• Multi-language → Consider each stack's needs

Focus ONLY on:

• Fetch dependencies or set up workspace for development
• NOT already handled by Docker image
• NOT for live testing/running (avoid: npm start, npm run dev, python manage.py runserver, go run, cargo run)

If Docker image handles most setup, may need few/no commands.

7. Setup Commands Confirmation

Repos cloned into workspace directory. Commands assume workspace root as cwd.

Format requirements:

• Use relative paths (no leading "/")
• Wrap full command in double quotes
• Single-repo: Prefix with cd <repo_name> &&
• Multi-repo: Navigate to appropriate repo dir using relative paths

Examples:

• Instead of npm install → "cd my-repo && npm install"
• Alternative: "npm -C my-repo install"
• Multi-repo: "cd warp-internal && cargo build" + "cd warp-server && go mod download"

MANDATORY STOP POINT: Present: "I found these setup commands: [LIST_COMMANDS_WITH_CD_AND_QUOTES]. These will run automatically after the code is fetched. Are these correct, or do you need to add/remove any commands?"

DO NOT CONTINUE until user responds.

8. Environment Creation

CLI Command Detection: Detect which Oz CLI binary to use:

• Dev/staging: warp (or warp-cli on Linux)
• Production: warp (or warp-cli on Linux)
• Local: warp-local (or warp-cli-local on Linux)
• Preview: warp-preview (or warp-cli-preview on Linux)

Run <candidate> --version to confirm availability.

Command:

oz environment create \
  --name <repo_name> \
  --docker-image <selected_image> \
  --repo <owner/repo> \
  [--repo <owner/repo2> ...] \
  --setup-command "<command>" \
  [--setup-command "<command2>" ...]

Returns environment UID for next step.

9. Final Summary

Provide:

• Environment name and UID created
• Docker image used
• Setup commands that run automatically
• "Environment with <environment_uid> is now ready to be used with your integrations!"
• Demo command:

  oz integration create [provider] --environment <environment_uid>

where [provider] = linear or slack. Add --help for details.

• If warning about public repos with GitHub auth URL: "Warning: the following repos will only be read-only access for this environment: <repos>. If you want more access, authorize with GitHub at this link: <URL>"

Cleanup: Remove tmp directory if created.

Critical Rules

• MUST stop at two MANDATORY STOP POINTS (base image confirmation + setup commands confirmation)
• DO NOT continue past stop points automatically
• For other steps: proceed automatically unless genuinely need information you can't determine
• Refer to environment as "oz environment" (NOT "Cloud Environment")
• NEVER cd into temporary directories (e.g. cd /tmp/..., cd ./tmp-*)
• All temp directory interactions use absolute paths while keeping working directory unchanged
• If constructing command with cd into temp dir → correct to absolute path instead
• Don't say "mandatory stop point" to user - just "stop" and wait

Third-Party Coding Agent CLIs

This reference documents third-party coding agent CLIs that Oz cloud agents can install and run. Each CLI has its own authentication, non-interactive mode, and nuances.

The -agents tagged variants of prebuilt Oz Docker images (e.g. warpdotdev/dev-base:latest-agents, warpdotdev/dev-rust:1.85-agents) include Claude Code, Codex, and Gemini CLI preinstalled. Base tags (without -agents) do not include coding agent CLIs.

Reporting Artifacts

When a third-party CLI creates a PR or branch, Oz does not automatically detect it. You must explicitly register these artifacts so they appear in the Warp UI.

Pull Requests: After a third-party CLI creates a PR, call the report_pr tool with the pr_url and branch parameters. Parse the CLI's output to extract the PR URL and branch name.

How to prompt for this: When writing prompts that instruct an Oz agent to delegate work to a third-party CLI, always include instructions to: 1. Tell the third-party CLI to print the PR URL and branch name in its output. 2. After the CLI finishes, parse the output and call report_pr to register the artifact.

Plans: Plan artifacts are registered automatically by the Oz agent when it creates plans using its built-in plan tools. No special handling is needed.

---

Claude Code

• Package: npm install -g @anthropic-ai/claude-code
• Auth: ANTHROPIC_API_KEY environment variable (automatic).
• Non-interactive mode: claude -p "<prompt>"
• Useful flags: --output-format json, --allowedTools "Read,Write,Bash(...)", --append-system-prompt

Oz secret

oz secret create ANTHROPIC_API_KEY --team --value-file key.txt --description "Anthropic API key for Claude Code"

Example prompt

Run: claude -p "Analyze the codebase and list potential security issues" --output-format json

Artifact reporting prompt

Run Claude Code to implement the feature:
  claude -p "Create a branch, implement the login fix, commit, push, and create a PR using gh CLI. Print the full PR URL and branch name at the end."

After Claude Code finishes, find the PR URL and branch name from its output.
Then call the report_pr tool with those values so the PR appears as an artifact.

---

Codex CLI

• Package: npm install -g @openai/codex
• Auth: Requires an explicit login step before use:

  printenv OPENAI_API_KEY | codex login --with-api-key

Alternatively, CODEX_API_KEY can be set directly.

• Recommended: Add printenv OPENAI_API_KEY | codex login --with-api-key as an environment setup command so authentication happens automatically before the agent starts.
• Non-interactive mode: codex exec "<prompt>"
• Regional endpoint: Set OPENAI_BASE_URL if needed (e.g. https://us.api.openai.com/v1).
• Useful flags: --full-auto, --sandbox workspace-write, --json, --skip-git-repo-check

Oz secret

oz secret create OPENAI_API_KEY --team --value-file key.txt --description "OpenAI API key for Codex CLI"

Example prompt

First authenticate Codex: printenv OPENAI_API_KEY | codex login --with-api-key
Then run: codex exec "Refactor the utils module to reduce duplication"

Artifact reporting prompt

Authenticate Codex: printenv OPENAI_API_KEY | codex login --with-api-key
Then run: codex exec --full-auto "Create a branch, fix the bug, commit, push, and create a PR. Print the PR URL and branch name."
After Codex finishes, parse the PR URL and branch name from its output and call report_pr.

---

Gemini CLI

• Package: npm install -g @google/gemini-cli
• Auth: GEMINI_API_KEY environment variable (automatic). Obtain from Google AI Studio.
• Non-interactive mode: gemini -p "<prompt>" (headless mode)
• Useful flags: --output-format json, --yolo (auto-approve tool actions)

Oz secret

oz secret create GEMINI_API_KEY --team --value-file key.txt --description "Gemini API key for Gemini CLI"

Example prompt

Run: gemini -p "Review the test suite and suggest missing edge cases" --output-format json

Artifact reporting prompt

Run Gemini CLI:
  gemini -p "Create a branch, implement the change, commit, push, and create a PR using gh CLI. Print the full PR URL and branch name at the end." --yolo
After it finishes, parse the PR URL and branch from the output and call report_pr.

---

Amp

• Package: npm install -g @sourcegraph/amp
• Auth: AMP_API_KEY environment variable. Obtain from ampcode.com/settings. In isolated mode, uses ANTHROPIC_API_KEY instead.
• Non-interactive mode: amp -x "<prompt>" (execute mode)
• Useful flags: --dangerously-allow-all (skip tool approval prompts)

Oz secret

oz secret create AMP_API_KEY --team --value-file key.txt --description "Amp API key"

Example prompt

Run: amp -x "List all TODO comments in the codebase and group them by priority"

Artifact reporting prompt

Run Amp:
  amp --dangerously-allow-all -x "Create a branch, implement the fix, commit, push, and create a PR using gh CLI. Print the full PR URL and branch name."
After Amp finishes, parse the PR URL and branch from the output and call report_pr.

---

Copilot CLI

• Binary: copilot (standalone, from github/copilot-cli)
• Auth: GH_TOKEN or GITHUB_TOKEN environment variable with a fine-grained PAT that has the Copilot Requests permission. Also supports COPILOT_GITHUB_TOKEN.
• Non-interactive mode: copilot -p "<prompt>"
• Useful flags: --allow-all-tools
• Note: The gh copilot extension (distinct from standalone copilot) requires OAuth and does not work with PATs.
• Not preinstalled in Oz images. Install via setup commands or GitHub releases.

Oz secret

oz secret create GH_TOKEN --team --value-file token.txt --description "GitHub PAT with Copilot Requests permission"

Example prompt

Run: copilot -p "Review the latest changes and suggest improvements" --allow-all-tools

Artifact reporting prompt

Run Copilot CLI:
  copilot -p "Create a branch, implement the fix, commit, push, and create a PR using gh CLI. Print the full PR URL and branch name at the end." --allow-all-tools
After Copilot finishes, parse the PR URL and branch from the output and call report_pr.

---

OpenCode

• Install: curl -fsSL https://opencode.ai/install | bash (or via binary release)
• Auth: Uses provider-specific API keys via environment variables (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY). Also reads from .env files. Run opencode auth login to configure interactively.
• Non-interactive mode: opencode run "<prompt>" or opencode -p "<prompt>"
• Useful flags: -f json (JSON output), -q (quiet/no spinner)
• Not preinstalled in Oz images. Install via setup commands.

Example prompt

Run: opencode run "Explain the architecture of this project" -q

---

Droid (Factory)

• Install: curl -fsSL https://app.factory.ai/cli | sh
• Auth: Requires a Factory account. Use /login in the CLI or generate an API key from Factory Settings. Headless env-var auth is not yet confirmed — this CLI may require interactive login.
• Non-interactive mode: droid exec "<prompt>"
• Useful flags: --auto low|medium|high (permission tier), --skip-permissions-unsafe
• Status: Not currently supported for headless Oz environments due to unclear non-interactive auth. Excluded from prebuilt images.

---

Quick Reference