Automation Platform: The Automation Platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting. # Cloud agents overview Canonical page: [/platform/](https://docs.warp.dev/platform/) > Run background agents in the cloud from events, schedules, or integrations with team-wide observability. Cloud agents are autonomous, background agents that run on Warp’s cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, inspectable, and shareable across your team. **New to cloud agents?** Start with the [Cloud agents quickstart](/platform/quickstart/) to run your first cloud agent in \~10 minutes. ### Monitor, inspect, and share cloud agent runs [Section titled “Monitor, inspect, and share cloud agent runs”](#monitor-inspect-and-share-cloud-agent-runs) To understand what a cloud agent did, start from the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/platform/oz-web-app/#runs). From there, you can find a run by source, status, trigger, or owner; open the run transcript; inspect the prompt, plan, commands, logs, and output; and share the session link with teammates for review. For a full walkthrough, see [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/). If the run came from Slack, Linear, GitHub Actions, a schedule, the CLI, or the API, it still produces a reviewable cloud agent run record.  ### What cloud agents are designed for [Section titled “What cloud agents are designed for”](#what-cloud-agents-are-designed-for) Cloud agents are designed for situations where: * **You need agents to react to system events.** * Examples include crashes, bug reports, [Slack interactions](/platform/integrations/slack/), cron timers, or CI steps. * **You want observability into agent activity across a team or system.** * This includes being able to see what ran, when it ran, what triggered it, what the agent did, and how teammates can review or share the result. * **You need more parallelism than local execution typically allows.** * For example, [multi-agent orchestration](/platform/orchestration/) can run many agent tasks concurrently in the cloud, shard a repo-wide task into multiple runs, or fan out the same task across multiple targets. * **You want agents to operate continuously as part of engineering infrastructure.** * This includes [scheduled maintenance tasks](/platform/triggers/scheduled-agents/) and integration-driven automation.  *** ### What is a cloud agent run? [Section titled “What is a cloud agent run?”](#what-is-a-cloud-agent-run) A cloud agent run is represented as an agent task. A task is created when a trigger fires (for example a webhook event or schedule) or when a user starts a run explicitly. Each task includes: * **Inputs**: a prompt, and often additional context from the triggering system (for example a Slack message, PR metadata, or CI logs). * **Execution context (optional)**: an [Environment](/platform/environments/) that defines the repo, image, and startup commands the agent should run with. * **Lifecycle state**: created → running → completed / failed. * **Persistent record**: status, metadata, and a session transcript that can be reviewed after the task completes, including the prompt, plan, commands, logs, outputs, and follow-up messages where available. ### How cloud agents work [Section titled “How cloud agents work”](#how-cloud-agents-work) Cloud agents run on the [Automation Platform](/platform/overview/), which provides the primitives for triggering work, orchestrating tasks, executing agents (optionally in environments), injecting secrets, and inspecting results. * Something **triggers** an agent task. * The **orchestrator creates** and tracks the task. * The agent **executes** on a host, optionally inside an [environment](/platform/environments/), with whatever [secrets](/platform/secrets/) and credentials it needs. The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/platform/deployment-patterns/) pages. For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the Automation Platform orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/platform/self-hosting/) for details. ### What you get by default [Section titled “What you get by default”](#what-you-get-by-default) Because cloud agents run on the [Automation Platform](/platform/overview/), each run is tracked and produces a persistent record that can be observed, shared, and reviewed (even if execution happens outside the Warp app). #### Codebase Context [Section titled “Codebase Context”](#codebase-context) Cloud agent runs automatically benefit from [Codebase Context](/agents/capabilities/codebase-context/) for semantic code understanding and search, as long as Codebase Context is enabled for your account. See [Codebase Context in cloud agent runs](/agents/capabilities/codebase-context/#codebase-context-in-cloud-agent-runs) for details. #### Observability and steerability [Section titled “Observability and steerability”](#observability-and-steerability) Cloud agent tasks are designed to be inspectable by the team: * The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs) surface task status, source, trigger, creator, history, and credit usage. * [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) opens the run transcript so teammates can inspect the prompt, plan, commands, logs, files changed, outputs, and follow-up messages where available. * [Agent Session Sharing](/agents/local-agents/session-sharing/) lets authorized teammates share, monitor, and steer live local or third-party agent sessions. #### Centralized configuration [Section titled “Centralized configuration”](#centralized-configuration) Cloud agent workflows often rely on shared configuration such as [MCP servers](/platform/mcp/), rules, saved prompts, environment variables, and [secrets](/platform/secrets/). Warp supports centralized configuration so the same workflow behaves consistently across triggers (for example Slack + CI + schedules), without duplicating setup in every system. For details on configuring MCP servers for cloud agents, see [MCP Servers](/platform/mcp/). #### API access to tasks [Section titled “API access to tasks”](#api-access-to-tasks) The Automation Platform exposes task visibility via the [**Oz API & SDK**](/reference/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. * Build internal dashboards or monitoring (for example success rates, runtime, failure reasons). ### Using cloud agents with or without the Warp app [Section titled “Using cloud agents with or without the Warp app”](#using-cloud-agents-with-or-without-the-warp-app) Cloud agents do not require the Warp app. Teams can deploy and operate them through the [Automation Platform](/platform/overview/) using: * [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal * [Oz web app](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) * [Agent Session Sharing](/agents/local-agents/session-sharing/) — attach to running tasks to monitor or steer * [Agent Management Panel](/platform/managing-cloud-agents/) — view agent activity and run history in the Warp app * [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations If your team also uses Warp’s terminal, you get an additional workflow: tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. *** ### Billing and plan requirements [Section titled “Billing and plan requirements”](#billing-and-plan-requirements) Cloud agents and [integrations](/platform/integrations/) run on the [Automation Platform](/platform/overview/) control plane, and usage is billed using credits. #### For cloud agents via CLI/API [Section titled “For cloud agents via CLI/API”](#for-cloud-agents-via-cliapi) Individual users can run cloud agents without being on a team. Requirements: * You need at least 20 credits available * Cloud agents run on Warp-hosted infrastructure * Self-hosted agents require a team subscription #### For integrations (Slack/Linear) [Section titled “For integrations (Slack/Linear)”](#for-integrations-slacklinear) Integrations require you to be part of a [Warp team](/knowledge-and-collaboration/teams/) and additional requirements: * **Plan requirements** * **Supported plans**: Build, Max, Business * Your plan must support add-on credits. * **Credit requirements** * Your team must have at least 20 credits available to run cloud agents and integrations. For more details, see [Access, Billing, and Identity Permissions](/platform/team-access-billing-and-identity/). Caution If your credit balance reaches zero, cloud agent runs will not be able to execute until credits are replenished. *** ### Learn more [Section titled “Learn more”](#learn-more) * [Cloud agents quickstart](/platform/quickstart/) — run your first cloud agent with an environment in \~10 minutes. * [Automation Platform](/platform/overview/) — CLI, Oz API & SDK, orchestration, tasks, environments, hosts, integrations, and more. * [Warp Factories](/factories/) — assemble cloud agents into a standing triage-to-merge workflow with named agents, automations, and measurement. * [Harnesses](/platform/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. * [Agents](/platform/agents/) — cloud agents that own and execute runs on your team. * [Multi-agent orchestration](/platform/orchestration/) — coordinate a parent agent and its child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows. * [Skills as Agents](/platform/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. * [Oz CLI](/reference/cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/platform/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. * [Oz API & SDK](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/platform/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. * [MCP Servers](/platform/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. * [Deployment Patterns](/platform/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. * [Access, Billing, and Identity Permissions](/platform/team-access-billing-and-identity/) — explains individual and team-level requirements, credit billing behavior, and the permission model for who can run, view, and steer cloud agent tasks. # Cloud agent accounts Canonical page: [/platform/agents/](https://docs.warp.dev/platform/agents/) > Cloud agents are how Warp runs scheduled jobs, integration triggers, CI/CD automation, and API-driven tasks against your team's environments. A **cloud agent** is an agent that runs in Warp’s cloud (or on a self-hosted worker) instead of on your local machine. Use a cloud agent when you want to give an automation its own settings, secrets, skills, and permissions instead of having it act as a user on your team. Every team starts with a default cloud agent, which is what runs when an automation triggers a task with no other configuration. You can optionally create additional cloud agents through the Oz web app‘s **Agents** page or the public API. See [Managing cloud agents](#managing-cloud-agents) below. ## How cloud agents get triggered [Section titled “How cloud agents get triggered”](#how-cloud-agents-get-triggered) A run executes as a cloud agent when it’s authenticated with an [agent API key](/reference/cli/api-keys/) or when an agent is explicitly selected; otherwise it runs as the calling user. The triggers that can run as a cloud agent are: * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/platform/triggers/scheduled-agents/). * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/platform/integrations/). * **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [Oz API & SDK](/reference/api-and-sdk/). * **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [Oz CLI](/reference/cli/). Each run is tracked in the [cloud agent dashboard](https://oz.warp.dev/runs) with its trigger source, the environment it ran in, and the full transcript. ## Agent API keys [Section titled “Agent API keys”](#agent-api-keys) Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/reference/cli/api-keys/) for how personal and agent keys differ, and how to create one. ## Service accounts [Section titled “Service accounts”](#service-accounts) In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects. ## Managing cloud agents [Section titled “Managing cloud agents”](#managing-cloud-agents) Use the [Oz web app‘s Agents page](/platform/oz-web-app/#agents) for day-to-day management. Use the public API when you need to create or update agents from scripts, CI/CD, or internal tooling. Full request and response formats, including error codes, live on the [API Reference](/api) page under the **agent** tag. | Action | Endpoint | What it does | | ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Create** | `POST /agent/identities` | Creates a cloud agent with a `name` and optional `description`, `secrets`, and `skills`. | | **List** | `GET /agent/identities` | Returns every cloud agent on the team, including the default, with an `available` flag for plan-limit status. | | **Update** | `PUT /agent/identities/{uid}` | Replaces individual fields. Omitted fields stay unchanged; empty strings or arrays clear the field. | | **Delete** | `DELETE /agent/identities/{uid}` | Soft-deletes the agent and deletes every API key bound to it. The team’s default agent cannot be deleted. | ### Caller requirements [Section titled “Caller requirements”](#caller-requirements) Across all endpoints: * **Human callers only** - Only human users can create, update, or delete a cloud agent. A request authenticated as a cloud agent itself is rejected. * **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. ## Plan limits [Section titled “Plan limits”](#plan-limits) Every team starts with a default cloud agent. Additional agents are subject to plan-based limits. See [Warp pricing](https://www.warp.dev/pricing) for current limits per plan. When a team is over its plan limit (for example, after downgrading), the extra agents remain visible in the list but are marked as unavailable. Unavailable agents cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. ## Where cloud agents appear in the product [Section titled “Where cloud agents appear in the product”](#where-cloud-agents-appear-in-the-product) * **Agents page** - The Agents page in the [Oz web app](/platform/oz-web-app/) is where teams view, create, edit, and delete cloud agents. * **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default: runs execute as the calling user, and pull requests are authored by that person. Picking a cloud agent runs as that agent instead, so with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, pull requests are authored by the **Warp Factories** GitHub App. Choose a cloud agent for any schedule that opens pull requests. See [Run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship). * **Run filters and detail** - The Runs view lets you filter by cloud agent, and individual run detail pages show which agent executed the run. * **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by cloud agent runs to the team rather than to a person. ## Capabilities [Section titled “Capabilities”](#capabilities) Cloud agents — and individual runs — can also be granted specific capabilities: * [**Skills as agents**](/platform/skills-as-agents/) - Attach a skill directly to a cloud agent, or pass one at run time, so the agent starts from a reusable, version-controlled prompt instead of an ad hoc one. * [**MCP servers**](/platform/mcp/) - Connect a run to external tools and services (GitHub, dbt, Sentry, or a custom internal service) via Model Context Protocol. * [**Secrets**](/platform/secrets/) - Store and inject credentials into cloud agent runs without exposing secret values, scoped to a team, a person, or a specific cloud agent. ## Related pages [Section titled “Related pages”](#related-pages) * [Triggers](/platform/triggers/) - How schedules, integrations, and API calls invoke cloud agents. * [Environments](/platform/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. * [Multi-agent orchestration](/platform/orchestration/) - Coordinate a parent cloud agent and its children across local and cloud runs. * [API keys](/reference/cli/api-keys/) - Create personal and agent API keys. * [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. * [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run. * [Oz web app](/platform/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. # Deployment patterns Canonical page: [/platform/deployment-patterns/](https://docs.warp.dev/platform/deployment-patterns/) > Common architectures for deploying cloud agents, including CLI-only, Automation Platform-hosted, and self-hosted execution patterns. Teams adopt cloud agents in a few repeatable ways. This page outlines the most common architectures, what they’re good for, and how they fit together. ## Quick mental model [Section titled “Quick mental model”](#quick-mental-model) Cloud agent setups usually have four moving parts: 1. **Trigger**: something happens (CI step, webhook, cron, Slack mention). 2. **Orchestration**: something decides what to run and tracks it (Automation Platform orchestrator, GitHub Actions, your internal system). 3. **Execution**: where the agent actually runs (your runner, Automation Platform-hosted environment, or self-hosted workers). 4. **Visibility**: how the team monitors and intervenes (cloud agent dashboard, session sharing, APIs). *** ## Pattern 1: CLI-only agents (bring your own orchestrator) [Section titled “Pattern 1: CLI-only agents (bring your own orchestrator)”](#pattern-1-cli-only-agents-bring-your-own-orchestrator) Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you need a reliable, cloud-connected agent runner. ### What it looks like [Section titled “What it looks like”](#what-it-looks-like) * **Trigger**: GitHub Actions / CI, a script, a dev box action, or an internal orchestrator * **Orchestration**: your existing system * **Execution**: wherever that system runs * **Warp adds**: cloud connectivity, shared context, visibility, session sharing, and tracking ### Why teams choose it [Section titled “Why teams choose it”](#why-teams-choose-it) * You want a **drop-in replacement** for other CLI/SDK-based agents (Claude Code, Codex CLI, Gemini CLI/SDK-style flows). * You want to run agents anywhere without requiring Warp desktop. * You still want **team-level observability** even when execution is “outside Warp.” ### Common examples [Section titled “Common examples”](#common-examples) * **CI PR helper**: run formatting checks, generate review comments, suggest fixes, open PRs. * **Remote dev box agent**: run refactors or debugging tasks inside a pre-provisioned box. * **Internal orchestrator integration**: treat Warp as one agent option alongside other model providers. ### What you still get even without Warp orchestration [Section titled “What you still get even without Warp orchestration”](#what-you-still-get-even-without-warp-orchestration) * Access to your shared Warp context (for example MCP config, Warp Drive context, rules/prompts). * [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor/steer runs. * Read-only APIs for tracking and reporting. * A path to [Handoff](/platform/handoff/) workflows (where a run can be continued or inspected in richer surfaces). ### Minimal setup checklist [Section titled “Minimal setup checklist”](#minimal-setup-checklist) * A Warp team * A [cloud agent](/platform/agents/) (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) *** ## Pattern 2: Warp-hosted agents and orchestration (managed cloud execution) [Section titled “Pattern 2: Warp-hosted agents and orchestration (managed cloud execution)”](#pattern-2-warp-hosted-agents-and-orchestration-managed-cloud-execution) Use this when you want the Automation Platform to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management.  ### What it looks like [Section titled “What it looks like”](#what-it-looks-like-1) * **Trigger**: first-party integrations, cron schedules, API/SDK calls, or on-demand commands * **Orchestration**: Automation Platform orchestrator * **Execution**: Automation Platform-hosted environments (Docker-based) * **Visibility**: cloud agent dashboard + session sharing + APIs/SDKs ### Why teams choose it [Section titled “Why teams choose it”](#why-teams-choose-it-1) * You want the simplest path to reproducible, scalable cloud execution. * You want to run many tasks in parallel without building your own sandboxing and scaling layer. * You want a consistent “production” setup with standardized environments and centralized configuration. ### Common ways to trigger [Section titled “Common ways to trigger”](#common-ways-to-trigger) * **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. * **[Scheduled agents](/platform/triggers/scheduled-agents/)** for recurring work (cron-like automation). * **Custom triggers** from your own systems using Warp’s API/SDK. * **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. ### Example recipe: daily dead-code cleanup [Section titled “Example recipe: daily dead-code cleanup”](#example-recipe-daily-dead-code-cleanup) 1. Define a Warp [Environment](/platform/environments/) with the repo + toolchain. 2. Create a [schedule](/platform/triggers/scheduled-agents/) with a fixed prompt for cleanup. 3. The Automation Platform runs the agent on the cadence. 4. Your team monitors runs in the [Oz web app](/platform/oz-web-app/) and [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/), reviews artifacts (PRs, plans), and intervenes when needed. ### Example recipe: crash triage via Sentry webhook [Section titled “Example recipe: crash triage via Sentry webhook”](#example-recipe-crash-triage-via-sentry-webhook) 1. Define a Warp Environment with the target repo. 2. Register a Sentry webhook to your handler (server, cloud function, Zapier/n8n). 3. Handler extracts crash details, constructs a prompt, and calls the Automation Platform orchestrator API/SDK to start a task. 4. Warp spins up the run in the environment and you monitor progress via UI/API. ### Example recipe: fan-out parallel work (sharding) [Section titled “Example recipe: fan-out parallel work (sharding)”](#example-recipe-fan-out-parallel-work-sharding) When a task is naturally divisible, use [multi-agent orchestration](/platform/orchestration/) to spawn one child agent per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for slash command, CLI, web app, and API examples. ### Example recipe: same task across multiple models [Section titled “Example recipe: same task across multiple models”](#example-recipe-same-task-across-multiple-models) * Launch N runs with the same prompt, but different profiles that map to different models. * Compare results and choose the best output (or merge). *** ## Pattern 3: Self-hosted execution [Section titled “Pattern 3: Self-hosted execution”](#pattern-3-self-hosted-execution) Use this when you need to control where agent execution happens while still using Automation Platform orchestration and visibility. Repositories are cloned and stored only on your infrastructure. Orchestration metadata and session transcripts route through Warp’s backend; cloud conversations require Warp to store conversation data according to Warp’s retention terms. LLM inference requests and responses route through Warp to contracted model providers under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), except for provider-specific models that are not covered by ZDR and follow the provider’s retention requirements. Think of self-hosted execution as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): * **[Managed](/platform/self-hosting/#managed-architecture)** — The Automation Platform orchestrates. You run the `oz-agent-worker` daemon; the Automation Platform routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. * **[Unmanaged](/platform/self-hosting/unmanaged/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. Why teams choose self-hosted execution: * Code and execution must stay within your network boundary for compliance or security requirements. * Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides. * Your environments (multi-service stacks, heavy resource requirements) don’t fit in a single Docker container. For setup, decision guides, and a quickstart, start with [Self-hosting](/platform/self-hosting/). # Cloud agent environments Canonical page: [/platform/environments/](https://docs.warp.dev/platform/environments/) > Environments give cloud agents a repeatable container, repositories, and setup for every cloud agent run. Environments describe *how* an agent executes a task, not *what* it does. They give cloud agents the same container, repositories, and setup every time they run. Use an environment for a cloud agent run that needs a repeatable toolchain. Interactive local runs use your current checkout and machine setup, so they don’t need one. ## What an environment includes [Section titled “What an environment includes”](#what-an-environment-includes) An environment groups the runtime configuration for a cloud agent run: * **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/platform/self-hosting/managed-kubernetes/) can run without a separate environment. * **Repositories** - One or more repos that the agent clones into its workspace. * **Setup commands** - Commands that prepare the workspace, such as dependency installation, builds, or code generation. * **Environment variables** - Runtime values that you set in the Docker image or container configuration. * **Agent Secrets** - Credentials and sensitive values that Warp injects at runtime. Configure them separately with [Agent Secrets](/platform/secrets/). Together, these settings create a fresh workspace for each run. Warp provides [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments) with common languages and tools. You can also use an official image or publish your own. ## How environments fit into cloud agent runs [Section titled “How environments fit into cloud agent runs”](#how-environments-fit-into-cloud-agent-runs) When the Automation Platform starts a cloud agent run, it combines the environment with a host, an agent profile, and task-specific context. Each part serves a distinct purpose: * **Host** - Determines where the run executes. Choose [Warp-hosted](warp-hosting/) infrastructure or [self-hosted](/platform/self-hosting/) runners. * **Agent Profiles** - Set the agent’s permissions, model choice, and defaults. See [Agent Profiles](/agents/capabilities/agent-profiles-permissions/). * **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](/agents/capabilities/rules/). * **MCP servers** - Connect agents to external tools and data. See [MCP servers](/platform/mcp/). * **Per-run context** - Supplies task-specific data, such as a Slack thread, PR metadata, or CI logs. ## When to use an environment [Section titled “When to use an environment”](#when-to-use-an-environment) Use an environment when your run needs a predictable toolchain and repeatable setup. This is common in the following cases: * **Integrations and schedules** - Runs from Slack, Linear, GitHub Actions, or a schedule need the same workspace each time. * **CI and remote automation** - An environment prevents different runners or base images from changing the result. * **Team workflows** - A shared environment gives every teammate the same image, repos, and setup commands. * **Toolchain-specific work** - Use an environment when the workflow depends on particular language versions, linters, build tools, or system packages. You can skip an environment for an interactive local run in a working checkout. The local agent uses your existing machine setup. []() ## Container users and permissions [Section titled “Container users and permissions”](#container-users-and-permissions) Cloud agents run as a non-root user inside the container. See [configuring container users](environments/configuring-environments/#configure-container-users) for image, setup-command, and migration requirements. ## Related pages [Section titled “Related pages”](#related-pages) * [Configuring cloud agent environments](environments/configuring-environments/) to create, configure, and manage environments. * [Troubleshooting cloud agent environments](environments/troubleshooting-environments/) to fix setup, authorization, permissions, and image failures. * [Runners](/platform/runners/) to configure the compute that hosts environments. * [Deployment patterns](/platform/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. # Configuring cloud agent environments Canonical page: [/platform/environments/configuring-environments/](https://docs.warp.dev/platform/environments/configuring-environments/) > Create, configure, and manage cloud agent environments with the Oz web app, guided setup in Warp, or the Oz CLI. Create an environment before you run a cloud agent that needs your repositories, toolchain, or setup commands. You can create and manage environments in the Oz web app, with guided setup in Warp, or through the Oz CLI. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **GitHub repositories** - Add one or more repositories for the agent to clone and work in. * **GitHub authorization** - Authorize GitHub so the agent can access your repositories. For automated workflows that use an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. * **Docker image** - Use a publicly accessible image that can build and run your code. Official [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), and [rust](https://hub.docker.com/_/rust) images work for many projects. You can also use [Warp’s prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). Caution Musl-based Docker images, including Alpine Linux, are not supported. The agent runtime requires glibc. Use Debian, Ubuntu, or a default non-Alpine image from Docker Hub. ## Create an environment in the web app [Section titled “Create an environment in the web app”](#create-an-environment-in-the-web-app)  The Create environment panel in the Oz web app. 1. Open the [Environments page in the Oz web app](https://oz.warp.dev/environments), then click **New environment**. 2. Enter a name, select one or more repositories, and enter a **Docker image reference**. Click **Suggest** to get an image recommendation based on the selected repositories. 3. Add setup commands, cloud provider access for AWS or GCP, or a description when needed. 4. Click **Create environment**. You can now use the environment with cloud agents and integrations. ## Create an environment with guided setup [Section titled “Create an environment with guided setup”](#create-an-environment-with-guided-setup) Run [`/create-environment`](warp://action/create_environment) in Warp to inspect your repositories and generate an environment configuration. The guided setup detects languages, frameworks, and tools, then recommends an image and setup commands. Run the command from a Git repository with no argument, or pass one or more repository paths or URLs. ```text # Local paths /create-environment ./warp-internal ./warp-server # GitHub repositories /create-environment warpdotdev/warp-internal warpdotdev/warp-server # GitHub URL /create-environment https://github.com/warpdotdev/warp-internal.git ``` Guided setup does the following: * **Detect repositories** - Identifies the languages, frameworks, and tools the agent will use. * **Recommend an image** - Finds an existing Dockerfile, recommends an official base image, or helps you build a custom image. * **Suggest setup commands** - Uses your scripts and package managers to recommend workspace setup. * **Create the environment** - Creates the environment through the CLI and returns an environment ID. ## Create an environment with the CLI [Section titled “Create an environment with the CLI”](#create-an-environment-with-the-cli) Use the Oz CLI when you know the environment configuration, need a custom Docker image, or want to automate environment creation. ```bash oz environment create \ --name ENVIRONMENT_NAME \ --docker-image IMAGE_REFERENCE \ --repo OWNER/REPO \ --setup-command "SETUP_COMMAND" \ --description "DESCRIPTION" ``` Replace `ENVIRONMENT_NAME` with a human-readable label, `IMAGE_REFERENCE` with a Docker Hub image, `OWNER/REPO` with a repository to clone, `SETUP_COMMAND` with a workspace command, and `DESCRIPTION` with an optional summary. Repeat `--repo` and `--setup-command` for each additional repository or command. ## Environment design and best practices [Section titled “Environment design and best practices”](#environment-design-and-best-practices) Design the image and setup commands so they produce the same workspace on every run. * **Keep setup repeatable** - Write setup commands that are safe to rerun and produce the same toolchain and workspace state for a given repository revision. * **Pin toolchain versions** - Pin language runtimes and core tools in a Docker image, then use lockfiles such as `package-lock.json` for dependencies. * **Define the workspace boundary** - In a multi-repo environment, state which repositories are cloned and where setup commands run. * **Make prerequisites explicit** - Add any required build, code generation, or system-package installation steps to the setup commands. ```bash # Repeatable setup mkdir -p .cache npm ci # Setup that can fail on rerun or drift over time mkdir .cache npm install ``` If setup commands need credentials, configure [Agent Secrets](/platform/secrets/) instead of hardcoding tokens. ## Configure container users [Section titled “Configure container users”](#configure-container-users) Cloud agents run as a non-root user inside the container. Configure your image and setup commands for that user before you create the environment. ### Understand how Warp chooses the container user [Section titled “Understand how Warp chooses the container user”](#understand-how-warp-chooses-the-container-user) * **Image with a non-root `USER`** - Warp respects the Dockerfile `USER` directive and runs the agent as that user. * **Image that starts as root** - Warp runs the agent as a dedicated `agent` user with passwordless `sudo`. The user has UID and GID 1000 when available. * **Image that cannot support a non-root user** - If Warp can’t install `sudo` or the workspace isn’t writable by the agent user, it logs a warning and continues as root. ### Prepare images and setup commands [Section titled “Prepare images and setup commands”](#prepare-images-and-setup-commands) * **Use `sudo` for root access** - Prefix commands such as `apt-get install`, writes to `/usr/local` or `/etc`, and `chown` with `sudo`. Passwordless `sudo` preserves your `PATH`, but removes unsafe variables such as `LD_*` and `BASH_ENV`. * **Install tools outside `/root`** - The agent home directory is `/home/agent`. Install tools and configuration stored in `~/.bashrc`, `~/.cargo`, or `~/.nvm` system-wide or somewhere the `agent` user can access. * **Keep directories writable by UID and GID 1000** - Files the agent creates use UID 1000. Directories in your image must be writable by that user. ## Manage environments [Section titled “Manage environments”](#manage-environments) Use the Oz CLI to inspect and update environments after you create them. ### List environments [Section titled “List environments”](#list-environments) ```bash oz environment list ``` ### View an environment [Section titled “View an environment”](#view-an-environment) Replace `` with the ID of the environment you want to view. ```bash oz environment get ``` ### Update an environment [Section titled “Update an environment”](#update-an-environment) Replace `` with the ID of the environment you want to modify. ```bash # Add or remove a repository oz environment update --repo OWNER/REPO oz environment update --remove-repo OWNER/REPO # Add or remove a setup command oz environment update --setup-command "SETUP_COMMAND" oz environment update --remove-setup-command "SETUP_COMMAND" # Update the name, description, or Docker image oz environment update --name "ENVIRONMENT_NAME" oz environment update --description "DESCRIPTION" oz environment update --docker-image IMAGE_REFERENCE ``` Use `--remove-description` to clear the description. Use `--force` to skip confirmation checks for environments used by integrations. ### Delete an environment [Section titled “Delete an environment”](#delete-an-environment) Replace `` with the ID of the environment you want to delete. ```bash oz environment delete ``` Add `--force` to skip confirmation checks for environments used by integrations. ## Related pages [Section titled “Related pages”](#related-pages) * [Cloud agent environments](/platform/environments/) for the conceptual overview. * [Troubleshooting cloud agent environments](troubleshooting-environments/) to resolve setup and runtime problems. * [Integration setup](/reference/cli/integration-setup/) to configure end-to-end integration workflows. # Troubleshooting cloud agent environments Canonical page: [/platform/environments/troubleshooting-environments/](https://docs.warp.dev/platform/environments/troubleshooting-environments/) > Fix environment setup failures, authorization errors, permission problems, and incompatible Docker images for cloud agents. ## Setup commands fail on a fresh container [Section titled “Setup commands fail on a fresh container”](#setup-commands-fail-on-a-fresh-container) Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). 1. Update the setup commands so they work in a fresh container. For example, use `mkdir -p .cache` instead of `mkdir .cache`. 2. Use lockfile-based dependency commands such as `npm ci` when your project supports them. 3. Run the complete setup from a clean container before updating the environment. ## `Permission denied` or `EACCES` [Section titled “Permission denied or EACCES”](#permission-denied-or-eacces) Cloud agents run as a non-root user by default. A command fails when it needs root access or writes to a directory that the agent user cannot modify. 1. Prefix commands that require root access with `sudo`. 2. Make directories in the Docker image writable by UID and GID 1000. 3. Review [configuring container users](configuring-environments/#configure-container-users) for the image and setup-command requirements. ## `external_authentication_required` [Section titled “external\_authentication\_required”](#external_authentication_required) Cloud agents need GitHub authorization to clone private repositories. This error can occur when GitHub lacks repository access or the user who started the run has not authorized GitHub. 1. Authorize GitHub for the user who starts the run. 2. For an automated workflow with an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). 3. Follow [GitHub authorization setup](/reference/cli/integration-setup/#how-github-authorization-works) for the full flow. ## ”VM failed before the agent could run” [Section titled “”VM failed before the agent could run””](#vm-failed-before-the-agent-could-run) This error often means the Docker image is incompatible with the agent runtime. Alpine Linux and other musl-based images are not supported because the runtime requires glibc. 1. Switch to a glibc-based image such as Debian, Ubuntu, or a default non-Alpine official image such as `node`, `python`, or `rust`. 2. Recreate or update the environment with the new image. 3. If the error continues, review the environment configuration in the Oz web app or use the Oz CLI to run `oz environment get `. ## Related pages [Section titled “Related pages”](#related-pages) * [Cloud agent environments](/platform/environments/) for the environment model and when to use one. * [Configuring cloud agent environments](configuring-environments/) to create, update, and manage environments. * [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. # Cloud Agent FAQs Canonical page: [/platform/faqs/](https://docs.warp.dev/platform/faqs/) > Frequently asked questions about cloud agents, including where agents run, how runs work, supported models, security, and common workflows. This page answers common questions about cloud agents, including where they run, how they’re configured, and how teams use cloud agents for day-to-day engineering work. ## Architecture and execution [Section titled “Architecture and execution”](#architecture-and-execution) ### Where do cloud agents run? What’s the architecture? [Section titled “Where do cloud agents run? What’s the architecture?”](#where-do-cloud-agents-run-whats-the-architecture) Agents run either **locally** (inside your Warp session) or **in the cloud** as a **cloud agent run**, inside an **environment** (see [Environments](/platform/environments/)). The cloud agents platform is built around modular, observable execution: * A **trigger** starts work (manual, schedule/cron, webhook, or an integration like Slack/GitHub). * The **agent** executes inside an **environment** (either a Warp-hosted cloud sandbox, or a **self-hosted sandbox** on your infrastructure, depending on plan/support). * Every step is recorded: **transcripts, tool calls, logs, and outputs**, so work is auditable and debuggable instead of a black box. The same agent can be invoked consistently across entry points (Warp conversation, cloud agent web app, the CLI, API/SDK, Slack/GitHub triggers) without rewriting the underlying instructions. ### What exactly are cloud agents in Warp? [Section titled “What exactly are cloud agents in Warp?”](#what-exactly-are-cloud-agents-in-warp) A **cloud agent** is a packaged automation unit made up of: * **Instructions** — A reusable skill/prompt (what it should do). * **Profile** — Model selection + tools + permissions (how it operates). * **Trigger** — Manual, cron/schedule, webhook, or integration event (when it starts). * **Environment** — Repo access, dependencies (Docker image), secrets, setup commands, and runtime config (where it runs). * **Host** — Local (interactive) or cloud (run), and optionally self-hosted execution (where supported). Because the agent definition is modular, the same cloud agent can be started from different surfaces (terminal, web app, CLI, integrations) with a consistent interface. ### Can we intervene mid-run? [Section titled “Can we intervene mid-run?”](#can-we-intervene-mid-run) Yes. For **cloud agent runs**, you can: * Inspect **run state**, tool calls, and logs. * **Steer** the agent while it’s running. * Unblock it with additional instructions or context. If you’re not happy with where it landed, you can take over to finish the task. That human handoff is a core part of making agents reliable beyond demos. ### Do cloud agents have access to Codebase Context and indexing? [Section titled “Do cloud agents have access to Codebase Context and indexing?”](#do-cloud-agents-have-access-to-codebase-context-and-indexing) Yes. [Codebase Context](/agents/capabilities/codebase-context/) is enabled for all cloud agent runs, as long as Codebase Context is enabled for your account. This includes runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules. No additional configuration is needed — if Codebase Context is enabled, cloud agents use it automatically. ### Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)? [Section titled “Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)?”](#can-i-access-a-shell-inside-a-cloud-agent-environment-are-there-limitations-docker-playwright-etc) Yes. Cloud agent runs execute in a full Linux environment and behave like a local development session. You can install dependencies, run Docker, and use headless tools like Playwright, subject to standard sandbox resource limits. ### Do cloud agents run as root inside the container? [Section titled “Do cloud agents run as root inside the container?”](#do-cloud-agents-run-as-root-inside-the-container) No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1000 where available) with passwordless sudo. If your environment’s image sets a non-root `USER`, Warp runs the agent as that user instead, unchanged. For images that start as root, commands that need root access, like `apt-get install`, work with a `sudo` prefix. See [configuring container users](/platform/environments/configuring-environments/#configure-container-users) for details on home directory location, file ownership, and fallback behavior. ### Do cloud agents support a fully self-hosted, on-prem, or offline mode? [Section titled “Do cloud agents support a fully self-hosted, on-prem, or offline mode?”](#do-cloud-agents-support-a-fully-self-hosted-on-prem-or-offline-mode) The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted. Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/platform/self-hosting/) and [Deployment patterns](/platform/deployment-patterns/) for details. ## Models [Section titled “Models”](#models) ### Which models are supported? [Section titled “Which models are supported?”](#which-models-are-supported) Cloud agents are **multi-model by design**. You can choose models based on cost, latency, and capability, and teams commonly mix models by workflow: * Faster/cheaper models for triage and routine tasks. * Stronger models for complex changes (refactors, multi-file work, deeper reasoning). Model choice is configurable per **agent** (and often per environment/workflow), depending on how you set up your profiles. ### Can I choose which model cloud agents use? [Section titled “Can I choose which model cloud agents use?”](#can-i-choose-which-model-cloud-agents-use) Yes. Cloud agents support the same set of models available in Warp. Model selection is configurable per agent or environment. ### Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan? [Section titled “Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan?”](#can-i-authenticate-cloud-agents-with-my-own-chatgpt-or-claude-pro--max-plan) We’re strong proponents of this, but it ultimately depends on model provider policies. We’re actively working with providers to explore whether direct third-party authentication is possible. ### Do you support local or private LLMs for compliance or air-gapped environments? [Section titled “Do you support local or private LLMs for compliance or air-gapped environments?”](#do-you-support-local-or-private-llms-for-compliance-or-air-gapped-environments) Enterprise plans can route inference through your own cloud-provider account via [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/), so prompts stay within your cloud environment. Fully local, offline LLM execution is difficult given the current cloud agents orchestration and runtime architecture, but private-model support via enterprise cloud providers is available through BYOLLM. ### Will cloud agents support Agent-to-Agent Protocols (A2A)? [Section titled “Will cloud agents support Agent-to-Agent Protocols (A2A)?”](#will-cloud-agents-support-agent-to-agent-protocols-a2a) It’s something we’re actively exploring. Our focus is on building durable orchestration primitives—runs, environments, observability, steering, and coordination—that can support A2A and other emerging standards over time. ## Security and billing [Section titled “Security and billing”](#security-and-billing) ### Will cloud storage for agent definitions, runs, and conversations be secure and encrypted? [Section titled “Will cloud storage for agent definitions, runs, and conversations be secure and encrypted?”](#will-cloud-storage-for-agent-definitions-runs-and-conversations-be-secure-and-encrypted) Yes. All cloud agent data stored in the cloud is encrypted at rest and in transit, and protected by Warp account–level access controls. Cloud agent environments are sandboxed by default, with scoped access to repos, secrets, and compute. Security and isolation are first-class design constraints for the cloud agent runtime. ### Are cloud agents included in the Build plan, or is it a separate add-on? [Section titled “Are cloud agents included in the Build plan, or is it a separate add-on?”](#are-cloud-agents-included-in-the-build-plan-or-is-it-a-separate-add-on) Cloud agents are included in the Build plan. Usage is metered via credits, with pricing based on agent runs and resource consumption. Concurrency limits and credit allocation details are still being finalized. ### How do cloud agents handle API keys and secrets for agents? [Section titled “How do cloud agents handle API keys and secrets for agents?”](#how-do-cloud-agents-handle-api-keys-and-secrets-for-agents) Secrets are managed via the cloud agents CLI. Secrets are encrypted at rest, scoped to your Warp account, and injected into the agent environment at runtime. They are never hard-coded into agent instructions or logs. To learn more about how secrets work in practice, see [Cloud Agent Secrets](/platform/secrets/). ## Workflows [Section titled “Workflows”](#workflows) ### How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents? [Section titled “How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents?”](#how-do-agents-handle-branching-merge-conflicts-and-multi-agent-coordination-with-cloud-agents) The cloud agents platform is intentionally flexible. As the developer, you decide how agents should branch, coordinate, and resolve conflicts. Interactive agents can plan work and spawn subagents to parallelize tasks. Cloud agents provide the building blocks for [running and coordinating multiple concurrent agents](/platform/orchestration/), rather than enforcing a fixed workflow. ### Why focus on orchestration primitives instead of immediately adopting new agent standards? [Section titled “Why focus on orchestration primitives instead of immediately adopting new agent standards?”](#why-focus-on-orchestration-primitives-instead-of-immediately-adopting-new-agent-standards) We believe durable infrastructure matters more than transient standards. The cloud agents platform is designed to provide stable building blocks—agent runs, environments, auditability, steering, and coordination—that orchestration frameworks and emerging standards can plug into over time. ### Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)? [Section titled “Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)?”](#can-cloud-agents-integrate-with-external-tools-apis-or-services-like-n8n-connectors) Yes, and cloud agents do not rely on rigid, predefined workflows. Agents can install CLIs, call external APIs, use MCP servers, and access the internet directly. The intent is to delegate flexibility to agents rather than constrain them with fixed connectors. ### Can I export agent conversations and runs from cloud agents? [Section titled “Can I export agent conversations and runs from cloud agents?”](#can-i-export-agent-conversations-and-runs-from-cloud-agents) Yes. Conversations can be copied directly from the UI. The cloud agent CLI and API also provide access to full conversation text, logs, and outputs programmatically. ### How do cloud agents handle environment access, files, and security compared to SSH-based setups? [Section titled “How do cloud agents handle environment access, files, and security compared to SSH-based setups?”](#how-do-cloud-agents-handle-environment-access-files-and-security-compared-to-ssh-based-setups) Access is handled through Warp session sharing rather than SSH keys. Authentication is tied to Warp accounts and access controls, enabling secure person-to-person sharing. Configuration files and credentials can be managed using encrypted .env workflows (for example, dotenv-style encryption), avoiding repeated manual decrypt/encrypt cycles. ### Can cloud agents review PRs like a teammate? [Section titled “Can cloud agents review PRs like a teammate?”](#can-cloud-agents-review-prs-like-a-teammate) Yes. Common patterns for a **cloud agent** in PR review: * Summarize changes and intent. * Flag risky diffs and edge cases. * Suggest tests and missing coverage. * Propose refactors for maintainability. A typical workflow is: the agent leaves structured review comments and optionally opens a follow-up PR for mechanical fixes (or commits to the branch, if you choose to allow that). ### Can cloud agents write unit tests? [Section titled “Can cloud agents write unit tests?”](#can-cloud-agents-write-unit-tests) Yes, especially when: * The repo has a consistent test framework. * The **environment** is reproducible (dependencies and setup are reliable). The strongest loop is: a cloud agent generates tests, runs them in the environment, iterates until green, then opens a PR with the tests plus a short explanation of coverage and assumptions. ### Can cloud agents do big refactors? [Section titled “Can cloud agents do big refactors?”](#can-cloud-agents-do-big-refactors) It can help, but the best practice is to scope into smaller, reviewable chunks. Agents are strongest when they can continuously validate progress (tests, lint, typecheck). For large refactors, a staged approach with checkpoints (and possibly multiple subagents for parallel exploration) tends to work better than one giant prompt. ### Can cloud agents triage issues / tickets automatically? [Section titled “Can cloud agents triage issues / tickets automatically?”](#can-cloud-agents-triage-issues--tickets-automatically) Yes. A common cloud agent workflow: * When a ticket/issue is created (via integration trigger), a cloud agent gathers context (recent changes, logs/metrics links, ownership). * Proposes labels/priority and likely causes. * Drafts next steps or a response. * Asks clarifying questions back to the reporter when needed. ### Can cloud agents do dependency upgrades? [Section titled “Can cloud agents do dependency upgrades?”](#can-cloud-agents-do-dependency-upgrades) Yes. Scheduled dependency bumps are a classic cloud agent use case: * Open a PR. * Run tests. * Resolve simple conflicts. * Attach a risk summary (optional). This is usually implemented as a scheduled **cloud agent** producing recurring **runs**. ### Can cloud agents keep docs up to date? [Section titled “Can cloud agents keep docs up to date?”](#can-cloud-agents-keep-docs-up-to-date) Yes. With cloud agents, agents can: * Scan for drift (commands that no longer work, onboarding steps that changed). * Run validations in a docs/test environment. * Propose doc updates as PRs. This is most successful with “docs as code” workflows (GitBook/Mintlify/Docusaurus style), where updates go through normal review. ## Self-hosting [Section titled “Self-hosting”](#self-hosting) ### Where does my source code go with self-hosted agents? [Section titled “Where does my source code go with self-hosted agents?”](#where-does-my-source-code-go-with-self-hosted-agents) With self-hosting, repositories are cloned and stored only on your infrastructure — Warp never hosts your codebase. Warp uses a split architecture: * **Execution plane (your infrastructure)** — Repository clones, build artifacts, runtime secrets, and container filesystem state stay on the machines you control. * **Control plane (Warp-hosted)** — Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp’s backend under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or use it for model training. See [Self-hosting](/platform/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. ### Can I use `oz agent run` in CI or existing runners? [Section titled “Can I use oz agent run in CI or existing runners?”](#can-i-use-oz-agent-run-in-ci-or-existing-runners) Yes. The [unmanaged architecture](/platform/self-hosting/unmanaged/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp’s backend for observability. ### Can self-hosted agents access services behind a VPN? [Section titled “Can self-hosted agents access services behind a VPN?”](#can-self-hosted-agents-access-services-behind-a-vpn) Yes. Since self-hosted agents run on your infrastructure, they inherit your network access. This means agents can reach self-hosted GitLab/Bitbucket instances, internal APIs, databases, and any other services behind your VPN. This is one of the primary reasons teams choose self-hosting. ### Does self-hosting work with GitLab or other non-GitHub SCMs? [Section titled “Does self-hosting work with GitLab or other non-GitHub SCMs?”](#does-self-hosting-work-with-gitlab-or-other-non-github-scms) Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/self-hosting/unmanaged/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/platform/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. ### Do LLM requests still go through Warp with self-hosting? [Section titled “Do LLM requests still go through Warp with self-hosting?”](#do-llm-requests-still-go-through-warp-with-self-hosting) Yes. LLM inference routes through Warp’s backend, which has [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements with all contracted model providers. Enterprise teams that need full control over inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. AWS Bedrock BYOLLM supports both interactive agents and cloud agent runs; [Gemini Enterprise (Vertex AI)](/enterprise/enterprise-features/byollm-gemini-enterprise/) BYOLLM currently applies to interactive agents, with cloud agent support coming. ### What about large monorepos with long environment setup times? [Section titled “What about large monorepos with long environment setup times?”](#what-about-large-monorepos-with-long-environment-setup-times) The [unmanaged architecture](/platform/self-hosting/unmanaged/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/platform/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. ### Do Kubernetes pods provide enough sandboxing for self-hosted agents? [Section titled “Do Kubernetes pods provide enough sandboxing for self-hosted agents?”](#do-kubernetes-pods-provide-enough-sandboxing-for-self-hosted-agents) This depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements. ## Current limitations [Section titled “Current limitations”](#current-limitations) ### Do cloud agents support image attachments? [Section titled “Do cloud agents support image attachments?”](#do-cloud-agents-support-image-attachments) Cloud agent conversations do not currently support image attachments. Image attachment (via the toolbar button, clipboard paste, or drag-and-drop) is only available in [local agent conversations](/agents/local-agents/interacting-with-agents/terminal-and-agent-modes/). If you need to provide visual context to a cloud agent, you can describe the image contents in your prompt or reference image file paths within the agent’s [environment](/platform/environments/). # Handoff between local and cloud agents Canonical page: [/platform/handoff/](https://docs.warp.dev/platform/handoff/) > Understand how agent handoff moves work between local Warp sessions and cloud agent runs, including what context carries over in each direction. Handoff moves agent work between local Warp sessions and cloud agent runs without making you restart the task. Depending on the direction, Warp carries over conversation history, workspace changes, and attachments so the receiving agent can continue from the prior session instead of starting from scratch.  The Handoff control in a local conversation. ## Directions of handoff [Section titled “Directions of handoff”](#directions-of-handoff) Handoff supports three directions: * **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or parallel variants of the same task. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/platform/handoff/local-to-cloud/). * **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session’s workspace state restored. See [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/). * **Cloud to local** - Fork a cloud conversation into a local Warp session with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). ``` flowchart TD Local("Local Warp session") Cloud1("Cloud agent run") Cloud2("Cloud agent run (follow-up)") NewLocal("New local Warp session") Local -- "Local to cloud" --> Cloud1 Cloud1 -- "Cloud to cloud" --> Cloud2 Cloud1 -- "Cloud to local" --> NewLocal ``` ### Third-party agent runtime coverage [Section titled “Third-party agent runtime coverage”](#third-party-agent-runtime-coverage) Handoff coverage depends on which agent is running the conversation: * **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in the Automation Platform](/platform/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. * **Local to cloud** works for the Warp Agent. It isn’t available for third-party CLI agent sessions. ## What carries over [Section titled “What carries over”](#what-carries-over) Handoff preserves enough state that the receiving agent can resume the work, not only read about it. * **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn’t modified; cloud-to-cloud continues in the same conversation. * **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session’s repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction doesn’t currently apply workspace patches to your local checkout; review the cloud agent’s branch or pull request artifact to inspect those changes. * **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. Handoff is best-effort. When the receiving agent can apply the prior session’s changes cleanly, it picks up where the prior agent left off. When it can’t, the agent reports which changes failed to apply and continues with the changes that applied cleanly. ## When to use handoff [Section titled “When to use handoff”](#when-to-use-handoff) Each direction has a clear motivating workflow. * **Local to cloud** - Use when a local conversation has grown into work that’s better done in the cloud: long-running tasks you don’t want to keep your laptop awake for, [parallel variants of the same task](/platform/orchestration/), or steering work from another device once it’s running. * **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a [Slack-triggered](/platform/integrations/slack/) or [scheduled](/platform/triggers/scheduled-agents/) run completes and someone on the team wants to push it further. * **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping. ## Related pages [Section titled “Related pages”](#related-pages) * [Cloud agents overview](/platform/) - What cloud agents are, when to use them, and how they fit into the Automation Platform. * [Multi-agent orchestration](/platform/orchestration/) - Fan out parallel cloud variants after a local-to-cloud handoff. * [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the Oz web app alongside local conversations. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. * [Environments](/platform/environments/) - The runtime context a cloud agent runs in after a handoff. # Handoff from cloud to cloud Canonical page: [/platform/handoff/cloud-to-cloud/](https://docs.warp.dev/platform/handoff/cloud-to-cloud/) > Send follow-up instructions to a finished cloud agent run. The run continues with restored workspace state, so the agent picks up where it left off. Cloud-to-cloud handoff in Warp lets you send follow-up instructions to a finished cloud agent run and continue it in a fresh cloud session. The run keeps the same conversation and restores the prior workspace state, so the agent can pick up where it left off instead of starting over. Watch this walkthrough to see how cloud-to-cloud handoff continues a cloud agent run without losing the prior session context.  Use this handoff direction when: * You want to send a follow-up to a cloud agent after its session has ended. * You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs). ## What carries over [Section titled “What carries over”](#what-carries-over) When you send a follow-up to a run whose session has ended, the run continues with: * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. * **The prior workspace state** - The prior session’s repository changes (tracked and untracked) are restored before the agent answers your follow-up. For Git-managed sessions, the new session continues on the same Git branch. You can [customize which repositories and files get snapshotted](/platform/handoff/snapshots/) when running outside the bundled cloud agent image. * **Stable run identity** - The run’s ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. If any changes fail to apply, the agent reports which changes failed and continues with the changes that applied cleanly. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **An ended cloud agent run** - The run must be in a terminal state, such as succeeded, failed, or canceled, and have an associated agent conversation. Blocked runs that are waiting on user input or approval can’t be continued via cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can’t be continued via handoff. * **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn’t capture one (for example, due to a transient storage error), the run still continues but without restored workspace state. * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. Caution Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud runs that don’t have a snapshot on file can’t be handed off; start a new run instead. ## Sending a follow-up [Section titled “Sending a follow-up”](#sending-a-follow-up) To continue an ended cloud run, open the run in Warp and send the next message in the conversation. When the original session has ended, Warp automatically starts a fresh cloud session and restores the prior workspace state. 1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel in the Warp app. 2. **Send your follow-up.** Enter the next message in the conversation’s input and submit it. The run picks up where it left off, with workspace state restored. ### Third-party agent runtimes [Section titled “Third-party agent runtimes”](#third-party-agent-runtimes) Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the flow is slightly different from Warp Agent runs: 1. Open the ended run from the conversation panel in the Warp app, or from the artifacts shown after the run completes. 2. Click **Continue**. 3. Type your follow-up prompt and submit it. ## Inspecting a run that’s been handed off [Section titled “Inspecting a run that’s been handed off”](#inspecting-a-run-thats-been-handed-off) The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs) show one row per run, even when the run spans multiple sessions. 1. Open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/platform/oz-web-app/#runs). 2. Select the handed-off run. 3. Review the transcript. Each session appears in order, so you can see where one session ended and the next began. Per-session timestamps aren’t currently exposed in the API; the transcript is the source of truth. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **The run continued but no workspace state was restored.** The prior session didn’t capture a snapshot. This is rare but possible because snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. **The run is in a terminal state with no conversation and follow-ups are rejected.** Very old runs predate the agent conversation model and can’t be continued via handoff. Start a new cloud agent run with the prompt you want, referencing the prior run if needed. ## Related pages [Section titled “Related pages”](#related-pages) * [Handoff overview](/platform/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. * [Managing cloud agents](/platform/managing-cloud-agents/) - Find runs to send follow-ups to. # Handoff from local to cloud Canonical page: [/platform/handoff/local-to-cloud/](https://docs.warp.dev/platform/handoff/local-to-cloud/) > Move an in-progress local Warp Agent conversation into a cloud agent run for longer-running work, parallel exploration, or remote follow-up. Local-to-cloud handoff in Warp promotes an active local Warp Agent conversation into a cloud agent run. Warp forks the conversation, snapshots your uncommitted workspace changes, and sends both to the cloud so the agent can continue the same task with the context and files it needs. Watch this walkthrough to see how to move a local Warp Agent conversation into a cloud agent run.  Use this handoff direction when: * You have a long-running task and don’t want to keep your laptop awake. * You want to fan out variants of the same task across multiple cloud agents in parallel. * You want to walk away and check on the agent from a different device. * You want the agent to keep working while you start a new conversation locally. ## What the cloud agent receives [Section titled “What the cloud agent receives”](#what-the-cloud-agent-receives) When you hand off from local to cloud, the receiving cloud agent inherits: * **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for related sync behavior. * **A workspace snapshot** - Warp captures your uncommitted repository changes, including both tracked modifications and untracked files, and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. If any changes fail to apply in the cloud run, the cloud agent reports which changes failed and continues with the changes that applied cleanly. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **An active local conversation** - Have a [Warp Agent](/agents/) conversation open in Warp with the work you want to hand off. * **A configured environment** - The cloud agent needs an [environment](/platform/environments/) that includes the same repositories you’re working in locally. The environment’s repos must match your local checkout so the workspace snapshot applies cleanly. * **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/). * **Sufficient credits** - Cloud agent runs consume credits. See [Credits](/support-and-community/plans-and-billing/credits/) for how credit usage works, and [Access, billing, and identity](/platform/team-access-billing-and-identity/) for team-specific credit requirements. ## Handing off a conversation to the cloud [Section titled “Handing off a conversation to the cloud”](#handing-off-a-conversation-to-the-cloud) 1. **Open the handoff flow from your active conversation.** With the local conversation focused, press `&` or run the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn’t an entry point for handoff. 2. **Choose the environment for the cloud run.** Pick the one whose repositories match the directories your local conversation has been editing. If you don’t have a matching environment yet, create one and add the repos you’ve been working in. 3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. The `&` entry point and `/handoff` slash command both open the same handoff flow.  The ampersand handoff entry point.  The `/handoff` slash command. After the flow opens, choose the cloud environment and add the follow-up prompt the cloud agent should act on.  The environment selector in the handoff flow.  A follow-up prompt before handoff. After you submit, the cloud agent applies your workspace snapshot and responds to your follow-up. The local conversation is not modified, so you can keep working in it locally or close it. To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel in the Warp app. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **The cloud agent reports that some changes couldn’t be applied.** The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo’s current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment’s repo to the branch you were on locally and retry the handoff. **The cloud agent doesn’t see my uncommitted changes.** Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Otherwise, the conversation can’t be forked and the run falls back to starting over. **The conversation doesn’t appear in the cloud run.** The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel in the Warp app to confirm the conversation has a cloud-synced indicator. ## Related pages [Section titled “Related pages”](#related-pages) * [Handoff overview](/platform/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. * [Environments](/platform/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. * [Multi-agent orchestration](/platform/orchestration/) - Fan the handed-off work across parallel cloud child agents. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and steer the cloud run after handoff. * [Cloud agents quickstart](/platform/quickstart/) - Run your first cloud agent from scratch. # Customizing workspace snapshots Canonical page: [/platform/handoff/snapshots/](https://docs.warp.dev/platform/handoff/snapshots/) > Customize which repositories and files Warp snapshots at the end of a cloud agent run, so handoff continues to work outside the bundled cloud agent image. Workspace snapshots are how [handoff](/platform/handoff/) carries repository changes and other workspace state across cloud agent runs. At the end of every cloud agent run, Warp asks a small declarations script which repositories and files to snapshot, then uploads the resulting git diffs and file contents so the next cloud agent run can apply them. Warp’s bundled cloud agent image ships with a declarations script that snapshots every Git repository under the agent’s workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/platform/self-hosting/managed-direct/), or as an [unmanaged](/platform/self-hosting/unmanaged/) `oz agent run` in CI. ## When to customize snapshots [Section titled “When to customize snapshots”](#when-to-customize-snapshots) The default snapshotting behavior covers the most common case: snapshot every Git repository the agent worked on, inside the bundled cloud agent image. Customize snapshots when you need different behavior: * **You’re running outside the bundled image** — for example, a custom Docker base image, a self-hosted Direct backend, or unmanaged `oz agent run` invocations — where Warp’s default `snapshot-declarations.sh` isn’t on disk. * **You want to snapshot repos or files outside the agent’s workspace** — for example, a sibling repo the agent reads but doesn’t `cd` into, or a log file the agent writes to `/tmp`. * **You want dynamic snapshotting behavior** — because the declarations file is generated by a script that Warp runs, you can script any logic you want (filter by git status, dedupe against a baseline, emit a fixed list, etc.) rather than being limited to a static set of paths. If you don’t customize snapshots in any of these cases, the run still completes — Warp just uploads nothing, and handoff into the next run starts without the prior session’s uncommitted changes. ## How snapshotting works [Section titled “How snapshotting works”](#how-snapshotting-works) There are two ways to tell Warp what to snapshot at the end of a cloud agent run: * **Script-driven** (default in the bundled image) - Warp invokes a declarations script (configured via the `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` environment variable) that emits one JSON line per repository or file to snapshot. Use this when the set of repos isn’t fixed ahead of time (for example, the agent may `git init` a new directory during its work) or when you want any other dynamic logic to decide what to snapshot. * **Static** - You pre-populate the declarations file yourself (at the path given by `OZ_SNAPSHOT_DECLARATIONS_FILE`) and skip the script. Use this when the same set of repos and files should be snapshotted on every run. ### Script-driven flow [Section titled “Script-driven flow”](#script-driven-flow) 1. **Warp invokes your declarations script.** The script path comes from the `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` environment variable. Warp runs it with the agent’s workspace as the current directory. 2. **Warp passes a per-run output file.** Warp sets `OZ_SNAPSHOT_DECLARATIONS_FILE` to an absolute path the script must write to. Each run gets its own file so concurrent runs don’t clobber each other. 3. **Warp reads the declarations file.** Warp parses the JSONL output (described below) and uploads the listed repositories and files. See [Write a custom declarations script](#write-a-custom-declarations-script) for the full pattern. ### Static flow [Section titled “Static flow”](#static-flow) Set `OZ_SNAPSHOT_DECLARATIONS_FILE` to a path you’ve already populated and leave `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` unset. Warp reads the file directly with no script invocation. See [Use a static declarations file](#use-a-static-declarations-file) for the full pattern. In both flows, snapshotting is automatically enabled for cloud agent runs when cloud conversations are enabled, and can be turned off per run with `--no-snapshot`. See [Disable snapshots](#disable-snapshots) below. ## Environment variables [Section titled “Environment variables”](#environment-variables) * **`OZ_SNAPSHOT_DECLARATIONS_SCRIPT`** - Absolute path to the script Warp invokes at the end of each cloud agent run. The bundled cloud agent image sets this automatically. Set it yourself when running outside the bundled image. * **`OZ_SNAPSHOT_DECLARATIONS_FILE`** - Absolute path to the JSONL file the script writes to (and Warp reads from). When `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` is set, Warp picks a per-run path by default and exports it to the script. Set or override this variable yourself when you want Warp to read from a static, pre-populated declarations file instead of running a script, or whenever you want both Warp and the script to use a specific path you control. ## Declarations file format [Section titled “Declarations file format”](#declarations-file-format) The declarations file is UTF-8 JSONL — one JSON object per non-empty line: snapshot-declarations.jsonl ```json {"version":1,"kind":"repo","path":"/workspace/my-repo"} {"version":1,"kind":"file","path":"/tmp/agent-output.log"} ``` Each line has exactly these fields: * **`version`** - Always `1`. Reserved for future schema versions. * **`kind`** - Either `"repo"` or `"file"`. * **`path`** - A non-empty absolute path. A few rules to follow when writing declarations: * **Paths must be absolute.** Relative paths are rejected and logged as malformed. * **Prefer `repo` over `file` for paths inside a repository.** Warp generates a git diff for each `repo` entry (tracked changes plus untracked, non-gitignored files), so individual `file` entries inside that repo are redundant and dropped before upload. Including a `repo` entry is also more extensible than enumerating files. * **Repos are diffed, not copied wholesale.** Only changed files are uploaded for each `repo` entry, so listing a large repository is cheap when the agent’s changes are small. * **`file` entries are for paths outside any declared repo** — for example, logs the agent wrote to `/tmp` or scratch files in `$HOME`. Malformed lines (invalid JSON, missing fields, unknown `kind`, non-absolute path) are logged as warnings and skipped; they never abort the upload. Caution **Declared paths are uploaded to Warp.** `file` entries upload the file’s contents verbatim, and `repo` entries upload the repo’s git diff (tracked changes plus untracked, non-gitignored files). Before declaring logs, scratch files, or other agent outputs as `file` entries, make sure they don’t contain secrets, credentials, API tokens, or other sensitive data. ## Write a custom declarations script [Section titled “Write a custom declarations script”](#write-a-custom-declarations-script) A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The minimal pattern looks like this: snapshot-declarations.sh ```bash #!/bin/bash set -euo pipefail # Warp sets this to a per-run output path. Fail loudly if it's missing, # so a misconfigured runner doesn't silently overwrite a shared file. if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2 exit 1 fi mkdir -p "$(dirname "$OZ_SNAPSHOT_DECLARATIONS_FILE")" # Find every git repo under the agent's workspace and emit a JSONL # repo declaration for each one. Escape backslashes and double quotes in # the path before writing so paths containing those characters don't # produce malformed JSON (which Warp skips with a warning). find "$PWD" -type d -name .git -prune -print 2>/dev/null \ | while IFS= read -r git_dir; do repo_root="$(cd "$(dirname "$git_dir")" && pwd)" repo_json="$(printf '%s' "$repo_root" | sed 's/\\/\\\\/g; s/"/\\"/g')" printf '{"version":1,"kind":"repo","path":"%s"}\n' "$repo_json" \ >> "$OZ_SNAPSHOT_DECLARATIONS_FILE" done ``` Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the environment your cloud agent runs in: ```bash export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh ``` For a managed [Direct backend](/platform/self-hosting/managed-direct/) worker, set it via the worker’s `environment` config so it’s present when the agent process starts. ### The full bundled script [Section titled “The full bundled script”](#the-full-bundled-script) For reference, this is the canonical declarations script Warp invokes inside the bundled cloud agent image. It’s a richer version of the minimal example above: it honors a colon-separated `OZ_SNAPSHOT_SCAN_ROOTS` override for operators who need to scan repos outside the default workspace, uses `jq` for canonical JSON encoding (which handles `"` and `\` escaping for you), and dedupes against repo declarations already written in the same run so repeated invocations stay additive. snapshot-declarations.sh ```bash #!/bin/bash # Generates the declarations file consumed by the end-of-run snapshot upload pipeline. # # Scans one or more roots for `.git` directories and appends one JSON object per # newly-discovered repository to the declarations file. # # Scan root selection (in order of precedence): # - OZ_SNAPSHOT_SCAN_ROOTS: colon-separated list of absolute paths. Operators can use this # to target repos outside the default workspace. # - $PWD: the Rust driver sets this to the agent's workspace via `Command::current_dir` # before invoking the script, so the default scan root is always the assigned workspace. # # Output file: # - OZ_SNAPSHOT_DECLARATIONS_FILE must be set. The Rust driver sets this to a per-run path # so concurrent runs don't clobber each other. # - The file is created if missing, and appended to if it already exists. Existing lines are # never rewritten, so operator-authored declarations are preserved. # - Repeated invocations within a single run skip already-emitted repo declarations so the # upload pipeline can stay additive without duplicating identical generated entries. set -euo pipefail SCAN_ROOTS_RAW="${OZ_SNAPSHOT_SCAN_ROOTS:-$PWD}" IFS=':' read -r -a SCAN_ROOTS <<< "$SCAN_ROOTS_RAW" if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2 exit 1 fi DECL_FILE="$OZ_SNAPSHOT_DECLARATIONS_FILE" JQ="${OZ_SNAPSHOT_JQ:-/agent/tools/jq}" mkdir -p "$(dirname "$DECL_FILE")" touch "$DECL_FILE" # Dedup set. Seed from repo declarations already emitted by this script so a repeated # invocation within the same run doesn't re-emit repos it already discovered earlier. # Keep the full canonical JSON line as the key; this lets us preserve unrelated JSONL entries # verbatim while ensuring identical generated declarations are emitted at most once. SEEN_FILE="$(mktemp)" trap 'rm -f "$SEEN_FILE"' EXIT "$JQ" --raw-input --compact-output ' fromjson? | select( type == "object" and (. | keys_unsorted | sort == ["kind", "path", "version"]) and .version == 1 and .kind == "repo" and (.path | type == "string") ) | { version: 1, kind: "repo", path: .path } ' "$DECL_FILE" > "$SEEN_FILE" repo_declaration_for_path() { "$JQ" --compact-output --null-input \ --arg path "$1" \ '{ version: 1, kind: "repo", path: $path }' } for root in "${SCAN_ROOTS[@]}"; do [ -d "$root" ] || continue while IFS= read -r git_dir; do repo_root="$(cd "$(dirname "$git_dir")" && pwd)" repo_declaration="$(repo_declaration_for_path "$repo_root")" if grep -Fxq -- "$repo_declaration" "$SEEN_FILE"; then continue fi printf '%s\n' "$repo_declaration" >> "$SEEN_FILE" printf '%s\n' "$repo_declaration" >> "$DECL_FILE" done < <(find "$root" -type d -name .git -prune -print 2>/dev/null) done ``` ## Use a static declarations file [Section titled “Use a static declarations file”](#use-a-static-declarations-file) If the same set of repositories or files should be snapshotted on every run (for example, an unmanaged GitHub Actions job operating on a known checkout), you can skip the script entirely and pre-populate a JSONL file: /etc/oz/snapshot-declarations.jsonl ```json {"version":1,"kind":"repo","path":"/workspace/my-repo"} {"version":1,"kind":"repo","path":"/workspace/shared-libs"} ``` Then point Warp at the file directly: ```bash export OZ_SNAPSHOT_DECLARATIONS_FILE=/etc/oz/snapshot-declarations.jsonl # Do not set OZ_SNAPSHOT_DECLARATIONS_SCRIPT in this mode. ``` Warp reads the file at end-of-run and uploads the listed repos and files. Because the file is the same on every run, this is best for environments where the workspace layout is fixed. ## Disable snapshots [Section titled “Disable snapshots”](#disable-snapshots) To opt out of snapshotting for a single run, pass `--no-snapshot` to the CLI: ```bash oz agent run-cloud --prompt "Fix the failing test" --no-snapshot ``` Snapshotting is also skipped automatically when cloud conversations are disabled for the team. ## Related pages [Section titled “Related pages”](#related-pages) * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Promote a local conversation to a cloud run; the workspace snapshot is what carries your uncommitted changes across. * [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session’s workspace snapshot is what gets restored. * [Self-hosting overview](/platform/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. * [Unmanaged architecture](/platform/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. * [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. # Harnesses in the Automation Platform Canonical page: [/platform/harnesses/](https://docs.warp.dev/platform/harnesses/) > Run third-party harnesses such as Claude Code or Codex as cloud agents. They inherit the same triggers, environments, secrets, and observability as Warp Agent. The Automation Platform can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent.  ## What stays the same [Section titled “What stays the same”](#what-stays-the-same) Third-party harnesses inherit the same Automation Platform features as Warp Agent: * **Triggers** — Slack, Linear, schedules, CI, and API [triggers](/platform/triggers/) launch any harness. * **Environments and secrets** — Reuse the same [environments](/platform/environments/) and [agent secrets](/platform/secrets/). * **Skills and Rules** — Saved [Skills](/agents/capabilities/skills/) and [Rules](/agents/capabilities/rules/) apply across harnesses. * **Observability** — Every run produces a transcript and shareable session in the [cloud agent dashboard](/platform/managing-cloud-agents/). ## Plan requirements [Section titled “Plan requirements”](#plan-requirements) Third-party harnesses require a Build plan or higher. On the Free plan, cloud agent runs use Warp Agent, and choosing another harness returns an upgrade prompt. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes. ## Billing [Section titled “Billing”](#billing) Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run’s sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the [multi-agent orchestration](/platform/orchestration/) layer. ## How to switch harnesses [Section titled “How to switch harnesses”](#how-to-switch-harnesses) ### Warp app [Section titled “Warp app”](#warp-app) In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input.  The Agent harness selector. ### Web app [Section titled “Web app”](#web-app) On the new run or new schedule pane, choose the harness in the **Harness** field. ### API and SDK [Section titled “API and SDK”](#api-and-sdk) Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/reference/api-and-sdk/) for the exact field names. ## Harness identifiers [Section titled “Harness identifiers”](#harness-identifiers) Surfaces that take the harness as a string use `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code` — unless the surface explicitly accepts that alias: * **API and SDK** — the agent config’s `harness.type` accepts `oz`, `claude`, or `codex`. * **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`. * **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts `oz`, `claude`, `codex`, or `gemini`, plus `claude-code` as an alias for `claude`. Where the alias is accepted, it selects the same Claude Code harness as `claude`. Everywhere else — including the API — only the canonical identifiers are valid, so prefer them in anything you script, sync, or store. ## Related pages [Section titled “Related pages”](#related-pages) * [Warp Agent with the Automation Platform](/platform/harnesses/warp-agent/) — the Automation Platform‘s default first-party harness. * [Claude Code with the Automation Platform](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. * [Codex with the Automation Platform](/platform/harnesses/codex/) — Codex as a cloud harness. * [Authentication](/platform/harnesses/authentication/) — connect credentials and launch Claude Code or Codex. * [Multi-agent orchestration](/platform/orchestration/) — run parent and child agents across harnesses and locations. * [Third-party CLI agents in the Warp terminal](/agents/cli-agents/overview/) — run Claude Code, Codex, and other CLI agents locally. # Third-party cloud agent authentication Canonical page: [/platform/harnesses/authentication/](https://docs.warp.dev/platform/harnesses/authentication/) > Connect Anthropic or OpenAI credentials to the Automation Platform to run Claude Code or Codex as cloud agents. Third-party cloud agent authentication in the Automation Platform stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness. Auth secrets can be scoped to a **team** (available to all teammates’ runs) or **personal** (only your own runs), like any other Warp-managed secret. A [factory agent](/factories/factory-agents/#configuring-a-third-party-harness) can only select team-scoped secrets, since a factory’s runs aren’t tied to one person. Personal secrets remain available when you start an ad hoc cloud run. ## Connecting Claude Code credentials [Section titled “Connecting Claude Code credentials”](#connecting-claude-code-credentials) Claude Code is Anthropic’s agentic coding tool. For more on Claude Code authentication, see [Anthropic’s Claude Code auth docs](https://code.claude.com/docs/en/authentication). ### Create an Anthropic API key [Section titled “Create an Anthropic API key”](#create-an-anthropic-api-key) 1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in or create an account. 2. Confirm your account has API credits. Claude Code runs are billed against your Anthropic API balance. 3. Navigate to the API keys section, then click **Get API key**. 4. Create a new API key and copy the value. The Automation Platform also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. ### Store the API key [Section titled “Store the API key”](#store-the-api-key) #### Warp desktop app [Section titled “Warp desktop app”](#warp-desktop-app) Start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential. #### Web app [Section titled “Web app”](#web-app) Start a [new run](https://oz.warp.dev/runs/new), choose **Claude Code** as the harness, and add a new key in the Claude Code auth secret dialog.  The Claude Code auth secret dialog. #### CLI [Section titled “CLI”](#cli) ```bash oz secret create claude api-key --team ``` Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. **Expected outcome.** `oz secret list` shows the new secret with the matching Anthropic credential type. The value is never displayed. ## Connecting Codex credentials [Section titled “Connecting Codex credentials”](#connecting-codex-credentials) Codex is OpenAI’s coding agent. For more on Codex authentication, see [OpenAI’s Codex auth docs](https://developers.openai.com/codex/auth). Caution A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a separate OpenAI API key with API credits. ### Create an OpenAI API key [Section titled “Create an OpenAI API key”](#create-an-openai-api-key) 1. Go to the [OpenAI Platform](https://platform.openai.com/) and sign in (or create an account). 2. Confirm your account has API credits. Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription. 3. Navigate to the API keys section, then click **Create API key**. 4. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key. 5. Click **Create secret key**, then copy the value. ### Store the API key [Section titled “Store the API key”](#store-the-api-key-1) #### Warp desktop app [Section titled “Warp desktop app”](#warp-desktop-app-1) Start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential. #### Web app [Section titled “Web app”](#web-app-1) Start a [new run](https://oz.warp.dev/runs/new), choose **Codex** as the harness, and add a new key in the Codex auth secret dialog. #### CLI [Section titled “CLI”](#cli-1) ```bash oz secret create codex api-key --team ``` Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. **Expected outcome.** `oz secret list` shows the new secret with the matching OpenAI credential type. The value is never displayed. ## Managing harness auth secrets [Section titled “Managing harness auth secrets”](#managing-harness-auth-secrets) Auth secrets follow the same management commands as any other Warp-managed secret. See [Cloud agent secrets](/platform/secrets/) for the full reference. Common tasks: ```bash # List secrets you can see oz secret list # Rotate a secret value (prompts for the new value) oz secret update --team --value ANTHROPIC_API_KEY # Update the description oz secret update --team --description "Rotated 2026-05-12; owned by platform team" ANTHROPIC_API_KEY # Delete a secret (irreversible) oz secret delete --team ANTHROPIC_API_KEY ``` Caution Deleting an auth secret breaks any scheduled or integration-triggered run that references it by name. Update the schedules and integrations to point at a new secret first. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Claude Code or Codex run fails with an authentication error.**\ Confirm the run was started with a harness auth secret selected. From the Oz web app‘s run detail pane, the **Harness auth secret** field shows which secret (if any) was used. Re-launch the run with the correct secret selected, or create one if your team doesn’t have one yet. **The harness auth secret dropdown is empty.**\ The dropdown only lists secrets whose type matches the selected harness — Anthropic types for Claude Code, OpenAI for Codex. If you stored the credential as a raw value, recreate it using the typed flow above. **The selected harness is disabled.**\ Your team admin has disabled the harness for your workspace. Contact your admin or pick a different harness for the run. ## Related pages [Section titled “Related pages”](#related-pages) * [Harnesses in the Automation Platform](/platform/harnesses/) — overview of third-party harnesses in the Automation Platform. * [Claude Code in Warp](/agents/cli-agents/claude-code/) — run Claude Code locally in the Warp terminal. * [Codex CLI in Warp](/agents/cli-agents/codex/) — run Codex locally in the Warp terminal. * [Cloud agent secrets](/platform/secrets/) — the full Warp-managed secrets reference. # Claude Code with the Automation Platform Canonical page: [/platform/harnesses/claude-code/](https://docs.warp.dev/platform/harnesses/claude-code/) > Run Claude Code with the Automation Platform. Strong at code review, deep bug investigation, large feature planning, and frontend or UI work. Claude Code is Anthropic’s agentic coding tool. Running it with the Automation Platform puts Claude Code inside a Warp-managed environment and connects it to the rest of the Automation Platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses. ## Key features [Section titled “Key features”](#key-features) * **Cloud orchestration** - Launch Claude Code from any Automation Platform trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, Linear issues, or GitHub Actions. * **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants. * **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger [multi-agent orchestration](/platform/orchestration/). ## Available models [Section titled “Available models”](#available-models) The Claude Code harness exposes Anthropic’s coding-tuned model lineup. Common choices include: * `best` - Resolves to the current top-of-line Claude model. * `opus`, `sonnet`, `haiku` - Aliases that resolve to the current default for that family. For the full list — including 1M-context variants for very large codebases and planning-tuned models — open the model picker in the Warp app’s Cloud Mode or the **Model** field on the Oz web app‘s new-run pane. ## Credentials and billing [Section titled “Credentials and billing”](#credentials-and-billing) Claude Code calls Anthropic directly using credentials your team provides. The Automation Platform supports three Anthropic credential types, stored as [Warp-managed secrets](/platform/secrets/): * **Anthropic API key** - For direct Anthropic API access. * **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. * **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. Anthropic bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run’s sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials). ## Starting a Claude Code run [Section titled “Starting a Claude Code run”](#starting-a-claude-code-run) * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. * **Oz web app** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets. * **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). ## Related pages [Section titled “Related pages”](#related-pages) * [Harnesses in the Automation Platform](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. * [Authentication](/platform/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets. * [Warp Agent with the Automation Platform](/platform/harnesses/warp-agent/) — the Automation Platform‘s default harness, the only one that can orchestrate Claude Code subagents. * [Multi-agent orchestration](/platform/orchestration/) — coordinate a Warp Agent parent with Claude Code children across local and cloud runs. * [Managing cloud agents](/platform/managing-cloud-agents/) — inspect Claude Code cloud runs in the Agent Management Panel and the Runs page. * [Codex with the Automation Platform](/platform/harnesses/codex/) — Codex as a cloud harness. * [Claude Code in Warp](/agents/cli-agents/claude-code/) — Claude Code in your local Warp terminal. * [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) — configure Claude Code as a factory agent’s harness. # Codex with the Automation Platform Canonical page: [/platform/harnesses/codex/](https://docs.warp.dev/platform/harnesses/codex/) > Run Codex with the Automation Platform for codebase migrations, release coordination, batch test generation, and backend or DevOps automation. Codex is OpenAI’s coding agent. Running it with the Automation Platform puts Codex inside a Warp-managed environment and connects it to the rest of the Automation Platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses. ## Key features [Section titled “Key features”](#key-features) * **Cloud orchestration** - Launch Codex from any Automation Platform trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, Linear issues, or GitHub Actions. * **Codex model picker** - Choose the OpenAI model Codex uses, including the GPT-5 lineup and Codex-tuned variants, each available at a configurable reasoning level. * **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger [multi-agent orchestration](/platform/orchestration/). ## Available models [Section titled “Available models”](#available-models) The Codex harness exposes OpenAI’s Codex-tuned and general coding models, each available at a configurable reasoning level (low, medium, high, or extra-high). Common choices include: * `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` - The latest generation of Codex-tuned coding models. * `gpt-5.5` - The prior generation’s coding model, still supported. * `gpt-5.4`, `gpt-5.4-mini` - Fallback options for accounts without access to the newer models; `gpt-5.4-mini` is faster and lower-cost for lighter coding tasks or subagents. * `gpt-5.3-codex` - An older Codex-tuned model, still available as an alternative. Codex has no `default` model that picks automatically; every option names a specific model and reasoning level. For the full list, including Codex-tuned and general models, open the model picker on the Oz web app‘s new-run pane. For details on each model, see [OpenAI’s Codex model docs](https://developers.openai.com/codex/models). ## Credentials and billing [Section titled “Credentials and billing”](#credentials-and-billing) Codex calls OpenAI directly using credentials your team provides. The Automation Platform supports one credential type today, stored as a [Warp-managed secret](/platform/secrets/): * **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. OpenAI bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run’s sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. For setup steps, see [Connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials). ## Starting a Codex run [Section titled “Starting a Codex run”](#starting-a-codex-run) * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. * **Oz web app** - On the new run or new schedule pane, choose **Codex** in the **Harness** field. A **Codex auth secret** field appears below it; pick the OpenAI secret your team has stored. * **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). ## Related pages [Section titled “Related pages”](#related-pages) * [Harnesses in the Automation Platform](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. * [Authentication](/platform/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets. * [Warp Agent with the Automation Platform](/platform/harnesses/warp-agent/) — the Automation Platform‘s default harness, the only one that can orchestrate Codex subagents. * [Multi-agent orchestration](/platform/orchestration/) — coordinate a Warp Agent parent with Codex children across local and cloud runs. * [Managing cloud agents](/platform/managing-cloud-agents/) — inspect Codex cloud runs in the Agent Management Panel and the Runs page. * [Claude Code with the Automation Platform](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. * [Codex CLI in Warp](/agents/cli-agents/codex/) — Codex in your local Warp terminal. * [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) — configure Codex as a factory agent’s harness. # Warp Agent with the Automation Platform Canonical page: [/platform/harnesses/warp-agent/](https://docs.warp.dev/platform/harnesses/warp-agent/) > Warp Agent is the default Automation Platform harness, with multi-model routing, full terminal access, and cross-harness subagent orchestration. Warp Agent is the harness Warp builds and ships with the Automation Platform. It’s the default for every cloud agent run unless you pick another harness, and it’s the only harness that can spawn cross-harness subagents (for example, a Warp Agent parent dispatching a Claude Code or Codex child). Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal. Running it as a cloud harness gives you the same behavior — model routing, tool access, Skills, Rules, Memory — without tying execution to a single laptop. ## Key features [Section titled “Key features”](#key-features) * **Multi-model auto-routing** - Routes between Anthropic, OpenAI, Google, and Fireworks-hosted models. Choose a specific model, or let Warp pick via `auto`, `auto-efficient`, `auto-genius`, or `auto-open`. See [Model choice](/agents/inference/model-choice/) for the full catalog. * **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers, giving cloud runs the same toolbelt Warp Agent uses locally. * **Platform-native context** - Reads [Codebase Context](/agents/capabilities/codebase-context/), applies [Rules](/agents/capabilities/rules/), reuses saved [Skills](/agents/capabilities/skills/), and respects Memory and Warp Drive context with no extra setup. * **Multi-repo execution** - Clones every repo configured on the [environment](/platform/environments/) and works across them in a single run. * **Cross-harness orchestration parent** - A Warp Agent parent run can spawn Claude Code or Codex subagents and coordinate their outputs in [multi-agent orchestration](/platform/orchestration/). Other harnesses cannot act as parents in a multi-harness orchestration. * **No extra credentials** - Warp Agent uses your existing Warp account and credits. There’s no separate API key to configure. ## How it works [Section titled “How it works”](#how-it-works) Warp Agent is the same agent runtime as Agent Mode in the Warp terminal: it plans, calls tools, edits code, runs tests, and reports progress. The cloud platform adds the [environment](/platform/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [cloud agent dashboard](/platform/managing-cloud-agents/). Team admins can disable any harness for their workspace. Users on that team can only start runs with the harnesses that remain enabled. ### Available models [Section titled “Available models”](#available-models) Warp Agent supports the full Warp model catalog. Configure the model per [Agent Profile](/agents/capabilities/agent-profiles-permissions/), or pick one at run time. See [Model choice](/agents/inference/model-choice/) for the supported model IDs, including the `auto`, `auto-efficient`, `auto-genius`, and `auto-open` routing options. ### Cross-harness orchestration [Section titled “Cross-harness orchestration”](#cross-harness-orchestration) Warp Agent is the orchestration host for multi-harness runs. [Multi-agent orchestration](/platform/orchestration/) covers the parent/child model, run states, and patterns; a typical multi-harness pattern looks like: 1. A Warp Agent parent run analyzes a task and breaks it into subtasks. 2. The parent dispatches Claude Code subagents for steps that need careful review and Codex subagents for high-volume edits. 3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply). Subagents run in the same environment as the parent and share the same secrets, MCP servers, and integrations. The transcript shows the full tree, so reviewers can see exactly which subagent did what. ## When to choose Warp Agent [Section titled “When to choose Warp Agent”](#when-to-choose-warp-agent) * The task spans multiple repos, languages, or domains. * You want model auto-routing instead of pinning one provider. * The run needs to orchestrate other harnesses as subagents. * You want the deepest integration with Warp’s platform features (Skills, Rules, Memory, Codebase Context). * You’re not sure which harness fits — Warp Agent is the safe default and can delegate to other harnesses when it decides that’s the better fit. ## Starting a Warp Agent run [Section titled “Starting a Warp Agent run”](#starting-a-warp-agent-run) Warp Agent is the default, so there’s nothing extra to configure. * **Warp app** - Start a cloud agent run from the input. The **Agent harness** dropdown defaults to **Warp Agent**. * **Oz web app** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. * **Oz CLI** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. * **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/reference/api-and-sdk/). For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). ## Related pages [Section titled “Related pages”](#related-pages) * [Harnesses in the Automation Platform](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. * [Claude Code with the Automation Platform](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. * [Codex with the Automation Platform](/platform/harnesses/codex/) — Codex as a cloud harness. * [Multi-agent orchestration](/platform/orchestration/) — parent/subagent runs, including cross-harness subagents Warp Agent can spawn. * [Model choice](/agents/inference/model-choice/) — the model catalog Warp Agent routes across. * [Agent Profiles and permissions](/agents/capabilities/agent-profiles-permissions/) — configure the default model, autonomy, and tool access for Warp Agent. * [Skills as agents](/platform/skills-as-agents/) — turn a saved skill into a reusable Warp Agent run. # Integrations Overview Canonical page: [/platform/integrations/](https://docs.warp.dev/platform/integrations/) > Configure Warp's first-party integrations by creating environments, connecting GitHub, and enabling agents to run your code and automate development workflows. Warp integrations let your team trigger agents directly from the terminal, or from tools like [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), [Jira](/platform/integrations/jira/), and [GitHub](/platform/integrations/github/). Once set up, agents can: * Read conversation or issue context * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf Integrations are one way to start a cloud agent. For the full set, including schedules, the Oz CLI, and the API, see [Triggers](/platform/triggers/). If you’re deciding which one to use, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). Integrations run on the [Automation Platform](/platform/overview/) (formerly Oz), which handles the trigger, the [environment](/platform/environments/) the agent executes in, and the record of each run. *** ## Get started [Section titled “Get started”](#get-started) Use the setup walkthrough below for a quick look at how environments connect to integrations, then choose the guide that matches what you want to do next.  * [Integrations quickstart](/platform/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. * [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. * [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/) - Trigger agents from team conversations, issues, and comments. * [GitHub](/platform/integrations/github/) - Mention `@warp-agent` on issues, pull requests, and review comments to start agents that reply in the thread. * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events. * [GitLab](/platform/integrations/gitlab/) - Connect GitLab.com repos natively, or self-managed instances with tokens and Warp-managed secrets. * [Bitbucket](/platform/integrations/bitbucket/) and [Azure DevOps](/platform/integrations/azure-devops/) - Connect repositories with tokens and Warp-managed secrets. * [AWS, GCP, and other cloud providers](/platform/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor and review integration-triggered runs across your team by source, status, or creator. # Azure DevOps integration Canonical page: [/platform/integrations/azure-devops/](https://docs.warp.dev/platform/integrations/azure-devops/) > Connect cloud agents to Azure DevOps repos using personal access tokens and Warp-managed secrets. Cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Automation Platform trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate an Azure DevOps personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at https://oz.warp.dev](https://oz.warp.dev)) * A repository hosted on Azure DevOps (cloud or self-hosted) * The [Oz CLI](/reference/cli/) installed and authenticated *** ## Step 1: Generate a personal access token [Section titled “Step 1: Generate a personal access token”](#step-1-generate-a-personal-access-token) 1. Sign in to your Azure DevOps organization at `dev.azure.com/{your-org}`. 2. Click the user settings icon (gear) in the top-right corner, then click **Personal access tokens**. 3. Click **+ New Token**. 4. Enter a descriptive name for the token (e.g. `warp-oz-agent`), choose the organization it applies to, and set an expiration date that matches your team’s rotation policy. 5. Under **Scopes**, select **Custom defined**, then select **Code** > **Read**. 6. Click **Create**. 7. Copy the token value immediately. Azure DevOps will not show it again. *** ## Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team AZURE_DEVOPS_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. If you need to update a secret value, run: ```bash oz secret update --team --value AZURE_DEVOPS_TOKEN ``` *** ## Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your Azure DevOps repo via a setup command instead. 1. Run the following command: ```bash oz environment create \ --name "my-azure-devops-env" \ --docker-image \ --setup-command 'git clone https://$AZURE_DEVOPS_TOKEN@dev.azure.com/your-org/your-project/_git/your-repo' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$AZURE_DEVOPS_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `your-org` with your Azure DevOps organization name * `your-project` with your Azure DevOps project name * `your-repo` with your repository name * For Azure DevOps Server (self-hosted), replace `dev.azure.com` with your server’s hostname. * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Step 4: Test your environment [Section titled “Step 4: Test your environment”](#step-4-test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. 1. Run the following command, replacing `` with the environment ID from Step 3: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: * **Slack** — Tag **@warp** in a message to start an agent run against your Azure DevOps repo. See [Slack](/platform/integrations/slack/). * **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). # Bitbucket integration Canonical page: [/platform/integrations/bitbucket/](https://docs.warp.dev/platform/integrations/bitbucket/) > Connect cloud agents to Bitbucket repos using access tokens and Warp-managed secrets. Cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub and GitLab, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Automation Platform trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a Bitbucket access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. Bitbucket Cloud and Bitbucket Data Center/Server use different token types: * **Bitbucket Cloud** uses **API tokens**, created through your Atlassian Account settings. * **Bitbucket Data Center/Server** uses **HTTP access tokens**, created through your Bitbucket profile settings. Follow the section that matches your setup. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at https://oz.warp.dev](https://oz.warp.dev)) * A repository hosted on Bitbucket (Cloud or Data Center/Server) * The [Oz CLI](/reference/cli/) installed and authenticated *** ## Bitbucket Cloud [Section titled “Bitbucket Cloud”](#bitbucket-cloud) ### Step 1: Generate an API token [Section titled “Step 1: Generate an API token”](#step-1-generate-an-api-token) 1. Click your avatar in the upper-right corner of Bitbucket, then click **Account settings**. 2. On the Atlassian Account page that opens, click the **Security** tab. 3. Click **Create and manage API tokens**, then click **Create API token with scopes**. 4. Enter a name for the token (e.g. `warp-oz-agent`) and choose an expiration date. 5. Click **Next**. 6. Select **Bitbucket** as the app and click **Next**. 7. Search for `repository` in the **Select Bitbucket scopes** search box, then select **read:repository:bitbucket** (View your repositories). 8. Click **Next**. 9. Click **Create token**. 10. Copy the token value immediately. It is only shown once and cannot be retrieved later. *** ### Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team BITBUCKET_API_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. If you need to update a secret value, run: ```bash oz secret update --value BITBUCKET_API_TOKEN ``` *** ### Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. Use the static username `x-bitbucket-api-token-auth` in the clone URL — this is a Bitbucket-specific placeholder that works with API tokens and means you don’t need to store your Bitbucket username separately. 1. Run the following command: ```bash oz environment create \ --name "my-bitbucket-cloud-env" \ --docker-image \ --setup-command 'git clone https://x-bitbucket-api-token-auth:$BITBUCKET_API_TOKEN@bitbucket.org/your-workspace/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$BITBUCKET_API_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `bitbucket.org/your-workspace/your-repo.git` with your actual repository URL * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Bitbucket Data Center / Server [Section titled “Bitbucket Data Center / Server”](#bitbucket-data-center--server) ### Step 1: Generate an HTTP access token [Section titled “Step 1: Generate an HTTP access token”](#step-1-generate-an-http-access-token) 1. Click your profile avatar in Bitbucket, then click **Manage account**. 2. In the left sidebar, click **HTTP access tokens**. 3. Click **Create token**. 4. Enter a name for the token (e.g. `warp-oz-agent`) and choose an expiration date if required by your administrator. 5. Under **Permissions**, choose **Read** for the **Repository** permission. 6. Click **Create token**. 7. Copy the token value immediately. It is only shown once and cannot be retrieved later. *** ### Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret-1) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team BITBUCKET_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. If you need to update a secret value, run: ```bash oz secret update --value BITBUCKET_TOKEN ``` *** ### Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command-1) Create an environment that uses your token to clone the repository at the start of each agent run. 1. Run the following command: ```bash oz environment create \ --name "my-bitbucket-dc-env" \ --docker-image \ --setup-command 'git clone -c "http.extraHeader=Authorization: Bearer $BITBUCKET_TOKEN" https://your-server.com/scm/your-project/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets, so `$BITBUCKET_TOKEN` is expanded at runtime inside the container rather than in your current shell. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `your-server.com/scm/your-project/your-repo.git` with your Bitbucket Data Center/Server repository URL. The `/scm/` path segment is standard for Bitbucket Data Center/Server. * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Test your environment [Section titled “Test your environment”](#test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. This applies to both Bitbucket Cloud and Bitbucket Data Center / Server. 1. Run the following command, replacing `` with the environment ID from Step 3 of whichever setup you followed: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: * **Slack** — Tag **@warp** in a message to start an agent run against your Bitbucket repo. See [Slack](/platform/integrations/slack/). * **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). # Cloud Providers (Preview) Canonical page: [/platform/integrations/cloud-providers/](https://docs.warp.dev/platform/integrations/cloud-providers/) > Connect cloud agents to your AWS and GCP services. Cloud agents can securely access AWS, GCP, and other cloud providers using short-lived OpenID Connect (OIDC) credentials. Configure your cloud agent environment to automatically authenticate to your cloud provider without storing long-lived keys, using Warp’s built-in OIDC federation support. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account. You can [create an account in the Oz web app](https://oz.warp.dev). * A cloud provider account Follow the section for your cloud provider. *** ## AWS [Section titled “AWS”](#aws) ### Step 1: Create an OIDC identity provider [Section titled “Step 1: Create an OIDC identity provider”](#step-1-create-an-oidc-identity-provider) The first step is to configure your AWS account to trust OIDC tokens produced by the Automation Platform. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 2. Click **Identity Providers**, then click **Add provider**. 3. Set the provider type to **OpenID Connect**. 4. Set the **Provider URL** to `https://app.warp.dev`. 5. Set the **Audience** to `sts.amazonaws.com`. 6. Copy the ARN of the new identity provider, which will look like: `arn:aws:iam:::oidc-provider/app.warp.dev`. *** ### Step 2: Configure an IAM role [Section titled “Step 2: Configure an IAM role”](#step-2-configure-an-iam-role) Next, you will need to set up an AWS IAM role with a trust policy that links it to the OIDC provider. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 2. Click **Roles**, then click **Create role**. 3. Select **Custom trust policy**, and fill in the following JSON trust policy: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowOzFederation", "Effect": "Allow", "Principal": { "Federated": "" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com" }, "StringLike": { "app.warp.dev:sub": "scoped_principal:/*" } } } ] } ``` You will need to replace: * `` with the ARN of the OIDC provider added in Step 1. * `` with your Warp team UID. This is the last component of your [Admin Panel](/enterprise/team-management/admin-panel/) URL. For example, if the Admin Panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. You can also get your team UID from the `oz whoami` command. The example above uses `StringLike` with the `scoped_principal:/*` pattern to allow any user or automation on your team to assume the role. See [the subject claim](#subject-sub) for the full format of `app.warp.dev:sub`. To restrict the role to a specific user, use `StringEquals` with the fully qualified subject: ```json ... "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com", "app.warp.dev:sub": "scoped_principal:/user:" } } ... ``` To allow multiple specific principals, use a list of subjects: ```json ... "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com", "app.warp.dev:sub": [ "scoped_principal:/user:", "scoped_principal:/user:", "scoped_principal:/service_account:" ] } } ... ``` 4. Click **Next** and add permissions policies. These policies determine what agents can access in your AWS account. 5. Click **Next** and enter a role name and optional description. 6. Click **Create role**, then open the role and note down the role ARN. This will be of the form `arn:aws:iam:::role/`. *** ### Step 3: Enable AWS federation in your cloud agent environment [Section titled “Step 3: Enable AWS federation in your cloud agent environment”](#step-3-enable-aws-federation-in-your-cloud-agent-environment) Finally, configure the cloud agent environment to use your new AWS role. 1. Open the [Oz web app](https://oz.warp.dev). 2. Create or edit an environment. See [Environments](/platform/oz-web-app/#environments) for instructions. 3. Expand the **AWS** section and enter the AWS role ARN from Step 2. 4. Save the environment. Caution Currently, AWS federation can only be configured in the Oz web app, not the CLI. Agents running in this environment will now automatically assume the configured role when using the `aws` CLI or a compatible SDK. *** ## GCP [Section titled “GCP”](#gcp) ### Step 1: Create a Workload Identity Pool and Provider [Section titled “Step 1: Create a Workload Identity Pool and Provider”](#step-1-create-a-workload-identity-pool-and-provider) The Automation Platform GCP integration uses [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation). You will need to configure a pool and provider to trust OIDC tokens produced by the Automation Platform. These instructions use the `gcloud` tool. You can also follow the OIDC instructions in [Configure Workload Identity Federation with other identity providers](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) to use the GCP console or Terraform. 1. Create a Workload Identity Pool using the `gcloud` CLI: ```bash gcloud iam workload-identity-pools create "" --location=global ``` Replace `` with the desired identifier for your pool, such as `oz-agent-pool`. 2. Create a Provider within the pool: ```bash gcloud iam workload-identity-pools providers create-oidc \ "" \ --location=global \ "--workload-identity-pool=" \ --issuer-uri="https://app.warp.dev" \ "--attribute-mapping=google.subject=assertion.sub,google.groups=assertion.teams,attribute.environment=assertion.environment" \ "--attribute-condition='' in assertion.teams" ``` Replace `` with the ID you used above, and `` with the desired identifier for your provider, such as `oz-oidc-provider`. Replace `` with the UID of your Warp team. This is the last component of your [Admin Panel](/enterprise/team-management/admin-panel/) URL. For example, if the admin panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. Caution If you do not set an attribute condition, then *any cloud agent* will be able to use your Workload Identity Federation provider, even if it does not belong to your team. ### Step 2: Configure IAM policies [Section titled “Step 2: Configure IAM policies”](#step-2-configure-iam-policies) You will need to configure IAM policies in GCP that allow agents in the Workload Identity Federation pool access to resources. To give all agents on your team read-only access to all Compute Engine resources in a project, for example, you would run: ```bash gcloud projects add-iam-policy-binding \ --member "principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools//group/" \ --role "roles/compute.viewer" ``` See [Workload Identity Federation principal types](https://docs.cloud.google.com/iam/docs/workload-identity-federation#principal-types) for the full syntax supported. ### Step 3: Enable Workload Identity Federation in your cloud agent environment [Section titled “Step 3: Enable Workload Identity Federation in your cloud agent environment”](#step-3-enable-workload-identity-federation-in-your-cloud-agent-environment) Finally, configure the cloud agent environment to use your Workload Identity Federation provider. 1. Open the [Oz web app](https://oz.warp.dev). 2. Create or edit an environment. See [Environments](/platform/oz-web-app/#environments) for instructions. 3. Expand the **GCP** section and enter the project number, pool ID, and provider ID from Step 1. 4. Save the environment. Caution Currently, Workload Identity Federation can only be configured in the Oz web app, not the CLI. Agents running in this environment will now automatically configure [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) to use the configured pool. Both the `GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE` environment variables are set, so both the `gcloud` CLI and official Google SDKs will use the Automation Platform federated credentials. The Automation Platform uses [**executable-sourced credentials**](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create-credential-config) to configure ADC for automatic token rotation. #### Automatic `gcloud` sign-in [Section titled “Automatic gcloud sign-in”](#automatic-gcloud-sign-in) Environment variables alone are enough for the Google SDKs, but `gcloud` reports no active account until it signs in through its own auth system, and some tooling depends on an active account. During provider setup, the Automation Platform therefore also runs `gcloud auth login` against the federated credential file so `gcloud` reports the federated identity as its active account. This step is best-effort and never blocks the run: * **`gcloud` isn’t installed** - The Automation Platform skips the sign-in. The ADC environment variables still provide credentials to the Google SDKs. * **Sign-in fails or times out** - The Automation Platform logs the failure and continues. The ADC environment variables still work, so a run only loses the active-account convenience. To confirm the account inside a run, use `gcloud auth list`. ## Other providers [Section titled “Other providers”](#other-providers) To authenticate from the Automation Platform to another provider that supports OIDC federation, you can issue tokens directly. Within the agent environment, use the `oz federate issue-token` command to produce an OIDC token with your provider as the audience: ```bash oz federate issue-token --run-id --audience your-provider.com --output-format json ``` Replace `` with the current agent run’s ID. Optionally, add `--duration ` to customize the token validity. Tokens are valid for between 5 minutes and 3 hours. You can then exchange this token for provider-specific credentials. ## OIDC token claims [Section titled “OIDC token claims”](#oidc-token-claims) All Automation Platform OIDC tokens include standard claims like `iss` (issuer) and `iat` (issued at). ### Audience [Section titled “Audience”](#audience) The `aud` claim will reflect the default for your cloud provider. For AWS, this is always `sts.amazonaws.com`. For GCP, it is derived from the Workload Identity Federation provider, such as `https://iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/`. ### Subject (`sub`) [Section titled “Subject (sub)”](#subject-sub) The `sub` claim is set to the identity that an agent is executing as. This will either be a Warp user ID or an autogenerated account ID for team-scoped agent runs. By default, the `sub` claim uses the format `:`: * `user:abc123def456`: Identifies a user with ID `abc123def456` * `service_account:abc123def456`: Identifies your autogenerated team account When authenticating to AWS, the Automation Platform will use a different `sub` claim format, because AWS trust policies cannot match on custom OIDC claims. The format above will be prefixed with your team UID: * `scoped_principal:xyz789/user:abc123def456`: Identifies the user `abc123def456`, who is a member of team `xyz789`. * `scoped_principal:user:abc123def456`: Identifies the user `abc123def456`, who is not on any team. * `scoped_principal:xyz789/service_account:abc123def456`: Identifies the autogenerated account for team `xyz789`. In addition, user OIDC tokens include an `email` claim with the user’s email address. To get possible user ID values, use the `oz whoami` command: ```bash oz whoami User ID: abc123 Email: user@warp.dev Team ID: xyz789 Team Name: My Team ``` You can also check the user IDs from past runs using the Oz API & SDK: ```bash curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY" { "runs": [ { ... "creator": { "type": "user", "uid": "", "display_name": "User Name", "email": "user@warp.dev" } } ] } ``` ### Team [Section titled “Team”](#team) Tokens for principals on a team include a `teams` claim listing the UIDs of the teams the principal belongs to. Users on multiple teams get multiple values, and users on no team get no `teams` claim. ### Run [Section titled “Run”](#run) The following claims are derived from an agent run: * `run_id`: the unique identifier for the individual run. This is not suitable for configuring access, but is useful to log for debugging. * `environment`: the unique identifier for the agent’s [Environment](/platform/environments/). * `agent_name`: the name of the [Skill](/platform/skills-as-agents/) that the agent was invoked with. * `skill_spec`: the canonical identifier for the skill, such as `github-org/github-repo:.warp/skills/skill-name/SKILL.md`. * `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/platform/self-hosting/). ### Example token [Section titled “Example token”](#example-token) The following OIDC token references an agent running as a specific Warp user: ```json // JWT Header { "typ": "JWT", "alg": "ES256", "kid": "" } // JWT Payload { "aud": ["sts.amazonaws.com"], "sub": "user:", "email": "user@warp.dev", "teams": [""], "run_id": "", "environment": "", "agent_name": "", "skill_spec": "", "host": "warp", "iss": "https://app.warp.dev", "jti": "", "exp": 1775210175, "iat": 1775206575, "nbf": 1775206575 } ``` # GitHub integration Canonical page: [/platform/integrations/github/](https://docs.warp.dev/platform/integrations/github/) > Mention @warp-agent on a GitHub issue, pull request, or review comment to start a cloud agent that replies in the thread and opens pull requests. The GitHub integration lets your team start cloud agents from GitHub itself. Mention **@warp-agent** in an issue comment, a pull request review comment, or the body of a new pull request, and Warp starts a cloud agent that reads the surrounding context, works the task in your codebase, and posts its progress and results back into the same thread. The integration is powered by the **Warp Factories** GitHub App. Once a team admin installs the app and enables the GitHub organization, every teammate who has connected their GitHub account can trigger agents from GitHub without leaving a review or an issue. *** ## What the GitHub integration does [Section titled “What the GitHub integration does”](#what-the-github-integration-does) * **@warp-agent mentions** - Mention the agent in a comment or pull request body to start a cloud agent run with the issue or pull request as context. * **In-thread status** - Warp posts a status comment carrying the run link, then follows up with progress comments and a final summary in the same issue, pull request, or review thread. * **Thread-aware follow-ups** - Mention the agent again in the same thread and Warp continues the existing run instead of starting a new one. * **Automatic repository access** - The repository the event came from is cloned for the run, alongside any repositories in the environment you configure for the integration. * **Team-scoped configuration** - A Warp team admin controls which GitHub organizations are enabled, and which environment, model, agent, and prompt GitHub-triggered runs use. ## How it works [Section titled “How it works”](#how-it-works) When you mention `@warp-agent`, GitHub sends the event to Warp through the Warp Factories GitHub App installation. Warp then: 1. Confirms the comment or pull request body contains the `@warp-agent` mention and that the author is a person rather than a bot. 2. Maps the GitHub App installation to a Warp team using the organizations enabled in the Admin Panel. 3. Maps the GitHub account that posted the mention to a Warp account, so the run is attributed to that person. 4. Posts a status comment in the thread and starts the cloud agent run with the issue, pull request, or review thread as context. 5. Posts progress updates and a final summary back into the thread, including any pull requests the agent opened and branches it pushed. The agent replies through Warp’s status comments, which are posted by the GitHub App. Agent replies aren’t posted from the triggering user’s account. ### Supported triggers [Section titled “Supported triggers”](#supported-triggers) The integration starts or continues a run for these GitHub events when the text contains `@warp-agent`: * **Issue comments** - A new comment on an issue. Warp reads the issue title, description, labels, state, and the recent comment thread. * **Pull request comments** - A new top-level comment on a pull request. These continue the pull request’s existing run when one exists. * **Pull request review comments** - A new inline review comment or a reply in a review thread. Warp reads the pull request, the review thread, and the diff of the commented file, and replies inside the same review thread. * **New pull requests** - A pull request opened with `@warp-agent` in its description. Warp reads the title, description, and the head and base branches. Mentions in other places don’t start a run. Editing a comment to add the mention, mentioning the agent in an issue or pull request title, and mentions posted by bots are all ignored. ### Follow-ups and existing runs [Section titled “Follow-ups and existing runs”](#follow-ups-and-existing-runs) Warp groups events into a single conversation per issue, pull request, or review thread: * Comments on the same issue continue that issue’s run. * Top-level pull request comments continue that pull request’s run, including a run started from the pull request description. * Replies in a review thread continue that thread’s run. When a run for that thread is already in flight, a new mention is delivered to the running agent as a follow-up instruction rather than starting a second agent. ## Requirements [Section titled “Requirements”](#requirements) * **Team membership** - The GitHub integration requires a [Warp team](/knowledge-and-collaboration/teams/). Configuration is team-scoped, and runs are owned by the team associated with the GitHub App installation. * **Plan and credits** - Your team must have cloud agents enabled and credits available. On Enterprise plans, runs draw from a team credit pool per your contract. See [Access, billing, and identity](/platform/team-access-billing-and-identity/). * **Warp Factories GitHub App** - A GitHub organization owner installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set. The installation’s repository access is what agents act with, so scope it deliberately. * **An enabled GitHub organization** - A Warp team admin adds the organization under **Enabled GitHub Orgs** in the Admin Panel so the installation maps to your Warp team. * **A connected GitHub account** - Each teammate connects their GitHub account to Warp once, so Warp can identify who triggered the run and which team to bill. The connection identifies the requester; it doesn’t determine what the agent can reach on GitHub. ## Setting up the GitHub integration [Section titled “Setting up the GitHub integration”](#setting-up-the-github-integration) Complete steps 1 through 3 once per team. Step 4 is per teammate. ### 1. Install the GitHub App [Section titled “1. Install the GitHub App”](#1-install-the-github-app) Install the app so GitHub can deliver issue and pull request events to Warp, and so agents can read repository context and post comments. A user with admin permissions on the GitHub organization installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App and grants it access to **all repositories** or **selected repositories**. Each installation covers a single GitHub organization or personal account, so install the app separately for every organization your team works in.  Installing the Warp Factories GitHub App. The agent can only act on repositories included in this installation. ### 2. Enable the GitHub organization for your Warp team [Section titled “2. Enable the GitHub organization for your Warp team”](#2-enable-the-github-organization-for-your-warp-team) Enabling the organization is what tells Warp which team owns the runs triggered from those repositories. In the Warp app, a team admin goes to **Settings** > **Admin Panel** > **Platform** and adds the GitHub organization under **Enabled GitHub Orgs**.  Enabled GitHub Orgs setting in the Admin Panel. Until the organization is enabled, mentions in its repositories return a comment asking a Warp workspace admin to configure GitHub repository access in the Admin Panel. ### 3. Configure how GitHub-triggered runs execute [Section titled “3. Configure how GitHub-triggered runs execute”](#3-configure-how-github-triggered-runs-execute) Configure the integration so every GitHub-triggered run uses the environment and settings your team expects. 1. Open the [Integrations page in the Oz web app](https://oz.warp.dev/integrations). The **GitHub integration** row shows whether an installation is connected to your team. 2. Open the row’s settings and choose the [environment](/platform/environments/) the runs use, plus an optional model, [agent](/platform/agents/), prompt, and secrets. 3. Save the configuration. The repository that triggered the event is always cloned for the run, so an environment is optional. Configure one when runs need additional repositories, a specific Docker image, or setup commands. Pick a GitHub environment whose repositories the same installation covers, since the run authenticates with that installation’s token. ### 4. Connect your GitHub account [Section titled “4. Connect your GitHub account”](#4-connect-your-github-account) Each teammate connects their GitHub account so Warp can match the mention to a Warp account, attribute the run to that person, and bill it to the right team. Warp doesn’t start a run for a GitHub account it can’t match. Connect the account from the GitHub integration row in the Oz web app, or the first time you trigger a run: when Warp can’t match your GitHub account, it replies in the thread with a link to connect. ## Using @warp-agent in GitHub [Section titled “Using @warp-agent in GitHub”](#using-warp-agent-in-github) Mention the agent and describe the task in the same comment: > @warp-agent this test is flaky on CI. Find the race condition and open a PR with a fix. On a pull request review comment, the agent also receives the diff for the file you commented on, so you can ask for a targeted change: > @warp-agent rename this helper to `parseRepoRef` and update the call sites. Warp responds in the thread with a status comment that links to the run, then posts progress updates as the agent works, and finally posts the agent’s summary along with any pull requests it opened and branches it pushed. ## Monitoring runs [Section titled “Monitoring runs”](#monitoring-runs) Every GitHub-triggered run is a cloud agent run: * **In the thread** - The status comment links to the run in the Oz web app and, once available, to the live conversation. * **In the Oz web app** - The [Runs page](https://oz.warp.dev/runs) shows the full transcript, status, and metadata. See [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/). * **In the Warp app** - GitHub-triggered runs appear alongside the rest of your team’s runs in the [Agent Management Panel](/platform/managing-cloud-agents/). ## Permissions and identity [Section titled “Permissions and identity”](#permissions-and-identity) GitHub-triggered runs separate **what the agent can do on GitHub** from **who the run belongs to**. **Access comes from the GitHub App installation.** A run started by an `@warp-agent` mention authenticates with a token minted for the Warp Factories GitHub App installation that delivered the event, not with the mentioning user’s GitHub authorization. Cloning, branches, commits, pull requests, and the status comments all use that installation token, so on GitHub the work is attributed to the Warp Factories GitHub App rather than to the person who wrote the mention. The boundary on what the agent can reach is the installation’s repository selection, optionally narrowed further by the repository access a Warp admin grants the team in the Admin Panel. Adjust the installation in your [GitHub settings](https://github.com/settings/installations). **Identity comes from the account connection.** Warp matches the GitHub account that posted the mention to the Warp account that connected it, not by email address. That binding decides who the run is attributed to in Warp, which team owns it, and whose credits pay for it. The person must be a member of the Warp team that enabled the organization. Caution Because the run uses the installation’s access rather than the mentioner’s, anyone who can comment in a repository covered by the installation — and who has a connected GitHub account on that Warp team — can start an agent that acts with all the repository access granted to that team. Grant the app, and the team, only the repositories your team wants agents to work in. For fully automated workflows that run without a triggering user, such as scheduled agents or runs started with an agent API key, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). ## Limitations [Section titled “Limitations”](#limitations) * **Mentions only start runs from comments and pull request descriptions.** Issue and pull request titles, commit messages, and edits to an existing comment don’t trigger the agent. * **Bots can’t trigger the agent.** Mentions posted by GitHub bots or apps are ignored, so an agent can’t start another agent from a comment. * **One run per thread at a time.** While a run for an issue, pull request, or review thread is active, further mentions become follow-ups to that run. * **The installation must map to a Warp team.** Repositories in an organization that no Warp team has enabled can’t start runs. * **Installations are scoped to one organization each.** Install the app separately for every GitHub organization whose repositories your team works in. * **Everything on GitHub is done by the app.** Comments, commits, branches, and pull requests come from Warp Factories rather than the person who mentioned the agent, so the run can’t reach anything the installation can’t reach, and it isn’t narrowed to what that person can reach either. * **The configured environment must be a GitHub environment.** A GitHub-triggered run rejects an environment built for another provider, such as GitLab or Bitbucket, and asks you to configure a GitHub environment instead. * **Environment repositories outside the installation stay out of reach.** The installation token only covers the repositories the app is installed on, so a repository in the environment that the installation doesn’t cover isn’t available to the agent. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Nothing happens after mentioning @warp-agent [Section titled “Nothing happens after mentioning @warp-agent”](#nothing-happens-after-mentioning-warp-agent) The event never reached Warp, or it was filtered out. Check in this order: 1. The comment body contains `@warp-agent`, spelled exactly, rather than only the issue or pull request title. 2. The Warp Factories GitHub App is installed on the organization and has access to that repository. 3. The mention was posted by a person. Bot-authored comments are ignored. 4. The comment is new. Editing an existing comment to add the mention doesn’t start a run. ### ”Your GitHub account is not connected to Warp” [Section titled “”Your GitHub account is not connected to Warp””](#your-github-account-is-not-connected-to-warp) Warp received the mention but couldn’t match your GitHub account to a Warp account. Use the link in the reply to connect your GitHub account, then mention the agent again. ### ”This repository is not enabled for a Warp team” [Section titled “”This repository is not enabled for a Warp team””](#this-repository-is-not-enabled-for-a-warp-team) The app is installed, but no Warp team has access to that repository. A Warp workspace admin configures GitHub repository access in **Settings** > **Admin Panel** > **Platform** in the Warp app. ### ”Your Warp account is not a member of any team with access to this repository” [Section titled “”Your Warp account is not a member of any team with access to this repository””](#your-warp-account-is-not-a-member-of-any-team-with-access-to-this-repository) Your GitHub account is connected, but your Warp account isn’t in a team with access to that repository. Ask a team admin to add you to the Warp team. ### The run starts but fails immediately [Section titled “The run starts but fails immediately”](#the-run-starts-but-fails-immediately) Use the error code in the thread’s status comment to narrow the fix. Common errors include: * [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) - The team’s plan doesn’t support integrations. * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) - GitHub authorization is missing or expired. * [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) - The billed account has no credits available. ### The agent finished but opened no pull request [Section titled “The agent finished but opened no pull request”](#the-agent-finished-but-opened-no-pull-request) Confirm the Warp Factories GitHub App installation covers the repository and still grants write access to it. Because the run acts with the installation’s token, removing a repository from the installation, or narrowing the app’s permissions, stops the agent from pushing branches or opening pull requests there. ## Removing or changing the integration [Section titled “Removing or changing the integration”](#removing-or-changing-the-integration) * **Change repository access** - Edit the Warp Factories installation in your [GitHub settings](https://github.com/settings/installations). * **Stop runs for an organization** - A Warp team admin removes the organization from **Enabled GitHub Orgs** in the Admin Panel. Mentions in its repositories stop starting runs. * **Remove the integration entirely** - Uninstall the Warp Factories GitHub App from the GitHub organization. GitHub stops delivering events to Warp for every repository in that installation. ## Related resources [Section titled “Related resources”](#related-resources) * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from your own CI workflows with `oz-agent-action`. * [Integrations overview](/platform/integrations/) - The full set of first-party integrations. * [Access, billing, and identity](/platform/team-access-billing-and-identity/) - Team GitHub authorization, identity mapping, and credit usage. * [Environments](/platform/environments/) - Configure the runtime context for cloud agents. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Inspect and share the runs a mention starts. # GitHub Actions Canonical page: [/platform/integrations/github-actions/](https://docs.warp.dev/platform/integrations/github-actions/) > Run agents in GitHub Actions to automate code review, issue triage, and CI fixes. Run agents directly in your GitHub Actions workflows using `oz-agent-action`. The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance using your repository context and GitHub permissions. This page covers how the integration works, how to set it up, and common automation patterns for development teams. If you’re comparing GitHub Actions with schedules, Slack, Linear, the GitHub integration, the Oz CLI, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). Watch this demo to see the integration in action: [Warp x GitHub Actions integration video](https://www.loom.com/embed/534f88b6a98e43ca9769ca09de6424b5) In this demo * Automated PR reviews with both summary feedback and inline suggestions * One-click batching and committing of agent suggestions directly from the GitHub UI * Automatically fixing failing CI checks by opening a suggested PR * Suggesting fixes for small review comments (“nits”) without checking out code locally *** ### What the GitHub Actions integration does [Section titled “What the GitHub Actions integration does”](#what-the-github-actions-integration-does) The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: * Runs an agent inside an Actions job * Caches package installation for faster builds * Captures the agent’s output for use in subsequent workflow steps * Lets you pass workflow context, event data, and previous step outputs into the agent prompt * Allows the agent to comment on PRs, post results, or open branches via the GitHub CLI * Supports inline code suggestions that can be batched and committed directly from the GitHub pull request UI * Enables using pre-built skills or custom skills for specialized tasks ### Requirements [Section titled “Requirements”](#requirements) To use agents in GitHub Actions, you need: * A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/reference/cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) * Familiarity with GitHub Actions concepts — see the official docs for [GitHub Actions](https://docs.github.com/en/actions) ### Using Skills [Section titled “Using Skills”](#using-skills) Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agents/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/platform/skills-as-agents/) to run on a schedule or in response to events. #### How to use skills [Section titled “How to use skills”](#how-to-use-skills) You can specify a skill using the `skill` input parameter, either instead of or in combination with prompts: ```yaml - name: Run agent with a skill uses: warpdotdev/oz-agent-action@v1 with: skill: 'code-review' warp_api_key: ${{ secrets.WARP_API_KEY }} ``` #### Skill format options [Section titled “Skill format options”](#skill-format-options) The `skill` parameter supports multiple formats for referencing skills: * **`skill_name`** - Searches for the skill in your repository’s skill directories * **`repo:skill_name`** - Uses a skill from a specific repository * **`org/repo:skill_name`** - Uses a skill from a specific organization’s repository #### Combining skills with prompts [Section titled “Combining skills with prompts”](#combining-skills-with-prompts) You can combine skills with prompts to provide specialized context while customizing the specific task: ```yaml with: skill: 'code-review' prompt: 'Focus on security vulnerabilities in authentication code' warp_api_key: ${{ secrets.WARP_API_KEY }} ``` In this example, the `code-review` skill provides the base context and approach for code review, while the prompt narrows the focus to security concerns in authentication code. *** ## Common use cases [Section titled “Common use cases”](#common-use-cases) The `oz-agent-action` supports several automation patterns commonly used in CI. ### 1. Responding to comments with @ mentions [Section titled “1. Responding to comments with @ mentions”](#1-responding-to-comments-with--mentions) * **File**: [`examples/respond-to-comment.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/respond-to-comment.yml) * **Use case**: Add “@oz-agent fix this typo” or similar comments to a PR or Issue. What it does: * Listens for comments containing a trigger phrase * Sends the comment and thread context into the agent * Agent replies directly to the comment * If code changes are requested, the agent commits fixes to the PR branch **When to use:** * Interactive coding assistance during review or issue triage. ### 2. Automated pull request review [Section titled “2. Automated pull request review”](#2-automated-pull-request-review) * **File**: [`examples/review-pr.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/review-pr.yml) * **Use case**: Provide automated agent feedback when a PR is opened or marked ready for review. What it does: * Automatically runs when PRs open or switch to “ready for review” * Agent inspects changed files, analyzes the diff, and comments inline * Optionally posts a summary comment **When to use:** * Fast initial review before human reviewers step in. ### 3. Automatically fix issues [Section titled “3. Automatically fix issues”](#3-automatically-fix-issues) * **File**: [`examples/auto-fix-issue.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/auto-fix-issue.yml) * **Use case**: Apply the `oz-agent` label on an Issue to trigger automated fixes. What it does: * Detects when the label is added * Agent analyzes the issue description and repo context * Creates a PR with a fix (fix/issue-NUMBER) * Or comments explaining why automation wasn’t possible **When to use:** * Automating bug fixes, small features, or maintenance tasks. ### 4. Daily issue summaries [Section titled “4. Daily issue summaries”](#4-daily-issue-summaries) * **File**: [`examples/daily-issue-summary.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/daily-issue-summary.yml) * **Use case**: Scheduled summaries of newly opened issues. What it does: * Runs daily at 09:00 UTC * Fetches issues created in the past 24 hours * Generates a categorized summary * Sends the summary to Slack via webhook **When to use:** * Daily visibility into new work across your repositories. ### 5. Fixing failing CI checks [Section titled “5. Fixing failing CI checks”](#5-fixing-failing-ci-checks) * **File**: [`examples/fix-failing-checks.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/fix-failing-checks.yml) * **Use case**: Automatically attempt fixes when a workflow or test suite fails. What it does: * Triggers when specified CI workflows fail * Pulls failure logs * Attempts to diagnose and fix the root cause * Opens a PR with the fix and comments with a link **When to use:** * Reducing downtime from failing builds or flaky tests. ### 6. Suggest fixes for review comments [Section titled “6. Suggest fixes for review comments”](#6-suggest-fixes-for-review-comments) * **File**: [`examples/suggest-review-fixes.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/suggest-review-fixes.yml) * **Use case**: Automatically propose code suggestions for small, actionable review comments such as typos, naming tweaks, and minor refactors. **What it does:** * Triggers when a pull request review is submitted * Fetches review comments and stores them in review\_comments.json * Sends comments and context to an agent to decide which ones are simple, actionable fixes * Generates `responses.json` with explanations and suggestion blocks for each fixable comment * Replies inline to the original review comments with the generated suggestions **When to use:** * Quickly addressing straightforward review feedback such as typos, naming tweaks, style nits, and small refactors. *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### `@oz-agent` mention doesn’t trigger the workflow [Section titled “@oz-agent mention doesn’t trigger the workflow”](#oz-agent-mention-doesnt-trigger-the-workflow) If you’re tagging `@oz-agent` in a PR or issue comment and the workflow doesn’t run: 1. **Check org membership (private repos only)**: In private organizations, the `oz-agent` GitHub user must be a [member of your organization](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). Without this, GitHub won’t recognize the mention and the `issue_comment` event won’t match the workflow trigger. Ask an org admin to invite [`oz-agent`](https://github.com/oz-agent) via **Settings > People > Invite member**. 2. **Verify the workflow file**: Ensure your workflow is on the default branch and the trigger condition matches `@oz-agent` (e.g. `contains(github.event.comment.body, '@oz-agent')`). 3. **Check workflow permissions**: The workflow must have the appropriate permissions (e.g. `issues: read`, `pull-requests: write`) to respond. ### `@oz-agent` doesn’t appear in GitHub autocomplete [Section titled “@oz-agent doesn’t appear in GitHub autocomplete”](#oz-agent-doesnt-appear-in-github-autocomplete) GitHub only suggests users who are members of the organization when typing `@` in comments on private repositories. [Invite `oz-agent`](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) to your organization to make it appear in autocomplete. Note: Even if `@oz-agent` doesn’t autocomplete, you can still type the mention manually — but the workflow will only trigger if the user is an org member (for private repos). # GitLab integration Canonical page: [/platform/integrations/gitlab/](https://docs.warp.dev/platform/integrations/gitlab/) > Connect cloud agents to GitLab.com repos natively, or use access tokens and Warp-managed secrets for self-managed instances. Cloud agents work natively with repositories hosted on GitLab.com. Connect your GitLab account when you create an environment in the [Oz web app](https://oz.warp.dev), select the projects agents need, and Warp handles the rest at runtime: repositories are cloned automatically, your GitLab credentials are injected into the run, the `glab` CLI is authenticated, and agents can push branches and open merge requests on your behalf. Merge requests the agent opens are reported as run outputs. For self-managed GitLab instances, native connection isn’t available yet. Instead, grant agents access using a personal access token and Warp-managed secrets, as described in [Self-managed GitLab instances](#self-managed-gitlab-instances). *** ## Connect GitLab.com natively [Section titled “Connect GitLab.com natively”](#connect-gitlabcom-natively) 1. In the [Oz web app](https://oz.warp.dev), create or edit an [environment](/platform/environments/). 2. Choose GitLab as the repository source and authorize with your GitLab account when prompted. Warp requests the `api` and `read_user` scopes, which grant read and write access to your projects. 3. Select the projects the agent should clone, then finish configuring the environment (Docker image, setup commands). At the start of each run, Warp clones the selected repositories and injects your GitLab token, so agents can fetch, push branches, and open merge requests without extra setup. Once configured, the environment works with any Automation Platform trigger—Slack, Linear, schedules, or the CLI. *** ## Self-managed GitLab instances [Section titled “Self-managed GitLab instances”](#self-managed-gitlab-instances) Native connection supports GitLab.com only. For a self-managed GitLab instance, generate a personal access token, store it securely, and configure an environment that clones your repository at runtime. ### Step 1: Generate a personal access token [Section titled “Step 1: Generate a personal access token”](#step-1-generate-a-personal-access-token) 1. Sign in to GitLab. 2. Click your avatar in the top-right corner, then click **Edit profile**. 3. In the left sidebar, click **Access**, then click **Personal access tokens**. 4. Click **Add new token**. 5. Enter a descriptive name for the token (e.g. `warp-agent`), and choose an expiration date that matches your team’s rotation policy. 6. Under **Select scopes**, select **read\_repository**. 7. Click **Generate token**. 8. Copy the token value immediately. GitLab will not show it again. ### Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team GITLAB_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. If you need to update a secret value, run: ```bash oz secret update --value GITLAB_TOKEN ``` ### Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. 1. Run the following command: ```bash oz environment create \ --name "my-gitlab-env" \ --docker-image \ --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.example.com/your-group/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$GITLAB_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `gitlab.example.com/your-group/your-repo.git` with your server’s hostname and repository path * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. ### Step 4: Test your environment [Section titled “Step 4: Test your environment”](#step-4-test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. 1. Run the following command, replacing `` with the environment ID from Step 3: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger: * **Slack** — Tag **@warp** in a message to start an agent run against your GitLab repo. See [Slack](/platform/integrations/slack/). * **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). # Jira integration Canonical page: [/platform/integrations/jira/](https://docs.warp.dev/platform/integrations/jira/) > Trigger cloud agent runs directly from Jira issues using the warp-agent label. The Jira integration lets your team kick off cloud agent runs directly from Jira Cloud issues. When you add the `warp-agent` label to an issue, an agent starts in the cloud and gets to work — then posts status updates and a summary as Jira comments when it’s done. *** ### Requirements [Section titled “Requirements”](#requirements) * **Jira Cloud** - Jira Server and Data Center are not supported. * **Team membership** - The Jira integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. * **Jira site admin** - Installing the Warp app on your Jira site requires site admin permissions. *** ### Setup [Section titled “Setup”](#setup) #### 1. Open the Jira app installation page [Section titled “1. Open the Jira app installation page”](#1-open-the-jira-app-installation-page) In the [Oz web app](https://oz.warp.dev/integrations), find Jira and click **Set up**. On the Atlassian installation page, click **Get app**. #### 2. Install the app on your Jira site [Section titled “2. Install the app on your Jira site”](#2-install-the-app-on-your-jira-site) Choose the Jira Cloud site you want to connect, review the requested permissions, and install the Warp app. Only Jira site admins can install apps. #### 3. Open the app configuration page [Section titled “3. Open the app configuration page”](#3-open-the-app-configuration-page) In your Jira site, open **Manage apps**. Find **Warp**, open its three-dot actions menu, then click **Configure**. The configuration page URL for the production app follows this pattern: ```text https://.atlassian.net/jira/settings/apps/configure/40dbc167-16d9-4b68-9752-277c5a52aa01/34808a52-a321-44c2-bac4-a15eb316df50/static/warp-jira-configure/34808a52-a321-44c2-bac4-a15eb316df50 ``` Replace `` with your Jira Cloud site subdomain. #### 4. Connect Jira to your Warp workspace [Section titled “4. Connect Jira to your Warp workspace”](#4-connect-jira-to-your-warp-workspace) On the app configuration page in Jira, click **Connect to Warp**. Sign in to Warp if prompted. Warp automatically binds the Jira installation to your Warp workspace. The confirmation page displays **Jira connected** when the connection succeeds. Jira-triggered runs are now available to members of the connected Warp workspace. Installing the app doesn’t require any action from individual teammates up front — each member connects their own Jira account to Warp the first time they trigger a run (see [Connecting your Jira account to Warp](#connecting-your-jira-account-to-warp)). #### 5. (Optional) Configure the default environment, model, and harness [Section titled “5. (Optional) Configure the default environment, model, and harness”](#5-optional-configure-the-default-environment-model-and-harness) Return to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations), then click **Edit Jira** to set the default [environment](/platform/environments/), model, harness, and agent for Jira-triggered runs. If you don’t change these settings, Jira-triggered runs use your workspace’s default configuration. *** ### How to start a run [Section titled “How to start a run”](#how-to-start-a-run) Add the label **`warp-agent`** to any Jira issue. Warp will pick it up, post a comment to let you know it’s started, and begin working through the task using the issue title, description, and recent comments as context. When the run finishes, Warp posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. To track runs across your team, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where Jira-triggered runs appear in the **All** tab. #### Connecting your Jira account to Warp [Section titled “Connecting your Jira account to Warp”](#connecting-your-jira-account-to-warp) This step is for any user who triggers runs — it doesn’t require Jira admin permissions. The first time you trigger a run, Warp posts a comment prompting you to connect your Jira account to Warp. Connecting attributes your Jira-triggered runs to your Warp account; the run doesn’t start until your account is connected. After connecting, re-add the `warp-agent` label to start the run. 1. Follow the link in the comment to open the Warp page in your Jira personal settings. The link for the production app follows this pattern: ```text https://.atlassian.net/jira/settings/personal/apps/40dbc167-16d9-4b68-9752-277c5a52aa01/34808a52-a321-44c2-bac4-a15eb316df50 ``` 2. Click **Connect to Warp**. A Warp page opens and links your account automatically. Sign in to Warp first if prompted. The page displays **Jira account connected** when the link succeeds, and the settings page shows a **Connected to Warp** badge. Runs you trigger from then on are attributed to you. *** ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If Warp doesn’t respond after adding the label, check that: * The Warp app is installed on your Jira site and the workspace is connected (see the app’s **Configure** screen in Jira). * The issue is in Jira Cloud (not Server or Data Center). For other issues, reach out to your Warp contact or join the [Warp community on Slack](https://go.warp.dev/join-preview). *** ### Related pages [Section titled “Related pages”](#related-pages) * [Integrations overview](/platform/integrations/) - How environments and integrations work together. * [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/) - Other chat- and issue-triggered integrations. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor Jira-triggered runs across your team. * [Environments](/platform/environments/) - Configure where agents run. # Linear integration Canonical page: [/platform/integrations/linear/](https://docs.warp.dev/platform/integrations/linear/) > Automate Linear issues with agents that run code in the cloud and create pull requests on your behalf. The Linear integration lets your team delegate development work directly to agents from inside Linear. When you tag @warp on an issue or comment, an agent will spin up in the cloud, clone the repos defined in your environment, and begin working through the task. Agents keep you updated inside Linear, generate pull requests using your GitHub account, and provide a link to join a live remote session so you can watch or steer the workflow in real time.  This guide explains what the integration does, how it works end-to-end, and how to configure it for your Warp team. *** ### Triggering agents inside Linear [Section titled “Triggering agents inside Linear”](#triggering-agents-inside-linear) Tagging @warp on an issue or in a Linear comment starts an agent run. Warp clones the repositories defined in your environment, sets up your development environment using your Docker image and setup commands, and begins working through the task with full context from your codebase and the Linear issue. Agents post updates as they progress, including a task list, elapsed time, and checkpoints, so you can follow along without leaving Linear. Agents also share a link to an interactive remote session using Warp’s [cloud agent session sharing](/platform/viewing-cloud-agent-runs/). Opening this link lets you view the live terminal output for the running agent in Warp or in the browser. From there, you can interrupt or guide the agent with additional instructions when needed. Once the agent finishes, it will create a pull request on your behalf — using your GitHub permissions — and post a summary of its work and the PR link back into Linear. You can start an agent in two ways: * **Tag @warp in a comment** and describe what you want done. * **Assign the issue to @warp** as if it were a teammate. The agent will acknowledge the request directly in the Linear issue and begin working. Agents keep you informed through: * **Activity updates** inside Linear * A **running task list** and timeline showing what the agent is working on * A **shared session link** that opens a live view of the agent’s cloud environment Session sharing works in Warp or in a browser view and allows multiple teammates to watch the session. To monitor Linear-triggered runs alongside the rest of your team’s agents, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where integration-triggered runs appear in the **All** tab.  #### Joining the remote session [Section titled “Joining the remote session”](#joining-the-remote-session) Selecting [**Open in Warp**](/platform/viewing-cloud-agent-runs/) (or the web option) opens the active session. You’ll see: * The agent’s full execution log * The plan pane with the task list * An input box to add clarifying instructions * A real-time view identical to a local Warp task Any instructions you give will interrupt the agent, feed the new context, and resume work. When the task is complete: * Warp commits the changes using your GitHub identity * A pull request is created through the GitHub CLI * The PR includes a clean title and description based on the Linear issue and the agent’s work * A summary and link to the PR appear in the Linear issue Because PRs are created as *you*, this makes code review, auditing, and team collaboration straightforward. *** ### Requirements [Section titled “Requirements”](#requirements) * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. * **Identity** - The first time you trigger an agent, Warp prompts you to connect your Linear identity to your Warp account. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access to the repo if you want Warp to create PRs on your behalf. *** ### How to configure the integration [Section titled “How to configure the integration”](#how-to-configure-the-integration) Setup involves two steps powered by the [Oz CLI](/reference/cli/). For more instructions, see [Integrations Overview](/platform/integrations/). #### 1. Create an environment [Section titled “1. Create an environment”](#1-create-an-environment) An environment defines everything the agent needs to run your code: * A **Docker image** (public on Docker Hub) * A set of **GitHub repos** the agent should clone * Optional **setup commands** that run before the agent starts You can create an environment via: * The CLI * The guided flow using `/create-environment` ([Slash Commands](/agents/capabilities/slash-commands/)) For full instructions, see our [Environment Setup](/platform/integrations/) docs. #### 2. Create the Linear integration [Section titled “2. Create the Linear integration”](#2-create-the-linear-integration) Once your environment exists, create the integration. Alternatively, you can use the CLI: ```plaintext oz integration create linear --environment ``` The CLI will open a browser window prompting you to install the Warp app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. *** ### Uninstallation instructions [Section titled “Uninstallation instructions”](#uninstallation-instructions) To remove the Warp app from Linear: 1. Only a Linear team admin can manage app permissions. 2. In Linear, go to **Settings**. 3. Navigate to Agents under the Features section. 4. Select **Warp** from the list of installed agents. 5. Click **Revoke access** to remove the integration for your workspace. [Uninstalling the Warp Linear integration video](https://www.loom.com/embed/2f1648586d8148dc80561c00a09ca334) After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If something isn’t working as expected—missing repos, PR failures, Linear not detecting @Oz, or environment issues—see [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/) for guidance on GitHub permissions, repo access, Docker images, and setup failures. # Integrations quickstart Canonical page: [/platform/integrations/quickstart/](https://docs.warp.dev/platform/integrations/quickstart/) > Trigger your first agent from Slack in ~15 minutes and get results in-thread. Automation Platform integrations let you trigger cloud agents directly from the tools your team already uses. This guide walks you through connecting Warp to Slack. Once set up, anyone on your team can tag @warp in a message or thread to kick off a cloud agent that runs the task and posts results back to the conversation. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Eligible team** - The Slack integration requires a Warp team with cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/). * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have one yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) or run `/create-environment` in Warp. * **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You’ll be prompted to authorize the Warp GitHub app when you first create the integration. *** ## 1. Connect the Slack integration [Section titled “1. Connect the Slack integration”](#1-connect-the-slack-integration) The simplest way to set up the integration is **using the Oz web app**: 1. Navigate to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations). 2. Click **Slack**. 3. Follow the guided flow to select your environment and authorize the Warp app in your Slack workspace. All members of your Warp team can now use the integration. **Using the Oz CLI instead:** Run `oz integration create` to connect the Slack integration: ```bash oz integration create slack --environment ``` Replace `` with your environment ID (see [Environments](/platform/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Warp app in your workspace. To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: ```bash oz integration create slack \ --environment \ --prompt "Always open a draft PR and request review from the team-leads group." ``` ## 2. Tag the agent in Slack [Section titled “2. Tag the agent in Slack”](#2-tag-the-agent-in-slack) In any channel or thread in your Slack workspace, tag @warp with a task: > @warp scan the authentication module for security issues and summarize what you find Warp acknowledges the request immediately and starts an agent run in the cloud. You’ll see progress updates appear in the thread as the agent works. You can also tag @warp inside an existing thread. Warp picks up the full thread history as context automatically, so you can tag it mid-discussion without repeating background. ## 3. Watch the run [Section titled “3. Watch the run”](#3-watch-the-run) While the agent works, progress updates appear directly in the Slack thread. To inspect the run in more detail: * **Click the session link** - Warp posts a link in the thread to open a live terminal view of the agent. Watch in real time, add follow-up instructions, or let it run to completion. * **Go to the [Runs page in the Oz web app](https://oz.warp.dev/runs)** - See the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. When the task is complete, Warp posts a summary back to the original Slack thread. **Breaking it down:** Warp reads the Slack thread as context, runs the agent inside the environment you configured — with your repos cloned and Docker image running — and returns results where the conversation started, in Slack, without anyone leaving the thread. *** ## Next steps [Section titled “Next steps”](#next-steps) * **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give agents consistent, reusable instructions across every run. * **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of agents. * **Read the full Slack reference** - [Slack](/platform/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. # GitHub Actions quickstart Canonical page: [/platform/integrations/quickstart-github-actions/](https://docs.warp.dev/platform/integrations/quickstart-github-actions/) > Set up your first agent in GitHub Actions in ~10 minutes. Run agents as workflow steps to automate code review and issue triage. Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://github.com/warpdotdev/oz-agent-action). This quickstart walks you through setting up your first GitHub Actions integration: a PR review workflow that automatically analyzes pull requests and posts inline review comments. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/platform/agents/) on your team) with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. *** ## 1. Add your API key as a GitHub Actions secret [Section titled “1. Add your API key as a GitHub Actions secret”](#1-add-your-api-key-as-a-github-actions-secret) Store your Warp API key as a GitHub Actions secret so workflows can authenticate without exposing the key in your code. 1. In your repository on GitHub, go to **Settings** > **Secrets and variables** > **Actions**. 2. Click **New repository secret**. 3. Set the name to `WARP_API_KEY`. 4. Paste your API key into the **Secret** field. 5. Click **Add secret**. ## 2. Create the workflow file [Section titled “2. Create the workflow file”](#2-create-the-workflow-file) This workflow triggers an agent whenever a PR is opened or marked ready for review. The agent reviews the diff and posts inline comments. Create `.github/workflows/oz-pr-review.yml` in your repository with the following content: ```yaml name: Warp PR review on: pull_request: types: [opened, ready_for_review] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Review PR with Warp uses: warpdotdev/oz-agent-action@v1 with: prompt: | Review the code changes on this pull request: 1. Use `git diff origin/${{ github.base_ref }}...HEAD` to identify changes. 2. Analyze the diff for style, security, or correctness issues. 3. Use `gh pr review --comment` to post inline suggestions. warp_api_key: ${{ secrets.WARP_API_KEY }} ``` This workflow listens for pull request events and runs the `oz-agent-action` step, which executes the prompt to review code changes. Commit and push this file to your default branch to activate the workflow. ## 3. Open a pull request [Section titled “3. Open a pull request”](#3-open-a-pull-request) Create a new pull request in your repository to trigger the workflow. To verify the workflow ran: 1. Go to the **Actions** tab in your repository. 2. Click **Warp PR review** in the list of workflows. 3. Select the most recent run to see the agent’s output in the job logs. ## 4. View the run [Section titled “4. View the run”](#4-view-the-run) Each `oz-agent-action` step creates a run you can inspect from the cloud agent dashboard: * **Oz web app** - Go to the [Runs page in the Oz web app](https://oz.warp.dev/runs) to see the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. * **Warp app** - Open the conversations panel to see the run alongside your other agent activity. When the run completes, the agent posts feedback as inline review comments on the PR. **Breaking it down:** The agent runs in Warp’s cloud infrastructure — not on GitHub’s runners — using the workflow’s GitHub token for repository access. Each run is isolated, tracked, and auditable, just like any manually triggered cloud agent run. *** ## Next steps [Section titled “Next steps”](#next-steps) * **Explore more workflow patterns** - The [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) includes ready-to-use consumer workflow templates for responding to `@oz-agent` comments, auto-fixing labeled issues, daily issue summaries, fixing failing CI checks, and suggesting review fixes. Copy any template from `consumer-workflows/` into `.github/workflows/` in your repo. * **Use skills for reusable behavior** - Replace the inline `prompt` with a `skill` parameter to apply consistent, version-controlled instructions across all your CI workflows. See [Skills](/agents/capabilities/skills/). * **Read the full reference** - [GitHub Actions](/platform/integrations/github-actions/) covers all action inputs, output handling, session sharing for debugging, and troubleshooting. # Slack integration Canonical page: [/platform/integrations/slack/](https://docs.warp.dev/platform/integrations/slack/) > Trigger agents from Slack to run cloud tasks, track progress, and create pull requests. The Slack integration lets your team trigger cloud agents directly from Slack conversations. Tag @Warp in a message or DM the bot to start a cloud agent that clones your repos, works through the task, posts progress updates, and opens pull requests back into the same thread. ### Get started [Section titled “Get started”](#get-started) #### Installation [Section titled “Installation”](#installation) 1. Log in to the [Oz web app](https://oz.warp.dev) and go to the [Integrations page](https://oz.warp.dev/integrations). 2. Click **Connect** next to **Slack**. You’ll be prompted to install the Warp app into your Slack workspace. 3. After installing, you’re returned to the Integrations page to finish setup: choose the [environment](/platform/environments/) agents should use, which defines the repos, Docker image, and setup commands. 4. Start using Warp in Slack by mentioning **@Warp** with a task. Alternatively, install via the [Oz CLI](/reference/cli/): ```plaintext oz integration create slack --environment ``` The CLI opens a browser window to install the Warp app into your Slack workspace. After installation, the integration is available to all members of your Warp team. #### Requirements [Section titled “Requirements”](#requirements) * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. *** ### Using Warp inside Slack [Section titled “Using Warp inside Slack”](#using-warp-inside-slack) Tagging @Warp in a message or thread starts an agent run. The agent clones the repositories in your environment, sets up your development environment using your Docker image and setup commands, and begins working with the context from the Slack conversation. The bot posts updates back into the thread as it progresses so you can follow along without opening your terminal. Agents also share a link to an interactive remote session using Warp’s [cloud agent session sharing](/platform/viewing-cloud-agent-runs/). Opening this link gives you a live terminal view of the cloud agent running your code. You can interrupt or steer the agent by providing additional instructions, and the agent will pick up where it left off with the new context. When the work is complete, Warp will create a pull request on your behalf using your GitHub permissions and send a summary and PR link back to the original Slack thread. ### Triggering an agent [Section titled “Triggering an agent”](#triggering-an-agent) You can start an agent in three ways: * **Tag @Warp in a channel message** Describe the task, and Warp will begin working with full context from the thread. * **Tag @Warp inside a thread** Warp will automatically collect the thread’s prior messages and use them as context. * **DM the Warp bot directly** Useful for private tasks or experimentation. The bot will acknowledge the request in Slack and start running the task immediately. ### Monitoring agent progress [Section titled “Monitoring agent progress”](#monitoring-agent-progress) Agents keep you informed directly in Slack via: * Activity updates showing progress throughout the run * Checkpoints indicating major steps completed * A direct link to the cloud agent run in the [Oz web app](/platform/oz-web-app/), where you can view the full run transcript and metadata * A session-sharing link that opens a live terminal view of the remote agent [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) works in Warp or in your browser and supports multiple teammates joining the same live session. To monitor Slack-triggered runs alongside the rest of your team’s agents, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where integration-triggered runs appear in the **All** tab. ### Joining the live remote session [Section titled “Joining the live remote session”](#joining-the-live-remote-session) Selecting **View conversation** opens the active agent session. Inside the session you’ll see: * The agent’s full execution log * The plan/task list * Real-time output just like a local Warp task * An input box for follow-up instructions Any instruction you type will interrupt the agent, incorporate the new guidance, and then resume execution. This is the best way to debug or steer multi-step tasks. ### Pull requests and output [Section titled “Pull requests and output”](#pull-requests-and-output) Once the agent finishes, it will: * Commit changes using your GitHub account * Create a pull request via the GitHub CLI * Generate a clean title and description referencing your Slack request * Post the summary and PR link directly into the Slack thread Because PRs are created as you, the workflow slots seamlessly into your team’s existing review process. *** ### Configuration [Section titled “Configuration”](#configuration) #### 1. Create an environment [Section titled “1. Create an environment”](#1-create-an-environment) An environment defines everything the agent needs to run your code in the cloud: * A Docker image (public on Docker Hub) * The GitHub repos the agent should clone * Optional setup commands that run before the agent starts Create an environment via: * **Oz CLI** ```bash oz environment create \ --name \ --docker-image \ --repo \ --setup-command "" ``` * **Guided setup using `/create-environment`** ( [Slash Commands](/agents/capabilities/slash-commands/)) This flow analyzes your repos, recommends a Docker image, suggests setup commands, and can build + push a custom image if needed. See the [Environments](/platform/environments/) docs for detailed instructions. #### 2. Optional: custom prompt [Section titled “2. Optional: custom prompt”](#2-optional-custom-prompt) You can attach a custom prompt that is applied to every agent run: ```plaintext oz integration create slack \ --environment \ --prompt "Always prefix PR titles with '[WARP]' and include detailed test steps." ``` ### Identity mapping and team access [Section titled “Identity mapping and team access”](#identity-mapping-and-team-access) * Integrations are scoped to your Warp team. * Any teammate in the same Slack workspace and Warp team can use the integration. * The first time you mention the bot or DM it, Warp sends you a link to connect your Slack identity to your Warp account. * Teammates must individually authorize GitHub on their first run. *** ### Privacy [Section titled “Privacy”](#privacy) The Warp app reads Slack messages only where it is mentioned or directly messaged: the triggering message, its thread history (used as task context), and your Slack profile information. Message content is used to run the agent task and is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy), which describes how Warp collects, manages, and stores third-party data. ### Uninstallation instructions [Section titled “Uninstallation instructions”](#uninstallation-instructions) To remove the Warp app from your Slack workspace: 1. Open Slack and go to **Apps** in the left sidebar. 2. Search for Warp. 3. Select the app, then open the **About** tab. 4. Click **Configuration**. This will open your workspace’s app configuration page in the browser. 5. Scroll to the bottom and select **Remove App**. 6. Confirm the removal.  The Warp Slackbot in Slack.  Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If something isn’t working—missing repos, Slack not detecting @Warp, PR failures, or environment configuration issues—see [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/). It covers: * GitHub authorization and repo access * Docker image incompatibility * Missing credentials and secrets * Setup commands that fail on a fresh container For identity mismatches and installation problems, see [identity mapping and team access](/platform/integrations/slack/#identity-mapping-and-team-access) above. # Managing cloud agents Canonical page: [/platform/managing-cloud-agents/](https://docs.warp.dev/platform/managing-cloud-agents/) > Monitor and manage agent activity across your team with Warp's Agent Management Panel and the Oz web app's Runs page. Warp provides two management surfaces for tracking and observing agent activity across your account and, where applicable, your team: the **Agent Management Panel** in the Warp app and the [**Runs** page in the Oz web app](/platform/oz-web-app/#runs), which also works on mobile devices. Use these surfaces as the starting point for real-time agent observability in Warp. They help you see which agents are active, which runs are blocked or failed, where each run started, and which session link opens the prompt, plan, commands, logs, outputs, and follow-up messages behind the work. The Agent Management Panel and Oz web app Runs page are designed to answer, at a glance: * Which agents are active or have been running recently. * Which runs are working, blocked, failed, succeeded, or canceled. * Where an agent run was triggered from, such as a local agent conversation, the Oz CLI, Slack, Linear, a schedule, or the API. * How parent and child runs relate in orchestrated workflows. * Which session to open when you need prompt, plan, command, log, output, or follow-up context. * How many credits those runs consumed. Warp’s agent observability is run- and session-oriented. It is not a replacement for full APM, OpenTelemetry, or Datadog-style tracing across arbitrary agent frameworks. Use Warp to track agent run status, trigger/source, owner, parent-child relationships, transcripts, commands, logs, outputs, and replayable session links. [Managing cloud agent runs video](https://www.loom.com/embed/679c267ddd2d44519abf79edcb1122c7) These management surfaces include your **local (interactive) agents** and [cloud agent](/platform/) runs.  Warp’s Agent Management Panel showing interactive and cloud agent runs. ### What appears in the agent management surfaces [Section titled “What appears in the agent management surfaces”](#what-appears-in-the-agent-management-surfaces) The Agent Management Panel and Oz web app Runs page include two categories of agent activity. #### Interactive agents [Section titled “Interactive agents”](#interactive-agents) * Initiated from the Warp app. * The conversation is owned by you. It opens locally in Warp, and can be shared via a link when needed. * Credit usage reflects inference. #### Cloud agent runs [Section titled “Cloud agent runs”](#cloud-agent-runs) * Background executions initiated by triggers such as integrations and automations (for example: Slack, Linear, schedules, GitHub Actions, or API/CLI invocations). * Each run produces a shared session that can be inspected after completion (including logs, messages, and outputs). * Credit usage reflects inference + compute, shown as a single combined value in this view. Caution All usage rolls up into Warp’s standard [**credit**](/support-and-community/plans-and-billing/credits/) system. In the **Personal** tab, you can view all of the interactive and cloud agent conversations that you own. In the **All** tab, you can see everything from the personal tab, as well as any cloud agent sessions that are shared with you by your teammates; right now, this only includes things triggered from integrations. *** ### Inspect or review an agent run [Section titled “Inspect or review an agent run”](#inspect-or-review-an-agent-run) Use the Agent Management Panel or Oz web app Runs page as the starting point when a teammate asks, “What did the agent do?” 1. In the agents list, use the filter menu to filter by source, day, creator, or status. 2. Select the matching row to open the shared session or local conversation. 3. Inspect the prompt, plan, commands, logs, outputs, and follow-up messages where available. 4. Share the session link with teammates if they need to review the same context. 5. For PR-producing workflows, include the session link alongside the PR link so reviewers can inspect both the code diff and the agent’s execution context. For cloud agent runs, the session opens in [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/). For local interactive agents, the conversation opens in Warp and can be shared with [Agent Session Sharing](/agents/local-agents/session-sharing/). *** ### The agents list [Section titled “The agents list”](#the-agents-list) Each row represents a single item in the agents list (either an interactive conversation or a cloud agent run). The list is scannable: you can understand “what happened” without opening anything. #### Fields you’ll see [Section titled “Fields you’ll see”](#fields-youll-see) **Source** Where the agent was launched from. Common sources include: * **Interactive:** an [agent conversation](/agents/) started in the Warp app * **CLI**: a local run triggered by the [Oz CLI](/reference/cli/) * **API**: a run triggered by [Warp’s API](/reference/api-and-sdk/) * **Slack / Linear**: runs triggered by [integrations](/platform/integrations/) * **Scheduled**: runs triggered on a [cron schedule](/platform/triggers/scheduled-agents/) **Status** Warp uses a small set of statuses to help you quickly identify what needs attention: | Status | Icon | Description | | -------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------- | | `Working` | N/A | in progress (may include queued / running states) | | `Blocked` | 🟨 | *(interactive only)*the conversation is waiting on user input or a required step | | `Canceled` | ⬜️ | (interactive only) the interactive conversation was canceled before completion | | [`Failed / Errored`](/reference/api-and-sdk/troubleshooting/errors/) | 🔺 | something went wrong (applies to both interactive and cloud agent runs) | | `Success` | ✅ | completed successfully (applies to both interactive and cloud agent runs) | **Duration (for cloud agent tasks)** * Shown for cloud agent runs to indicate how long the task executed. * Note: Interactive conversations generally don’t map cleanly to a single “run duration,” so this is currently omitted. *** ### Inspecting an agent [Section titled “Inspecting an agent”](#inspecting-an-agent) **The primary interaction is simple:** * Clicking a cloud agent row opens the [shared session](/platform/viewing-cloud-agent-runs/) for that run (prompt, plan, commands, logs, messages, and output where available). * Clicking an interactive row opens the conversation locally in the Warp app. This makes the agents list a navigation surface: find the thing you care about, click once, and you’re in the right context to inspect or continue work. ### Filtering [Section titled “Filtering”](#filtering) In both *Personal* and *All* views, you can open the filter menu and filter by: * Source (interactive, API, CLI, Slack/Linear, scheduled) * Day of creation * Creator * Status This is the fastest way to isolate “everything that failed today,” “runs from Slack,” or “what a specific teammate triggered via integrations.” *** ### Orchestrated runs (parent and child) [Section titled “Orchestrated runs (parent and child)”](#orchestrated-runs-parent-and-child) When a parent agent spawns one or more child agents through [multi-agent orchestration](/platform/orchestration/), the parent and each child are tracked as separate runs. Where you see them depends on the surface: * **Local children in the Warp app** - while you’re viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with a live status badge. Click a child pill to switch the pane to that child’s conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you’re viewing a child - to return. Local children don’t appear as separate rows in the Agent Management Panel list. * **Cloud children in the Warp app** - appear in the Agent Management Panel list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them. * **Cloud children in the [Oz web app](/platform/oz-web-app/)** - grouped under the parent’s row on the Runs page, and surfaced together inside the parent’s detail pane on a **Sub-agents** tab. The parent’s own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the Oz web app). ## Related pages [Section titled “Related pages”](#related-pages) * [Cloud agents overview](/platform/) — What cloud agents are and when to use them. * [Multi-agent orchestration](/platform/orchestration/) — Parent/child model, run state transitions, and common orchestration patterns. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) — Open and inspect a remote cloud agent run. * [Handoff between local and cloud agents](/platform/handoff/) — Move agent work between local and cloud, or continue a finished cloud run. * [Oz web app](/platform/oz-web-app/) — Manage runs and schedules from any browser. # MCP Servers for cloud agents Canonical page: [/platform/mcp/](https://docs.warp.dev/platform/mcp/) > Connect cloud agents to external tools, APIs, and internal services using MCP servers. Cloud agents can call external tools through [Model Context Protocol (MCP) servers](/agents/capabilities/mcp/). This lets agents reach beyond the terminal to automatically interact with systems like GitHub, dbt, Sentry, or any custom internal service, whenever the workflow requires it. ## When to use MCP servers [Section titled “When to use MCP servers”](#when-to-use-mcp-servers) Add MCP servers to a cloud agent when it needs to: * Read from or write to an external API (issue trackers, monitoring tools, cloud services) * Call local processes that expose MCP endpoints * Use internal developer tools that you’ve wrapped in an MCP interface The agent calls MCP tools automatically based on what the task requires, without the need for explicit instruction. ## How MCP configuration works [Section titled “How MCP configuration works”](#how-mcp-configuration-works) You can supply MCP configuration in two ways: * **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/reference/cli/mcp-servers/) in the CLI reference for the full syntax. * **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. ## Configuration schema [Section titled “Configuration schema”](#configuration-schema) Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type: | Transport | Field(s) | When to use | | -------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Warp-shared server, managed MCP install, or integration server | `warp_id` | Reference an MCP server already configured in Warp — including an OAuth-authorized [managed MCP installation](#oauth-authentication) — by its UUID, or a Warp-managed integration server by its id | | Stdio (local process) | `command`, `args` | Launch a local executable as an MCP server | | Streamable HTTP / SSE | `url` | Connect to a remote or locally hosted MCP endpoint | ### Supported fields [Section titled “Supported fields”](#supported-fields) * **`warp_id`** — UUID of a Warp-shared MCP server or a [managed MCP installation](#oauth-authentication) (find UUIDs with `oz mcp list`, from **Settings** > **Agents** > **MCP servers**, or from the [Oz web app](/platform/oz-web-app/#integrations) **Integrations** page), or the id of a Warp-managed integration server: `linear`, `slack`, or `jira` * **`command`** — Executable to launch (stdio transport) * **`args`** — Arguments passed to `command` (only valid with `command`) * **`env`** — Environment variables passed to the process (only valid with `command`) * **`url`** — HTTP or HTTPS endpoint URL (streamable HTTP or SSE transport) * **`headers`** — HTTP headers sent with requests (only valid with `url`) You can define any number of MCP servers in a single config. ### Example configuration [Section titled “Example configuration”](#example-configuration) ```json { "github": { "url": "https://mcp.example.com/github" }, "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "https://example.us1.dbt.com", "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" } } } ``` ## Using MCP servers in an agent config file [Section titled “Using MCP servers in an agent config file”](#using-mcp-servers-in-an-agent-config-file) For repeatable cloud agent workflows, declare your MCP servers inside the agent config file passed to `-f / --file`: ```json { "name": "my-production-agent", "model_id": "claude-sonnet-4", "system_prompt": "You are a helpful assistant focused on backend development.", "environment_id": "SVhg783GBFQHk1OfdPfFU9", "mcp_servers": { "github": { "url": "https://mcp.example.com/github" }, "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "https://example.us1.dbt.com", "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" } } } } ``` Pass this file when running a cloud agent: ```sh oz agent run-cloud --environment -f my-agent-config.json --prompt "Check for regressions in the last deploy" ``` ## Requirements and defaults [Section titled “Requirements and defaults”](#requirements-and-defaults) * MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file. * If `mcp_servers` is omitted, the agent runs with no MCP servers enabled. * Each server name must be unique and non-empty. * The `warp_id` transport is validated against your Warp account. Referenced servers must be accessible to you. * A `warp_id` that names a Warp-managed integration server (`linear`, `slack`, or `jira`) resolves against your team’s [integration](/platform/integrations/) connection, but only for a run executing inside a [factory](/factories/) (`jira` also resolves for a run triggered directly by a Jira event). Outside those cases, or when the integration isn’t connected, the server is skipped and the run continues without it. ## OAuth authentication [Section titled “OAuth authentication”](#oauth-authentication) Cloud agents support OAuth-protected MCP servers through a **managed MCP installation** — a cloud run can’t complete an interactive browser login, so authorization happens ahead of time instead. To use an OAuth-gated server with a cloud agent: 1. In the [Oz web app](/platform/oz-web-app/#integrations), open **Integrations** and add the server as a managed MCP server. 2. Authorize it once. Warp completes the OAuth flow in a browser and stores the credentials. 3. Reference the installation’s UUID as `warp_id` in your `--mcp` flag or agent config, the same way you’d reference any Warp-shared server. Cloud agent runs then use the stored credentials automatically, with no browser interaction. This is the supported path for hosted OAuth servers such as Figma’s remote MCP server. ## Limitations [Section titled “Limitations”](#limitations) Caution A direct `url` MCP server that requires OAuth and has no `Authorization` header can’t be used by cloud agents. Set it up as a [managed MCP installation](#oauth-authentication) instead, then reference it by `warp_id`. Token- or header-based authentication on a `url` server, `env`-based secrets on a `command` server, and `warp_id` references to a Warp-shared or managed server all work without additional setup. ## Learn more [Section titled “Learn more”](#learn-more) * [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths * [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Environments](/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks * [Secrets](/platform/secrets/) — store and inject credentials into agent runs safely # Multi-agent orchestration Canonical page: [/platform/orchestration/](https://docs.warp.dev/platform/orchestration/) > Coordinate parent and child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows in Warp. Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent’s output. The parent/child model works from the Warp app, the [Oz CLI](/reference/cli/), and the [Oz API & SDK](/reference/api-and-sdk/), and supports local, cloud, and mixed execution. Watch this walkthrough to see how a cloud agent can coordinate a team of agents in the cloud.  To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). To orchestrate work inside a [Warp factory](/factories/), dispatch through the [factory API](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman’s `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. ## The parent/child model [Section titled “The parent/child model”](#the-parentchild-model) An orchestrated workflow always has one **parent agent** and one or more **child agents**. * **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child. * **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children. Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [Oz web app](/platform/oz-web-app/), and the [Oz API & SDK](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. ### Where parent and child agents can run [Section titled “Where parent and child agents can run”](#where-parent-and-child-agents-can-run) The parent and child don’t have to run in the same place. Orchestration supports four combinations: * **Local → local** - a [Warp Agent](/agents/) conversation in the Warp app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure. * **Local → cloud** - a local parent spawns one or more cloud children that run in [environments](/platform/environments/) on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel. * **Cloud → cloud** - a cloud parent spawns cloud children that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API. * **Cloud → cloud-local** - a cloud parent spawns children that run inside the parent’s own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful. Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agents/cli-agents/claude-code/) or [Codex](/agents/cli-agents/codex/), and vice versa. ### How a child agent is configured [Section titled “How a child agent is configured”](#how-a-child-agent-is-configured) An ad hoc child’s prompt comes from the parent at spawn time. The model, harness, and execution settings apply to every child in the batch. Use a [skill](/agents/capabilities/skills/) for reusable instructions. A local child discovers the project and home-directory skills in scope from its working directory. For cloud children, the parent attaches skills from a repository in the [environment](/platform/environments/). For named agents with standing configuration, use [Warp Factories](/factories/). A factory’s foreman can dispatch its [factory agents](/factories/factory-agents/#choose-a-configured-factory-agent). ## Run state transitions [Section titled “Run state transitions”](#run-state-transitions) Each run progresses through a small set of states. The parent observes these transitions to decide what to do next - keep waiting, send a follow-up, spawn a replacement, or finish. The main user-visible states a child run can reach are: * **`INPROGRESS`** - the run is actively executing (or has restarted after being blocked). * **`SUCCEEDED`** - the run completed successfully. * **`FAILED`** - the run hit a terminal failure. * **`BLOCKED`** - the run is waiting on a user action (for example, command approval or a permission request). * **`ERROR`** - the run encountered an error during startup or execution. * **`CANCELLED`** - the run was cancelled before reaching a terminal state. Track run state transitions in these places: * **The parent’s transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation. * **The orchestration pill bar** - in the Warp app, while you’re viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child’s name and a status badge that updates live. Click a pill to switch the pane to that child’s conversation in place; click the parent pill to switch back. * **The Oz web app** - cloud children appear under the parent on the [Runs page](https://oz.warp.dev/runs) and in the parent’s **Sub-agents** tab, with their status updating live. * **The Oz API & SDK** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. ## Messaging between agents [Section titled “Messaging between agents”](#messaging-between-agents) Orchestration is built on a durable, server-backed message bus. Every agent in an orchestration - parent and children - has its own inbox addressed by its agent ID, and the parent and children send each other short, structured messages to coordinate, hand off work, and stay in sync as they run. This is how parallel agents stay consistent without sharing mutable state. Each run owns its own conversation, working directory or environment, and credit usage; agents don’t read each other’s transcripts or live working trees. Instead, they exchange explicit messages whenever they need to communicate a decision, a result, or a question. Messages and run state transitions share a global sequence number so the parent never observes a child’s `SUCCEEDED` state before the message that produced the result. The same messaging infrastructure works across every combination of agent runtimes and execution locations: * **Harness-agnostic** - the mailbox is the same whether the recipient runs the default Warp Agent, [Claude Code](/agents/cli-agents/claude-code/), [Codex](/agents/cli-agents/codex/), or another agent runtime. A parent running with one harness can message a child running with another, in either direction. * **Cross-location** - the agent ID is the only address that matters. A local parent can message a cloud child, a cloud parent can message a local-to-cloud child running inside its own environment, and cloud parents can fan out messages to cloud children running in different environments. * **Resumable** - a child whose current run has reached a terminal state (`SUCCEEDED`, `FAILED`, `CANCELLED`, or `ERROR`) is not gone. It is still addressable by its agent ID and will wake up to handle follow-up instructions when the parent sends a new message. Alongside messages, every run emits **lifecycle events** on the same infrastructure when its state changes - the six states listed in [Run state transitions](#run-state-transitions). The parent observes these events to decide what to do next (keep waiting, send a follow-up, spawn a replacement, finish) without polling any child. Use messages for coordination signals - handoffs, decisions, blocked-on-input requests, status updates, and final results - rather than for piping full transcripts around. The parent’s prompt to a child and the child’s final output carry the substance of the work; messages are how the agents talk *about* the work as it happens. ## Common patterns [Section titled “Common patterns”](#common-patterns) The following patterns show common ways to structure parent and child agents, depending on whether you need parallel execution, review, dependency ordering, or loose coordination. ### Supervisor / worker [Section titled “Supervisor / worker”](#supervisor--worker) A parent supervisor agent breaks the task into a queue of work items, spawns worker children to claim and complete each item, and writes a summary when the queue is empty. Use this when the task is naturally divisible and you want a single agent to own coordination. ### Fan-out / fan-in [Section titled “Fan-out / fan-in”](#fan-out--fan-in) The parent spawns N children in parallel, each with a sharded prompt (one module, one file set, one test target, one model), then waits for all of them to complete and merges their results. Use this for large refactors, repo-wide migrations, or running the same task across multiple targets. ### Critic / verifier [Section titled “Critic / verifier”](#critic--verifier) The parent (the “writer”) proposes a solution, then spawns a critic child to review it. The critic returns notes; the writer revises; the cycle repeats until the critic approves or a budget is exhausted. Useful when correctness matters more than throughput. ### Review swarm (cloud → cloud) [Section titled “Review swarm (cloud → cloud)”](#review-swarm-cloud--cloud) A [scheduled](/platform/triggers/scheduled-agents/) or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system. ### DAG [Section titled “DAG”](#dag) The parent encodes a directed acyclic graph of subtasks where some nodes depend on the outputs of others. It spawns ready nodes, waits on their state transitions, and spawns dependents as upstream nodes complete. Use this when the workflow has explicit ordering constraints (build → test → deploy, for example). ### Swarm [Section titled “Swarm”](#swarm) A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are harder to debug than hierarchical patterns. ## Approval mode [Section titled “Approval mode”](#approval-mode) Two slash commands surface orchestration in the Warp app, and both require explicit user approval before any children launch: * **`/orchestrate`** asks the agent to apply orchestration to the task. The agent proposes a breakdown - number of children, prompts, environments, parallelism - and waits for approval. The API equivalent is setting `mode: orchestrate` on `POST /agent/runs`. * **`/plan`** asks the agent to research and produce a plan for a complex task. The agent always considers orchestration while planning, and proposes it as part of the plan when the work would benefit. When orchestration is part of the plan, the plan card surfaces an inline **orchestration config** block above the plan with model, harness, environment, host, and parallelism pickers; you can adjust the config and then approve the plan to start spawning children. The API equivalent is `mode: plan`. In both cases, approval is required before the parent launches children. Approving an orchestration also approves the run-wide config (model, harness, environment, host) that every child inherits unless the parent overrides it per child. ## Observability [Section titled “Observability”](#observability) Because every parent and child is tracked as its own conversation or run, the existing observability surfaces work without changes: * **[Managing cloud agents](/platform/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you’re viewing the parent. Cloud children also appear as their own rows in the Agent Management Panel list. * **[Oz web app](/platform/oz-web-app/)** - the Runs page groups cloud children under the parent’s row, and the parent’s detail pane adds a **Sub-agents** tab. * **[Oz API & SDK](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). * **[Agent notifications](/agents/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent’s conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. ## Related pages [Section titled “Related pages”](#related-pages) * [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical guidance for splitting tasks, assigning worktrees, validating child output, and handing work off for review. * [Oz API & SDK](/reference/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. * [Cloud agents overview](/platform/) - what a cloud agent run is and how it fits into the Automation Platform. * [Deployment patterns](/platform/deployment-patterns/) - higher-level deployment models that orchestration composes with. # Running orchestrated agents Canonical page: [/platform/orchestration/multi-agent-runs/](https://docs.warp.dev/platform/orchestration/multi-agent-runs/) > Start multi-agent orchestrations from the Warp app, the Oz CLI, the Oz web app, or the Oz API & SDK, and inspect parent and child conversations and artifacts. An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the Oz CLI, the Oz web app, or the Oz API & SDK. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. Watch this walkthrough to see how to start and inspect an orchestrated agent run from Warp.  ## Before you start [Section titled “Before you start”](#before-you-start) Pick where the parent will run. Every orchestration starts with a single parent that spawns children: * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. * **Parent in the cloud** - trigger the parent through the Oz CLI (`oz agent run-cloud`), the [Oz API & SDK](/reference/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/platform/self-hosting/). ## Starting an orchestrated run from Warp [Section titled “Starting an orchestrated run from Warp”](#starting-an-orchestrated-run-from-warp) In the Warp app, open the agent input and type `/orchestrate` followed by your task. The agent enters `orchestrate` mode and proposes a breakdown before spawning any children. ```text /orchestrate Migrate every test file in this repo from Jest to Vitest. Spawn one child per top-level directory under packages/. ``` The agent responds with a proposal that describes: * How many children it intends to spawn. * Each child’s prompt and environment. * What it expects each child to return. Approve the proposal to start spawning children. The parent’s transcript renders each child as it spawns, and an **orchestration pill bar** appears above the agent view header showing the parent on the left and one pill per child. Each pill displays the child’s name and a live status badge. Click a child pill to switch the pane to that child’s conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you’re viewing a child - to return to the parent. ### Letting the agent propose orchestration during /plan [Section titled “Letting the agent propose orchestration during /plan”](#letting-the-agent-propose-orchestration-during-plan) You can also reach the same approval flow from `/plan`. When you ask the agent to plan a complex task, it considers orchestration as part of planning and proposes it whenever the work would benefit. When that happens, the plan card includes an inline **orchestration config** block above the plan content with model, harness, environment, host, parallelism, and auth pickers. Edit the config as needed, review the plan’s orchestration section (number of children, what each child owns), and approve the plan to start spawning children with the configured run-wide settings. ### Spawning cloud children from a local parent [Section titled “Spawning cloud children from a local parent”](#spawning-cloud-children-from-a-local-parent) A local parent - a Warp Agent conversation in the Warp app - can spawn cloud children by specifying an environment for each child. The parent asks for the environment if it isn’t already clear from context. You can select any environment from your account or team. Cloud children inherit the parent’s authentication; the same credit and credentials rules from the [Cloud agents overview](/platform/) apply. ## Starting an orchestrated run from the CLI [Section titled “Starting an orchestrated run from the CLI”](#starting-an-orchestrated-run-from-the-cli) Use `oz agent run-cloud` to start a parent and let the agent itself spawn children as it works. ```bash oz agent run-cloud \ --prompt "Review the open pull requests in this repo and post a summary on each. Spawn one child agent per PR." \ --environment YOUR_ENVIRONMENT_ID ``` This is the recommended way to fan work out from the CLI: the parent decides how many children to spawn, links them to itself automatically, and you get a single parent run ID back to follow. ## Starting an orchestrated run from the web app [Section titled “Starting an orchestrated run from the web app”](#starting-an-orchestrated-run-from-the-web-app) In the Oz web app‘s [**Runs** page](https://oz.warp.dev/runs): 1. Click **New run** in the header. 2. Select an environment and, optionally, a skill that performs orchestration. 3. Enter the parent’s prompt. Describe both the high-level task and the orchestration shape you want (number of children, parallelism, success criteria). 4. Click **Run**. The parent run starts and children appear in the Runs list as the parent spawns them, nested under the parent row. ## Starting an orchestrated run from the API [Section titled “Starting an orchestrated run from the API”](#starting-an-orchestrated-run-from-the-api) Spawn the parent with `POST /agent/runs`. Children can either be spawned by the parent agent at runtime, or you can spawn each child explicitly from your code and link it to the parent with `parent_run_id`. Once they’re running, coordination between the parent and its children flows through Warp’s durable agent-to-agent messaging - see [Messaging between agents](/platform/orchestration/#messaging-between-agents) for the model. This section spawns a standalone parent run. If the parent you want to start is a [Warp factory](/factories/)’s foreman, use the [factory API](/factories/factory-api/) to dispatch by factory UID instead of looking up the foreman’s `agent_identity_uid` and calling `POST /agent/run` directly. ### Agent-driven orchestration [Section titled “Agent-driven orchestration”](#agent-driven-orchestration) Start a single parent run with `mode: orchestrate`: ```http POST /api/v1/agent/runs Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "prompt": "Coordinate a code review across every open PR in the repo. Spawn one child per PR.", "mode": "orchestrate", "config": { "environment_id": "YOUR_ENVIRONMENT_ID" }, "title": "PR review swarm" } ``` The parent decides how many children to spawn. Children inherit the parent’s authentication and bill to the same account. ### Caller-driven orchestration [Section titled “Caller-driven orchestration”](#caller-driven-orchestration) Spawn each child explicitly with `parent_run_id` set to the parent’s `run_id`: ```http POST /api/v1/agent/runs Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "prompt": "Review PR #123", "config": { "environment_id": "YOUR_ENVIRONMENT_ID" }, "parent_run_id": "YOUR_PARENT_RUN_ID", "title": "Review PR #123" } ``` Setting `parent_run_id` is what links the child to its parent across the Agent Management Panel in the Warp app, the Oz web app Runs page, and the descendants query (`?ancestor_run_id=`). A scripted fan-out, including parent linking, looks like this: ```bash PARENT_RUN_ID=$(curl -sS -X POST https://app.warp.dev/api/v1/agent/runs \ -H "Authorization: Bearer $WARP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Coordinate the migration", "mode": "orchestrate", "config": {"environment_id": "YOUR_ENVIRONMENT_ID"}, "title": "Jest to Vitest migration" }' | jq -r .run_id) for shard in pkg-a pkg-b pkg-c; do curl -sS -X POST https://app.warp.dev/api/v1/agent/runs \ -H "Authorization: Bearer $WARP_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"prompt\": \"Migrate $shard from Jest to Vitest\", \"config\": {\"environment_id\": \"YOUR_ENVIRONMENT_ID\"}, \"parent_run_id\": \"$PARENT_RUN_ID\", \"title\": \"Migrate $shard\" }" done ``` ## Retrieving conversations and artifacts [Section titled “Retrieving conversations and artifacts”](#retrieving-conversations-and-artifacts) Every parent and child started through the Oz API & SDK is tracked as a cloud agent run. Run responses include the run’s `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you’d use for any other run: * **List every descendant of a parent** - `GET /api/v1/agent/runs?ancestor_run_id=YOUR_PARENT_RUN_ID`. From the CLI: `oz run list --ancestor-run YOUR_PARENT_RUN_ID`. * **Get one run’s details and artifacts** - `GET /api/v1/agent/runs/YOUR_RUN_ID`. * **Read the normalized conversation** - `GET /api/v1/agent/runs/YOUR_RUN_ID/conversation` returns a structured sequence of messages, tool calls, and events. * **Download the raw transcript** - `GET /api/v1/agent/runs/YOUR_RUN_ID/transcript` returns a redirect to a time-limited download URL. All four endpoints work the same for the parent and any child. ## Cancelling a fleet [Section titled “Cancelling a fleet”](#cancelling-a-fleet) Cancel any run with `POST /agent/runs/{runId}/cancel`: ```http POST /api/v1/agent/runs/YOUR_RUN_ID/cancel Authorization: Bearer YOUR_API_KEY ``` Cancelling the parent does **not** automatically cancel its children. This is intentional: in many orchestrations, you want children to finish even after the parent ends. To cancel everything, list the descendants and cancel each one, then cancel the parent: ```bash # List every descendant of the parent, then cancel each. oz --output-format json run list --ancestor-run "$PARENT_RUN_ID" \ | jq -r '.runs[].run_id' \ | xargs -I{} curl -sS -X POST \ https://app.warp.dev/api/v1/agent/runs/{}/cancel \ -H "Authorization: Bearer $WARP_API_KEY" # Finally cancel the parent. curl -sS -X POST \ "https://app.warp.dev/api/v1/agent/runs/$PARENT_RUN_ID/cancel" \ -H "Authorization: Bearer $WARP_API_KEY" ``` Caution Self-hosted, local, and GitHub Action runs cannot be cancelled through this endpoint and return a `422`. Stop them through your own infrastructure. ## Related pages [Section titled “Related pages”](#related-pages) * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and common patterns. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. * [Oz CLI](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. * [Oz API & SDK](/reference/api-and-sdk/) - full HTTP reference and typed SDKs. * [Managing cloud agents](/platform/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the Oz web app. * [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence. * [Self-hosting](/platform/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. * [Handoff between local and cloud agents](/platform/handoff/) - promote a local parent to the cloud, or continue a finished cloud parent with a follow-up. * [Environments](/platform/environments/) - configure the runtime context cloud children execute in. # Automation Platform overview Canonical page: [/platform/overview/](https://docs.warp.dev/platform/overview/) > How cloud agent runs work on the Automation Platform: triggers start tasks, tasks run in environments on a host, and every run leaves a record. [Cloud agents](/platform/) run on the Automation Platform. You define the work (a prompt or a skill) and what starts it, and the platform runs the agent and records what it did. For example, an agent can triage each new issue as it’s filed, or start fixing a build the moment CI fails. If you’re new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes.  ## How a run works [Section titled “How a run works”](#how-a-run-works) Every run follows the same path, whatever starts it: 1. A **trigger** fires: a schedule, an integration event like a Slack mention or a CI failure, an API call, or a manual start. 2. Warp creates a **task**, the tracked record of the run. The trigger’s context travels with it: the Slack thread, the PR metadata, the CI logs. 3. The agent executes on a **host**, optionally inside an [environment](/platform/environments/) that defines its image, repos, and setup. 4. The task produces **outputs**: a pull request, a Slack reply, a report, or just a transcript and summary.  ## Integrations and triggers [Section titled “Integrations and triggers”](#integrations-and-triggers) Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn’t cover, receive the event in your own system and start the run through the [API](/reference/api-and-sdk/); it becomes a normal, fully tracked task. Set up a first-party integration with `oz integration create` on the Oz CLI; the [integration setup guide](/reference/cli/integration-setup/) covers it end to end. ## Tasks and tracking [Section titled “Tasks and tracking”](#tasks-and-tracking) Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [Oz CLI](/reference/cli/) and the [API](/reference/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. To fan work out across parent and child agents, see [multi-agent orchestration](/platform/orchestration/). ## Environments [Section titled “Environments”](#environments) An [environment](/platform/environments/) defines what a run needs: a Docker image with your toolchain, the repositories to clone, and setup commands. Automated runs (integrations, schedules, API calls) use an environment so every run starts from the same setup; interactive local runs use your machine as-is and don’t need one. Define one environment per codebase and reuse it across triggers. ## Hosts [Section titled “Hosts”](#hosts) A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/platform/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/platform/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs.  ## The CLI [Section titled “The CLI”](#the-cli) The [Oz CLI](/reference/cli/) starts and manages runs where there’s no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). ## API and SDKs [Section titled “API and SDKs”](#api-and-sdks) The [Oz API & SDK](/reference/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. ## Secrets [Section titled “Secrets”](#secrets) Agents often need credentials for APIs, cloud providers, databases, and MCP servers. Store them as [secrets](/platform/secrets/), and Warp injects them at runtime without exposing the values in logs or the UI. Secrets can be scoped to the whole team or to one person. ## Shared configuration [Section titled “Shared configuration”](#shared-configuration) Runs pick up your team’s shared setup no matter what triggered them: [MCP servers](/platform/mcp/), [rules](/agents/capabilities/rules/), [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/), and [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/). Configure these once and every trigger uses them. ## Warp Factories [Section titled “Warp Factories”](#warp-factories) [Warp Factories](/factories/) builds on these pieces to run persistent, multi-agent development workflows: specialized cloud agents move each work item through triage, specification, implementation, and review. It’s in Early Access. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ## Where to go next [Section titled “Where to go next”](#where-to-go-next) * [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app. * [Cloud agents quickstart](/platform/quickstart/) - run your first cloud agent in about ten minutes. * [Environments](/platform/environments/) - define the toolchain and repos a run executes against. * [Oz API & SDK](/reference/api-and-sdk/) - drive the platform programmatically. # Oz web app for cloud agents Canonical page: [/platform/oz-web-app/](https://docs.warp.dev/platform/oz-web-app/) > Use the Oz web app to manage cloud agents, view runs, create schedules, and configure environments and integrations from any browser or mobile device. The [Oz web app](https://oz.warp.dev) provides a visual interface for managing cloud agents. You can start runs, browse agents and skills, create schedules, configure environments, and set up integrations—all without installing Warp or using the CLI. Watch this short demo to create an environment and run an agent using the Oz web app:  ## Quick reference [Section titled “Quick reference”](#quick-reference) | Page | Path | What you can do | | ---------------- | --------------- | ----------------------------------------------------------------------------------------------------- | | **Runs** | `/runs` | View all runs, filter by status/source/creator, start new runs, inspect transcripts | | **Agents** | `/agents` | Browse saved agents, create agents, configure defaults, and start runs | | **Skills** | `/skills` | Browse skills from your environments, view suggested skills, create skills for agents, and start runs | | **Schedules** | `/schedules` | Create scheduled agents, pause/enable schedules, view run history | | **Environments** | `/environments` | Create and manage environments with repos, Docker images, and setup commands | | **Secrets** | `/secrets` | Create and manage Warp-managed secrets for cloud agent runs | | **Integrations** | `/integrations` | Connect Slack, Linear, and GitHub to trigger agents from external tools |  The Oz web app Runs page. ## When to use the web app [Section titled “When to use the web app”](#when-to-use-the-web-app) The Oz web app is ideal when you want to: * **Monitor agent activity** — View runs, check status, and inspect outputs from any device * **Start quick runs** — Dispatch agents without opening a terminal * **Manage agents and skills** — Create saved agents, browse skills from connected repositories, and start runs from either configuration * **Manage schedules visually** — Create and edit scheduled agents with a guided interface * **Configure environments** — Set up repos, Docker images, and setup commands through a form-based flow * **Set up integrations** — Connect Slack and Linear with a guided setup flow, and configure how [GitHub](/platform/integrations/github/) mention-triggered runs execute For scripting, automation, and CI/CD workflows, use the [Oz CLI](/reference/cli/) or [API](/reference/api-and-sdk/). ## Getting started [Section titled “Getting started”](#getting-started) When you first sign in to the Oz web app, you’ll see a guided onboarding flow that helps you get started based on your goals. The onboarding asks “What brings you to the Automation Platform?” and offers three paths: * **Create an agent automation** — Walks you through setting up a scheduled agent, integration-triggered agent, or other automation * **Run Cloud Agents in Warp** — Opens the Warp app (or takes you to the download page) to run cloud agents interactively * **Build an app that uses agents** — Links to the [Automation Platform](/platform/overview/) docs for using the CLI, SDK, or API You can skip onboarding at any time to go directly to the Runs page. ## Runs [Section titled “Runs”](#runs) The **Runs** page (`/runs`) is your central view for monitoring cloud agent activity. It shows runs across your account and team, where applicable, including those triggered from the CLI, API, integrations, and schedules. ### Run details [Section titled “Run details”](#run-details) Each run displays the following information: | Field | Description | | --------------- | --------------------------------------------------------------------- | | **Status** | Working, succeeded, failed, canceled, errored, or blocked | | **Title** | The run’s title or prompt summary | | **Environment** | Which environment the agent ran in | | **Creator** | Who started the run | | **Source** | Where the run was triggered from (CLI, API, Slack, Linear, scheduled) | | **Artifacts** | Any outputs like PRs or files created | | **Credits** | How many credits the run consumed | Click any run to open the detail pane, where you can view the full transcript, artifacts, and metadata. ### Filtering and search [Section titled “Filtering and search”](#filtering-and-search) | Quick filter | Shows | | ------------- | --------------------------- | | **All** | All runs | | **Mine** | Only runs you created | | **Active** | Runs currently in progress | | **Failed** | Runs that failed | | **Recurring** | Runs triggered by schedules | You can also search by title, prompt, or agent name, and add advanced filters for source, status, creator, and date range. ### Starting a new run [Section titled “Starting a new run”](#starting-a-new-run) To start a new run: 1. Click **New run** in the header to start a cloud agent. 2. Select an agent, if needed. Choose **Quick run** to run as yourself, or choose a saved agent from the **Agent** dropdown. 3. Select the environment where the agent should run. 4. Add a prompt with context and instructions for this specific run. **Quick run** runs as your own user. A saved agent uses its saved defaults, and your prompt adds context for this particular execution. ### Inspecting orchestrated runs [Section titled “Inspecting orchestrated runs”](#inspecting-orchestrated-runs) The Oz web app renders [multi-agent orchestrations](/platform/orchestration/) as nested rows on the **Runs** page, so you can follow parent and child execution together. Open a parent run from the Runs page. When the run has children, the detail pane adds a **Sub-agents** tab next to **Details**: * Each child agent row shows the child’s current status and title. Click a row to open that child’s detail pane; closing it returns you to the parent’s **Sub-agents** tab. * The parent’s own status badge at the top of the detail pane reflects the parent’s work, not its children. Open a child to inspect its state directly. ## Agents [Section titled “Agents”](#agents) The **Agents** page (`/agents`) is where you browse, create, and run saved agents. Agents are reusable cloud agent configurations that can include a prompt, skills, harness, model, environment, and secrets. Skills are reusable instruction sets stored in repositories. You can attach existing skills to an agent through the **Skills** field; for more details, see [Skills as Agents](/platform/skills-as-agents/). Saved agents use Warp’s team-scoped identity model, which lets a reusable agent own runs and carry default configuration for teammates. You manage saved agents from the Agents page. For plan limits, API endpoints, and API key binding behavior, see [Agents](/platform/agents/).  The Agents page in the Oz web app. Open an agent to review its prompt, skills, harness, model, environment, and attached secrets. From the detail pane, you can inspect activity, create schedules, edit configuration, or start a run from the saved agent. ### Running an agent [Section titled “Running an agent”](#running-an-agent) Click any agent to view its details, then click **New run** to start a run from that saved configuration. You can also click **New run** from the header to start a run with optional agent selection. ### Creating a new agent [Section titled “Creating a new agent”](#creating-a-new-agent) To create a saved agent: 1. Click **New agent** to open the guided creation flow. 2. Define the instructions and defaults. Add a name, description, prompt, optional skills, harness, model, environment, and secrets. 3. Click **Create agent**. The saved agent appears on the Agents page and is available for runs. For deeper guidance on reusable skills and team-scoped identities, see [Skills as Agents](/platform/skills-as-agents/) and [Agents](/platform/agents/).  Creating a new agent in the Oz web app. ## Skills [Section titled “Skills”](#skills) The **Skills** page (`/skills`) is where you browse and run skills. Skills are reusable instruction sets stored in repositories, and agents can include one or more skills as part of their default configuration. Use the **From your Environments** filter to view skills from repositories connected to your environments, or switch to **Suggested** to view recommended skills. Open a skill to view its activity, schedules, and `SKILL.md` configuration. ### Running a skill [Section titled “Running a skill”](#running-a-skill) Click any skill to view its details, then click **New run** to start a run with that skill attached. You can also click **New run** from the page header to start a run with optional skill selection. ### Creating a skill for agents [Section titled “Creating a skill for agents”](#creating-a-skill-for-agents) To create a skill for agents: 1. Click **New agent** on the Skills page to open the skill creation flow. 2. Choose a repository from an existing environment with GitHub access. 3. Define the skill. Add a skill name, description, and instructions. 4. Click **Open Skill PR** to create a pull request that adds the skill to the selected repository.  Creating a skill in the Oz web app. After the PR is merged, refresh skills so the new skill appears in the Oz web app. ## Schedules [Section titled “Schedules”](#schedules) The **Schedules** page (`/schedules`) lets you create and manage scheduled agents that run automatically on a cron schedule. ### Schedule details [Section titled “Schedule details”](#schedule-details) Each schedule displays: | Field | Description | | --------------- | ------------------------------------------------------------------------------ | | **Name** | A descriptive name for the scheduled task | | **Frequency** | Human-readable description of the cron schedule (e.g., “Every Monday at 10am”) | | **Next run** | When the schedule will next execute | | **Environment** | Which environment the scheduled agent runs in | | **Agent** | Which saved agent the schedule uses (if any) | | **Status** | Whether the schedule is active or paused |  The Schedules page in the Oz web app. ### Creating a schedule [Section titled “Creating a schedule”](#creating-a-schedule) To create a scheduled agent: 1. Click **New schedule** in the header. 2. Name the schedule. Use a descriptive name that explains what the scheduled agent does. 3. Set the frequency. Choose a preset or enter a cron schedule. 4. Select the environment where the scheduled agent should run. 5. Choose a saved agent, if needed. 6. Add the prompt that the agent should follow each time it runs. 7. Click **Create schedule**. The schedule appears on the Schedules page. ### Managing schedules [Section titled “Managing schedules”](#managing-schedules) Click any schedule to view its details and recent run history. From the detail pane, you can: * **Edit** the schedule configuration * **Pause** or **enable** the schedule * **Delete** the schedule * **View past runs** triggered by this schedule ## Environments [Section titled “Environments”](#environments) The **Environments** page (`/environments`) shows all environments configured for your account. Environments define the execution context for cloud agents, including repos, Docker images, and setup commands. ### Environment details [Section titled “Environment details”](#environment-details) Each environment displays: | Field | Description | | ------------------ | -------------------------------------- | | **Name** | The environment’s identifier | | **Docker image** | The container image used for execution | | **Repositories** | Which repos the agent can access | | **Setup commands** | Commands run before the agent starts |  The Environments page in the Oz web app. ### Creating an environment [Section titled “Creating an environment”](#creating-an-environment) To create a new environment: 1. Click **New environment** in the header. 2. Name the environment. Use a descriptive name that explains the runtime context. 3. Select the repositories the agent should be able to access. 4. Choose a Docker image. Warp provides prebuilt dev images, or you can use your own. 5. Add any setup commands that should run when the environment starts, such as `npm install`. 6. Click **Create environment**. The environment appears on the Environments page. ## Integrations [Section titled “Integrations”](#integrations) The **Integrations** page (`/integrations`) lets you configure first-party integrations with Slack, Linear, and GitHub. ### Available integrations [Section titled “Available integrations”](#available-integrations) | Integration | Description | | ----------- | ----------------------------------------------------------------------------------------------- | | **Slack** | Tag @warp in messages or threads to trigger agents directly from Slack conversations | | **Linear** | Tag @warp on issues to trigger agents from your issue tracker | | **GitHub** | Mention @warp-agent on issues, pull requests, and review comments to trigger agents from GitHub |  The Integrations page in the Oz web app. ### Setting up an integration [Section titled “Setting up an integration”](#setting-up-an-integration) Click an integration to start the guided setup flow. You’ll authorize Warp to connect with the external service, select an environment, and configure any integration-specific settings. The GitHub row works differently. Instead of an authorization flow started here, it reflects the Warp Factories GitHub App installation that a team admin enables in the Admin Panel. Once the installation is associated with your team, use the row to choose the environment, model, agent, prompt, and secrets that GitHub-triggered runs use. ## Related resources [Section titled “Related resources”](#related-resources) * [Cloud Agents overview](/platform/) — Learn about cloud agents and when to use them * [Multi-agent orchestration](/platform/orchestration/) — Parent/child model and common orchestration patterns * [Skills as Agents](/platform/skills-as-agents/) — Run agents based on reusable skill definitions * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Environments](/platform/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Monitor agent activity and inspect runs * [Oz CLI](/reference/cli/) — Command-line interface for running agents * [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents # Cloud agents quickstart Canonical page: [/platform/quickstart/](https://docs.warp.dev/platform/quickstart/) > Learn how to run your first cloud agent in ~10 minutes. Cloud agents run in remote environments, enabling automation, scheduling, and team collaboration. **Cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. The Automation Platform handles the orchestration, execution, and observability. Cloud agents can run interactively (where you steer them in real-time) or autonomously (as background tasks). Each run creates a persistent session that your team can inspect, share, and query through the Warp app, the CLI, web app, or API. This guide walks you through running your first cloud agent with an environment in about 10 minutes. You’ll create an environment, if needed, and launch a cloud agent to help with a development task. **Common use cases for cloud agents:** * Launch [parallel cloud coding agents](/platform/orchestration/) to multithread complex development tasks * Automate repetitive development tasks (e.g., feature-flag cleanup, documentation updates, fixing server crashes) * Build apps on top of agents, like bug triage and incident response systems *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before you begin, make sure you have: * **Warp desktop app** - Download from the [Warp website](https://www.warp.dev) * **Warp account** - Create an account from the [Oz web app](https://oz.warp.dev) *** ## Running your first cloud agent [Section titled “Running your first cloud agent”](#running-your-first-cloud-agent) *\~10 minutes • Recommended for all users* ### 1. Open Warp [Section titled “1. Open Warp”](#1-open-warp) If you don’t have Warp yet, download it from the [Warp website](https://www.warp.dev) and sign in to your account. When you open the Warp desktop app, you’re automatically authenticated to Warp’s services. ### 2. Run the `/cloud-agent` command [Section titled “2. Run the /cloud-agent command”](#2-run-the-cloud-agent-command) In Warp’s terminal input, type: ```bash /cloud-agent ``` This launches a new cloud agent for you. **How this works:** The `/cloud-agent` command is your entry point to cloud agents. It checks if you have an environment set up, and if not, it guides you through creating one. ### 3. Create your environment [Section titled “3. Create your environment”](#3-create-your-environment) If you don’t have an environment yet, the `/cloud-agent` setup flow will guide you through creating one. You will need: * **Name**: A label to identify this environment (required) * **Repo(s)**: Type repo in `owner/repo` format or select from the dropdown. Click **Auth with GitHub** if you need to connect your repos. * **Docker image**: Your runtime environment (e.g., `python:3.11`, `node:20`). Not sure? Click **Suggest image** and Warp will recommend one based on your repos. * **Setup command(s)**: Commands to prepare your workspace, like `pip install -r requirements.txt` or `npm ci`. Add each command separately by pressing Enter. * **Description**: Optional notes about what this environment is for. **How this works:** Environments are composed of Docker containers + Git repos + startup commands. They give your cloud agent a consistent workspace with your code and tools. Warp detects your project automatically and suggests the right setup. Environments can be shared with your team so everyone uses the same configuration. ### 4. Describe what you want the agent to do [Section titled “4. Describe what you want the agent to do”](#4-describe-what-you-want-the-agent-to-do) Enter your prompt (e.g., “analyze test coverage and suggest improvements”). The agent executes in the cloud with full access to your environment. You can continue conversing with the agent in real-time, watch its progress, and provide additional guidance as it works autonomously on your task. **How this works:** Your cloud agent is now running in Warp’s infrastructure (not on your machine). It clones your repos, runs your setup commands, and starts working on your prompt. The agent has full access to your code and can run tests, make changes, and create artifacts like PRs. ### 5. View run details [Section titled “5. View run details”](#5-view-run-details) You can view details of your agent’s run, including commands executed, files changed, and environment used, several different ways: * In the Warp app, open the [conversations panel](/agents/local-agents/interacting-with-agents/#conversation-panel) to see all your agent runs. * Click the session link in your terminal output. * Go to the [Oz web app](https://oz.warp.dev) and navigate to the **Runs** tab. * Access from mobile via the [Oz web app](/platform/oz-web-app/). **Breaking it down:** Every cloud agent run is auto-tracked. You get a shareable link, a run record, and full visibility into what the agent did. You or your teammates can watch the agent’s progress in real-time and even steer it if needed. The run record persists after completion so you can review it later. ### 6. Make it reusable with a skill (optional) [Section titled “6. Make it reusable with a skill (optional)”](#6-make-it-reusable-with-a-skill-optional) Turn your successful run into a skill that you can reuse: ```bash /create-skill ``` Follow the prompts to save your task definition. Once created, you can run it again, schedule it, trigger it from Slack/Linear, or share it with your team. **How this works:** Skills capture successful agent workflows as reusable building blocks. Instead of typing the same prompt repeatedly, you define it once. You can use it yourself, share it with teammates, schedule it to run automatically, or trigger it from integrations. Learn more about [Skills as Agents](/platform/skills-as-agents/). **Prefer using the CLI?** See the [Oz CLI quickstart](/reference/cli/quickstart/) for CLI-based workflows. *** ## Next steps [Section titled “Next steps”](#next-steps) Now that you’ve run your first cloud agent, try these next steps: * [**Schedule recurring work**](/platform/triggers/scheduled-agents-quickstart/) - Create a scheduled agent for maintenance tasks like dependency checks, cleanup, or triage. * [**Trigger agents from Slack or Linear**](/platform/integrations/quickstart/) - Connect Warp to team tools so mentions and issue updates can launch cloud agent runs. * [**Orchestrate multiple agents**](/platform/orchestration/multi-agent-runs/) - Fan work out across parent and child agents for large refactors, PR review swarms, and parallel package migrations. * [**Turn successful prompts into reusable skills**](/platform/skills-as-agents/) - Save repeatable agent workflows and run them again from the CLI, web app, API, or a schedule. * [**Build programmatic automations**](/reference/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the Oz API & SDK. For example, schedule a recurring agent from the CLI: ```bash oz schedule create \ --name "weekly-dependency-check" \ --cron "0 10 * * 1" \ --environment \ --prompt "check for dependency updates and open PR" ``` *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Environment creation fails**\ Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/platform/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. **Agent can’t access repos**\ Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using an agent API key, make sure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). **Not enough credits to run cloud agents**\ Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). **More resources** * [Environments deep dive](/platform/environments/) * [Cloud Agents FAQs](/platform/faqs/) * [Managing Cloud Agents](/platform/managing-cloud-agents/) # Cloud agent runners Canonical page: [/platform/runners/](https://docs.warp.dev/platform/runners/) > Runners define the OS, architecture, instance size, and sandbox image cloud agents run on, managed with the Oz CLI. Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines *what* an agent works on (the repos, setup commands, and toolchain), a runner defines *where and on what hardware* that work executes. Separating the two lets you reuse the same environment across different machine shapes—for example, a small Linux box for routine tasks and a larger instance for heavier builds. ## Key features [Section titled “Key features”](#key-features) What runners give you: * **Reusable compute configs** – Define an OS, architecture, instance size, and sandbox image once, then reuse the runner across cloud agent runs and orchestration without repeating the configuration. * **Right-sized hardware** – Choose the number of vCPUs and amount of memory a run needs, so lightweight tasks stay cheap and heavy builds get enough resources. * **Flexible OS targets** – Run agents on Linux or macOS. * **Independent of environments** – Override an environment’s default runner per run without changing the environment itself. ## How runners fit into cloud agent runs [Section titled “How runners fit into cloud agent runs”](#how-runners-fit-into-cloud-agent-runs) A runner is the compute layer for a cloud agent run. When a run starts, Warp provisions a sandbox on the runner’s shape, then prepares the workspace defined by the environment (cloning repos and executing setup commands) before the agent begins. * **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). * **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. * **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/platform/self-hosting/) infrastructure). Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. ## Operating systems [Section titled “Operating systems”](#operating-systems) * Linux Linux runners execute the agent in a fresh Docker container. Warp uses the Docker image you select to provide the agent’s base filesystem and toolchains. Warp-hosted Linux runners support any public x86-64 or aarch64 image. By default, runners use [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base). Linux supports any combination of CPU and memory as long as both are a power of two and within your plan’s maximum resource limit. Warp-hosted Linux runners can also run Docker containers and KVM-based virtual machines, such as the Android emulator. * macOS macOS runners execute the agent in a fresh VM on Apple Silicon. You can choose from macOS 14, 15, 26, or 27. If not specified, Warp uses the current macOS release. The VM has Xcode and standard system tools installed, along with simulators for iOS, watchOS, and tvOS. Use setup commands to install additional dependencies. Downloads from Homebrew and popular language package managers are cached automatically. The following resource configurations are supported: * 4 vCPUs, 7 GB memory * 6 vCPUs, 14 GB memory * 8 vCPUs, 14 GB memory * 12 vCPUs, 28 GB memory * 12 vCPUs, 56 GB memory ## Managing runners with the CLI [Section titled “Managing runners with the CLI”](#managing-runners-with-the-cli) Use the [Oz CLI](/reference/cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/reference/cli/quickstart/) to get set up. ### Create a runner [Section titled “Create a runner”](#create-a-runner) Create a runner with a name and the compute configuration you need. ```sh oz runner create \ --name \ --os linux \ --docker-image \ --vcpus 4 \ --memory-gb 8 \ --setup-command "" \ --description "Optional description" ``` Key flags: * `--name` (`-n`) — human-readable label for the runner (required). * `--description` (`-d`) — optional description (max 240 characters). * `--os` — target operating system, `linux` (default) or `macos`. * `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux, aarch64 on macOS). * `--docker-image` — Docker image reference for the sandbox. Linux only. * `--macos-version` — macOS version for the sandbox: `14`, `15`, `26`, or `27`. macOS only. * `--vcpus` — number of vCPUs for the instance shape. Must be set together with `--memory-gb`. * `--memory-gb` — memory in GB for the instance shape. Must be set together with `--vcpus`. * `--setup-command` (`-c`) — command to run when initializing the sandbox. Repeatable. * `--team` / `--personal` — create the runner at the team level or private to your account. Caution OS-specific options must match `--os`. Use `--docker-image` only with `--os linux`, and `--macos-version` only with `--os macos`. ### List runners [Section titled “List runners”](#list-runners) ```sh oz runner list ``` Add `--sort-by name` or `--sort-by last-updated` to order the results. ### Update a runner [Section titled “Update a runner”](#update-a-runner) Change a runner’s name, description, compute shape, or sandbox image without recreating it. Identify the runner by its UID, or by `--name` when you don’t have the UID. ```sh # Update by UID oz runner update --vcpus 8 --memory-gb 16 # Rename a runner (UID identifies it, --name sets the new name) oz runner update --name "new name" # Update by name when you don't have the UID oz runner update --name --docker-image node:22 ``` When updating by UID, `--vcpus` and `--memory-gb` can be set independently—the value you don’t pass is preserved. ### Delete a runner [Section titled “Delete a runner”](#delete-a-runner) ```sh oz runner delete ``` Add `--force` to skip the confirmation prompt. ## Using a runner for a run [Section titled “Using a runner for a run”](#using-a-runner-for-a-run) Pass a runner’s ID to `oz agent run-cloud` to run a cloud agent on that runner. This overrides the environment’s default runner for that run. ```sh oz agent run-cloud --runner --prompt "" ``` You can also select a runner when [running orchestrated agents](/platform/orchestration/multi-agent-runs/), so child agents run on the compute shape their work requires. ## Related pages [Section titled “Related pages”](#related-pages) * [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. * [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. * [Oz CLI reference](/reference/cli/) – Full command-line reference for runners and every other cloud agent command. # Cloud agent secrets Canonical page: [/platform/secrets/](https://docs.warp.dev/platform/secrets/) > Securely store, scope, and inject credentials for Warp cloud agents across CLI, Slack, Linear, and scheduled runs—without ever exposing secret values. Cloud agents often need to interact with external systems such as APIs, databases, cloud providers, or internal tooling. To do this safely, Warp provides Warp-managed **agent secrets**, a secure way to store, scope, and inject credentials into cloud agent runs without exposing secret values to users or logs. Warp-managed secrets are designed to work across [cloud agent](/platform/) and [integration](/platform/integrations/) triggers (CLI, Slack, Linear, and schedules), support both team-wide and personal credentials, and give engineering and security teams visibility into what agents can access. **Warp-managed secrets are useful when:** * A cloud agent needs to call an API or CLI that does not support OAuth * You are using [MCP servers](/platform/mcp/) that expect static tokens or keys * An agent needs credentials for tools like cloud CLIs, databases, monitoring systems, or internal services * You want centralized auditing and control over what credentials agents can access ### Common use cases [Section titled “Common use cases”](#common-use-cases) * Run SQL queries against BigQuery or Metabase to answer questions like “what changed in last night’s pipeline run” or “how many users hit this error today,” using a read-only service account or API token. * Call cloud or infrastructure CLIs to take small, predefined remediation steps when an alert fires, such as restarting a service, scaling a deployment, or clearing a stuck job, using tightly scoped credentials. * List and review all API keys, service accounts, and tokens that cloud agents can access to verify scopes, rotation policies, and ownership match internal security requirements. *** ### How Warp-managed secrets work [Section titled “How Warp-managed secrets work”](#how-warp-managed-secrets-work) Warp provides a set of CLI commands for creating, updating, and listing secrets. Secret values are stored securely and cannot be retrieved once created. At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. Key properties of secrets: * **Scoped** to either a team or an individual user * Secret values are **never readable after creation** (only metadata is visible) * **Automatically set** for cloud agent runs when in scope ### Secret scopes [Section titled “Secret scopes”](#secret-scopes) Each secret has a scope that determines who can use it. #### Team secrets [Section titled “Team secrets”](#team-secrets) Team secrets are shared across the entire team and are available to all cloud agents running on behalf of the team. **Key characteristics:** * Always injected into cloud agent runs, regardless of how the agent is triggered (CLI, Slack, Linear, or scheduled runs) * Available to agents running with or without a specific user context * Ideal for shared infrastructure credentials, service accounts, and read-only API keys **For example:** * Use a Metabase service account or read-only API token, not a personal Metabase API key * Use cloud provider service accounts with minimal required permissions * Use integration-specific tokens created for automation This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. #### Personal secrets [Section titled “Personal secrets”](#personal-secrets) Personal secrets belong to an **individual user**. * Only available to cloud agents triggered by that user * Not accessible to teammates or user-less triggers * Useful for personal API keys or credentials tied to an individual account *** ## Creating secrets in the web app [Section titled “Creating secrets in the web app”](#creating-secrets-in-the-web-app) The [Oz web app](/platform/oz-web-app/) provides a guided side pane for creating Warp-managed secrets. Use it when you want a point-and-click flow without leaving the browser; the CLI flow below remains available for scripting and automation. To create a secret in the web app: 1. In the Oz web app (https\://oz.warp.dev), open the **Secrets** page. 2. Click **Add secret** to open the **Add secret** side pane. 3. Enter a **Name** (for example, `OPENAI_API_KEY`). This becomes the environment variable name injected into runs. 4. Enter the **Value**. The value is encrypted in your browser before it is sent to the server; Warp never sees the plaintext. 5. Optionally, enter a **Description** to help teammates identify the secret later. 6. Choose a **Scope** — **Team** to share the secret with everyone on the team, or **Personal** to keep it scoped to your user. 7. Click **Create secret**. The new secret appears in the Secrets list immediately. Its value is never readable from the UI after creation; to rotate the value, edit the secret and submit a new one. *** ## Managing agent secrets with the CLI [Section titled “Managing agent secrets with the CLI”](#managing-agent-secrets-with-the-cli) Secrets are managed using the `oz secret` command family. You can create secrets interactively or from a file. **Create a team secret interactively** ```bash oz secret create --team METABASE_API_KEY ``` You will be prompted to enter the value securely in the terminal. **Create a personal secret from a file** ```bash oz secret create --personal --value-file api_key.txt METABASE_API_KEY ``` This is useful for long values such as JSON blobs or private keys. #### Adding descriptions [Section titled “Adding descriptions”](#adding-descriptions) Descriptions help with auditing and rotation tracking. ```bash oz secret create --team \ --description "Rotate every 2 weeks; owned by platform team" \ MY_SECRET ``` Descriptions are visible in listings but never expose the secret value. #### Updating a secret [Section titled “Updating a secret”](#updating-a-secret) Updating a secret replaces its value and/or description while keeping the same name and scope. **Update a secret value interactively** ```bash oz secret update --team --value METABASE_API_KEY ``` You will be prompted to enter the new value securely in the terminal. **Update a secret value from a file** ```bash oz secret update --team \ --value-file new_api_key.txt \ METABASE_API_KEY ``` This is the recommended way to rotate credentials. **Update a secret’s description (`-d`)** ```bash oz secret update --team \ --description "Rotated 2026-02-26; owned by platform team" \ METABASE_API_KEY ``` #### Deleting a secret [Section titled “Deleting a secret”](#deleting-a-secret) To permanently remove a secret, use `oz secret delete`: ```bash oz secret delete --team METABASE_API_KEY ``` You will be prompted for confirmation before the secret is deleted. Add `--force` to skip the confirmation prompt. Replace `--team` with `--personal` to delete a personal secret. ```bash oz secret delete --team --force METABASE_API_KEY ``` Caution Deleting a secret is permanent. Any cloud agent runs that depend on the deleted secret will no longer receive it as an environment variable. #### Listing secrets [Section titled “Listing secrets”](#listing-secrets) You can list all secrets you have access to. ```bash oz secret list ``` Example output: ```bash NAME SCOPE LAST UPDATED METABASE_API_KEY team 1 week ago GCP_SERVICE_ACCOUNT_JSON team yesterday MY_MCP_SERVER_TOKEN personal 10:00am ``` **Secret values are never displayed.** ### How secrets are made available to cloud agents [Section titled “How secrets are made available to cloud agents”](#how-secrets-are-made-available-to-cloud-agents) When a cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. Today, secrets are provided as environment variables using the secret name as the variable name. For example: ```bash METABASE_API_KEY=******** ``` #### Secret size limit [Section titled “Secret size limit”](#secret-size-limit) Because secrets are injected as environment variables, each resulting `NAME=value` entry has to fit inside the operating system’s per-variable limit of 128 KiB (131,072 bytes), including the terminating null byte. The usable value length is 128 KiB minus that entry’s environment-variable name, the `=` sign, and the terminating null byte. Warp validates the size when you create or update a secret. Secrets that expand into several environment variables, such as AWS credentials, are validated per variable. If you hit the limit, store the large payload somewhere the agent can fetch it at run time (an object store or a secrets manager the agent can call) and keep only the fetch credential in the Warp-managed secret. *** ### Secret availability by trigger type [Section titled “Secret availability by trigger type”](#secret-availability-by-trigger-type) Which secrets an agent receives depends on how the agent was triggered. #### User-initiated triggers [Section titled “User-initiated triggers”](#user-initiated-triggers) When an agent is triggered by a specific user, such as: * Oz CLI * Slack mentions * Linear updates **The agent receives:** * All team-level secrets * The triggering user’s personal secrets It **does not receive personal secrets** belonging to other team members. When an agent is triggered without a user context, such as: * [Scheduled (cron) agents](/platform/triggers/scheduled-agents/) * Fully automated [integrations](/platform/integrations/) The agent receives: * Team-level secrets only Caution Personal secrets are never injected in these cases. *** ## Scoping secrets to environments and runs [Section titled “Scoping secrets to environments and runs”](#scoping-secrets-to-environments-and-runs) Owner scoping (team versus personal) controls **which secrets exist** for a caller. Two additional layers — environments and individual runs — let you narrow **which of those secrets are actually injected** for a given execution. Together with [cloud agents](/platform/agents/), these layers form a broader access-scoping model where each layer contributes the secrets a run ends up with at execution time. ### Environment-level scoping [Section titled “Environment-level scoping”](#environment-level-scoping) A [cloud environment](/platform/environments/) can declare its own list of secrets. When a run uses that environment, the environment’s attached secrets are added to the run’s allowlist by default. The run can still narrow the allowlist further by passing its own `secrets` list, which then takes precedence. Use this when a workflow’s runtime needs a known, fixed set of credentials — for example, an `ops-tools` environment that only needs `DEPLOY_TOKEN` and `PAGERDUTY_API_KEY`. #### Attach secrets to an environment [Section titled “Attach secrets to an environment”](#attach-secrets-to-an-environment) Use the environment form in the [Oz web app](/platform/oz-web-app/) to attach secrets to an environment: 1. In the Oz web app (https\://oz.warp.dev), open the **Environments** page. 2. Click an existing environment to edit it, or click **New environment** to create one. 3. In the environment form, open the **Secrets** section. 4. Select the team and personal secrets the environment should contribute to each run. Only secret names already in your scope are selectable; values are never displayed. 5. Click **Save**. #### Attachment semantics [Section titled “Attachment semantics”](#attachment-semantics) Environment-attached secrets behave as follows at run time: * **Secret names, not values** - The environment stores references by name. Underlying values stay in the team or personal secret scope, so rotating a value takes effect on the next run without re-attaching the secret. * **Owner scope still applies** - A run only receives an attached secret if the trigger’s owner scope already allows it. Personal secrets are still skipped for triggers without a user context, as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). * **Resolved at run start** - Warp resolves the environment’s attached secrets when the run starts. If a referenced secret has been deleted or renamed since attachment, the run continues and the missing reference is surfaced in the run detail view. ### Run-level scoping [Section titled “Run-level scoping”](#run-level-scoping) Individual runs can override which secrets the run receives by listing them on the run’s config: * **Default (no list provided)** - The run inherits every secret the creator or team has access to that is in scope for the trigger, exactly as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). * **Explicit list of secret names** - Only the listed secrets are injected. Any other secrets the caller can access are skipped for this run. * **Empty list** - The run opts out of all secret injection. No managed secrets are injected, even for triggers that would otherwise receive them. Run-level scoping is exposed through the public REST API on the run config. See the [Oz API & SDK reference](/reference/api-and-sdk/) for the exact field and shape. *** ### Auditing and security considerations [Section titled “Auditing and security considerations”](#auditing-and-security-considerations) Warp is designed to make secret usage auditable and predictable: * Secret values cannot be read or exported after creation * All secrets are explicitly scoped to a team or user * Engineering and security leads can list all secrets available to them * Rotation is handled by updating secrets in place * Cloud agents only receive secrets that are in scope for the trigger **Teams remain responsible for:** * Choosing appropriate scopes for each secret * Limiting permissions on external systems (for example, read-only API keys) * Rotating credentials according to internal policies * Managing which agents and triggers exist within their environment # Self-hosting overview Canonical page: [/platform/self-hosting/](https://docs.warp.dev/platform/self-hosting/) > Run cloud agents on your own infrastructure with a managed worker daemon or unmanaged CLI-based execution you control. Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repository clones, source files, build artifacts, runtime secrets, and agent execution workspaces stay on your infrastructure, and agents can reach services behind your VPN or firewall. **New to self-hosting?** Start with the [Self-hosting quickstart](/platform/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. **Want a CLI-only path with no Docker requirement?** Jump straight to the [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. ## Managed vs unmanaged [Section titled “Managed vs unmanaged”](#managed-vs-unmanaged) Self-hosting has two architectures. The core distinction is **who orchestrates agent runs** — not who owns the compute. Both models keep code and execution on your infrastructure. * **Managed** — The Automation Platform orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to the Automation Platform and waits for work. [Slack](/platform/integrations/slack/) mentions, Linear comments, [schedules](/platform/triggers/scheduled-agents/), API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners). * **Unmanaged** — You orchestrate agent runs. You invoke `oz agent run` directly from your existing CI pipeline, Kubernetes pod, VM, or dev box. The Automation Platform provides session tracking and observability for each run, but does not start or stop agents for you. ### At a glance [Section titled “At a glance”](#at-a-glance) | Aspect | **Managed** | **Unmanaged** | | --------------------------------- | -------------------------------------------------------------------- | ----------------------------------- | | **Who triggers runs** | The Automation Platform (Slack, Linear, schedules, API, `run-cloud`) | Your system (CI, cron, scripts) | | **What runs on your infra** | Long-lived `oz-agent-worker` daemon | One-shot `oz agent run` invocations | | **OS support** | Linux (macOS/Windows coming) | Linux, macOS, Windows | | **Execution isolation** | Docker container, Kubernetes Job, or direct host | Whatever your host provides | | **Automatic environment setup** | Yes (via Warp [environments](/platform/environments/)) | No (you manage it) | | **Session tracking and steering** | Yes | Yes | The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. ## How self-hosting works [Section titled “How self-hosting works”](#how-self-hosting-works) Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp’s backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp’s control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it. If your security requirement is “repository clones and execution must stay on our infrastructure,” self-hosting is designed for that. If your requirement is “no code context can ever route through Warp or an external LLM provider,” review [Security and networking](/platform/self-hosting/security-and-networking/) with your Warp account team before deploying.  With any self-hosted architecture: * **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the [cloud agent dashboard](https://oz.warp.dev), the Warp app, or via the [API/SDK](/reference/api-and-sdk/). Authorized teammates can attach to running sessions to monitor or steer agents. * **Connectivity to Warp’s backend is required** — Agents need outbound access to Warp for orchestration, session storage, and LLM inference. No inbound ports need to be opened. * **Resource limits are controlled by your infrastructure** — Concurrency and compute are only limited by the machines you provision, not by Warp. *** ## Choosing an architecture [Section titled “Choosing an architecture”](#choosing-an-architecture) Caution **OS support:** The managed architecture is **Linux-only** today (macOS and Windows support is coming). If you need agents to run on macOS or Windows, use the [unmanaged](/platform/self-hosting/unmanaged/) architecture, which works on any platform Warp supports. Use these questions to decide between managed and unmanaged: 1. **Do you need agents to run on Windows or macOS?** * Yes → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. Managed is Linux-only today. * No, Linux works → Continue to the next question. 2. **Do you want the Automation Platform to handle starting and stopping agents** (from Slack, the web interface, the Warp app, schedules, or the API)? * Yes → Use the [managed](#managed-architecture) architecture. * No, you have your own triggering mechanism → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. 3. **Can your development environment run in a Docker container or Kubernetes pod?** * Yes, Docker → [Managed: Docker](/platform/self-hosting/managed-docker/) backend. * Yes, Kubernetes → [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. * No (multi-service stacks that don’t fit a single container, or environments where container runtimes aren’t available) → [Unmanaged](/platform/self-hosting/unmanaged/) or [Managed: Direct](/platform/self-hosting/managed-direct/). 4. **Do you have your own orchestrator** (CI/CD, Kubernetes, internal job scheduler) **that starts agents on demand?** * Yes → [Unmanaged](/platform/self-hosting/unmanaged/), using `oz agent run` as a drop-in. * No → [Managed](#managed-architecture). ### Choosing a managed backend [Section titled “Choosing a managed backend”](#choosing-a-managed-backend) The managed architecture supports three backends for task execution: 1. **Are you deploying the worker into a Kubernetes cluster?** * Yes → Use the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). Each task runs as a Kubernetes Job in your cluster; install with the included Helm chart. * No → Continue. 2. **Is Docker available on your worker host?** * Yes → Use the [Docker backend](/platform/self-hosting/managed-docker/) (default). Tasks run in isolated containers. * No → Use the [Direct backend](/platform/self-hosting/managed-direct/). Tasks run directly on the host. 3. **Do you need container-level isolation between tasks?** * Yes → [Docker](/platform/self-hosting/managed-docker/) or [Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. * No → Any backend works. 4. **Do you need Kubernetes-native scheduling, resource management, or policy enforcement?** * Yes → [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). * No → [Docker](/platform/self-hosting/managed-docker/) or [Direct](/platform/self-hosting/managed-direct/) is simpler to set up. *** ## Managed architecture [Section titled “Managed architecture”](#managed-architecture) With the managed architecture, you run the `oz-agent-worker` daemon on your infrastructure. The daemon connects to the Automation Platform‘s backend, waits for tasks to be assigned to it, and executes those tasks on its host using one of three backends: * **[Docker backend](/platform/self-hosting/managed-docker/)** (default) — Runs each task in an isolated Docker container. * **[Kubernetes backend](/platform/self-hosting/managed-kubernetes/)** — Runs each task as a Kubernetes Job in your cluster. * **[Direct backend](/platform/self-hosting/managed-direct/)** — Runs each task directly on the host without a container runtime. The managed architecture enables full orchestration by the Automation Platform — it can remotely start agents via Slack, Linear, the [Oz web app](https://oz.warp.dev), the API/SDK, and the `oz agent run-cloud` command. Agents can access host resources through volume mounts (Docker), Kubernetes-native configuration (Kubernetes), and injected environment variables. ## Unmanaged architecture [Section titled “Unmanaged architecture”](#unmanaged-architecture) With the [unmanaged architecture](/platform/self-hosting/unmanaged/), you run `oz agent run` inside your own orchestrator or dev environment. This works on any platform Warp supports (Linux, macOS, Windows), with no dependency on Docker or any other sandboxing platform. You’re responsible for executing `oz agent run` on your infrastructure — similar to how you’d integrate Claude Code or Codex CLI. The agent runs directly on the host, which could itself be a Kubernetes pod, VM, container, or CI runner. *** ## Routing runs to self-hosted workers [Section titled “Routing runs to self-hosted workers”](#routing-runs-to-self-hosted-workers) This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. ### From the CLI [Section titled “From the CLI”](#from-the-cli) ```bash oz agent run-cloud --prompt "Refactor the authentication module" --host "my-worker" ``` You can combine `--host` with any other `run-cloud` flags, such as `--environment`, `--model`, `--mcp`, `--skill`, `--computer-use`, and `--attach`. ### From scheduled agents [Section titled “From scheduled agents”](#from-scheduled-agents) When creating or updating a schedule, specify the host: ```bash oz schedule create --name "daily-cleanup" \ --cron "0 9 * * *" \ --prompt "Run dead code cleanup" \ --environment ENV_ID \ --host "my-worker" oz schedule update SCHEDULE_ID --host "my-worker" ``` ### From integrations [Section titled “From integrations”](#from-integrations) When creating or updating an integration, specify the host: ```bash oz integration create slack --host "my-worker" ... oz integration update linear --host "my-worker" ... ``` All tasks created through that integration route to your self-hosted worker. ### From the API and SDKs [Section titled “From the API and SDKs”](#from-the-api-and-sdks) When creating a run via the [Oz API & SDK](/reference/api-and-sdk/), include `worker_host` in the config: ```bash curl -X POST https://app.warp.dev/api/v1/agent/run \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Refactor the authentication module", "config": { "environment_id": "ENV_ID", "worker_host": "my-worker" } }' ``` ### From the web UI [Section titled “From the web UI”](#from-the-web-ui) When creating a run, schedule, or integration in the [Oz web app](https://oz.warp.dev), select your self-hosted worker from the host dropdown. *** ## Environments with self-hosted workers [Section titled “Environments with self-hosted workers”](#environments-with-self-hosted-workers) Self-hosted workers fully support [environments](/platform/environments/). When a task specifies an environment, the worker resolves the Docker image, clones the repositories, runs setup commands, and executes the agent inside the prepared container or Kubernetes Job. The same environment can be used for both Warp-hosted and self-hosted runs without modification. If your agents need custom tools, binaries, scripts, or system packages, add them to the environment’s Docker image. See [Environments](/platform/environments/) for details on creating and configuring custom images. Caution Musl-based Docker images (such as Alpine Linux) are not supported as task images. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. ## Monitoring runs [Section titled “Monitoring runs”](#monitoring-runs) Self-hosted runs have the same observability as Warp-hosted runs: * **Run history** — View task status, history, and metadata in the cloud agent dashboard, hosted in the [Oz web app](https://oz.warp.dev), or filter by source and status in the [Agent Management Panel](/platform/managing-cloud-agents/). * **Session sharing** — Authorized teammates can attach to running tasks to [monitor progress](/platform/viewing-cloud-agent-runs/). * **APIs and SDKs** — Query task history and build monitoring using the [Oz API & SDK](/reference/api-and-sdk/). For infrastructure-level observability, the `oz-agent-worker` daemon can export OpenTelemetry metrics (worker health, task throughput, capacity saturation) to Prometheus, an OTLP collector, or the console. See [Monitoring](/platform/self-hosting/monitoring/) for setup, the full metric catalog, and sample PromQL queries. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting quickstart](/platform/self-hosting/quickstart/) — Get a managed worker running in \~10 minutes. * [Unmanaged](/platform/self-hosting/unmanaged/) — Run `oz agent run` in your CI, K8s, or dev environment. * [Managed: Docker](/platform/self-hosting/managed-docker/) — Default managed setup with the Docker backend. * [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Managed setup with the Kubernetes backend and Helm chart. * [Managed: Direct](/platform/self-hosting/managed-direct/) — Managed setup with no container runtime. * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config file schema. * [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. * [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, network egress, and security considerations. * [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker won’t start, tasks not picked up, and other common issues. * [Deployment patterns](/platform/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment. * [Scheduled agents](/platform/triggers/scheduled-agents/) — Route recurring cloud agent work to a self-hosted worker with `--host`. * [Integrations](/platform/integrations/) — Point Slack, Linear, and other triggers at a self-hosted worker. * [Managing cloud agents](/platform/managing-cloud-agents/) — Inspect self-hosted runs alongside Warp-hosted ones. * [Environments](/platform/environments/) — Define the runtime context for agent tasks. * [Customizing workspace snapshots](/platform/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image. # Managed: Direct backend Canonical page: [/platform/self-hosting/managed-direct/](https://docs.warp.dev/platform/self-hosting/managed-direct/) > Run the Automation Platform managed worker with the Direct backend to execute cloud agent tasks directly on the host, without Docker or Kubernetes. Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. The Automation Platform still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. ## When to use the Direct backend [Section titled “When to use the Direct backend”](#when-to-use-the-direct-backend) * Neither Docker nor Kubernetes is available on the worker host. * Tasks need direct access to host resources that are hard to expose through a container. * You want managed orchestration (triggering from Slack, Linear, schedules, API) without the operational overhead of a container runtime. Caution The Direct backend does not provide per-task container isolation. Each task runs in an isolated workspace directory, but shares the host OS and kernel. Evaluate whether this fits your security requirements before using it in production. *** ## How it works [Section titled “How it works”](#how-it-works) 1. The worker creates a per-task workspace directory under `workspace_root`. 2. If a `setup_command` is configured, it runs before the task with environment variables pointing to the workspace. 3. The `oz` CLI runs the agent task inside the workspace directory. 4. After the task completes, the optional `teardown_command` runs and the workspace is cleaned up. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/platform/self-hosting/managed-docker/#install-and-run-the-worker). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). * **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to the Automation Platform. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. *** ## Setup [Section titled “Setup”](#setup) ### 1. Set your API key [Section titled “1. Set your API key”](#1-set-your-api-key) Export the API key so the worker can authenticate to the Automation Platform: ```bash export WARP_API_KEY="your_agent_api_key" ``` ### 2. Start the worker with the Direct backend [Section titled “2. Start the worker with the Direct backend”](#2-start-the-worker-with-the-direct-backend) Pass `--backend direct`: ```bash oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" --backend direct ``` Or with a [config file](/platform/self-hosting/reference/#config-file): ```yaml worker_id: "my-worker" backend: direct: workspace_root: "/var/lib/oz/workspaces" ``` **Expected outcome:** The worker connects to the Automation Platform and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of `workspace_root`. *** ## Workspace model [Section titled “Workspace model”](#workspace-model) Each task gets its own directory under `workspace_root`. The default is `/var/lib/oz/workspaces`; override it with the `workspace_root` config option shown above. After the task completes, the workspace is deleted (unless `--no-cleanup` is set, which keeps the directory around for debugging). *** ## Setup and teardown commands [Section titled “Setup and teardown commands”](#setup-and-teardown-commands) The `setup_command` runs before each task and receives the following environment variables: * `OZ_WORKSPACE_ROOT` — The workspace directory for the task. * `OZ_RUN_ID` — The unique task ID. * `OZ_ENVIRONMENT_FILE` — Path to a file where the setup script can write additional `KEY=VALUE` environment variables to inject into the task. * `OZ_WORKER_BACKEND` — Always set to `direct`. The `teardown_command` runs after each task and receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, and `OZ_WORKER_BACKEND`. Use the setup command to clone repos, install dependencies, or write task-specific env vars into `OZ_ENVIRONMENT_FILE`. Use the teardown command for cleanup or reporting. *** ## Environment variables for Direct tasks [Section titled “Environment variables for Direct tasks”](#environment-variables-for-direct-tasks) Config file example: ```yaml worker_id: "direct-worker" max_concurrent_tasks: 2 backend: direct: workspace_root: "/var/lib/oz/workspaces" oz_path: "/usr/local/bin/oz" setup_command: "/opt/scripts/setup.sh" teardown_command: "/opt/scripts/teardown.sh" environment: - name: MY_VAR value: "hello" ``` *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosted worker reference](/platform/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. * [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. * [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. * [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries and security considerations for the Direct backend. * [Troubleshooting](/platform/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. # Managed: Docker backend Canonical page: [/platform/self-hosting/managed-docker/](https://docs.warp.dev/platform/self-hosting/managed-docker/) > Run the Automation Platform managed worker daemon with the Docker backend to execute cloud agent tasks in isolated containers on your infrastructure. Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the Automation Platform (Slack, Linear, schedules, API, `oz agent run-cloud`). ## When to use the Docker backend [Section titled “When to use the Docker backend”](#when-to-use-the-docker-backend) * You want the simplest managed setup and have Docker available on the worker host. * You want per-task isolation without running a Kubernetes cluster. * You’re not already deploying workloads into Kubernetes. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. * **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to the Automation Platform. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. Caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. ### Install Docker [Section titled “Install Docker”](#install-docker) If Docker is not already installed, follow the [official Docker installation guide](https://docs.docker.com/get-docker/) for your platform. Verify Docker is running: ```bash docker info ``` **Expected outcome:** `docker info` prints daemon details without errors. *** ## Set your API key [Section titled “Set your API key”](#set-your-api-key) Export your agent API key so the worker can authenticate to the Automation Platform: ```bash export WARP_API_KEY="your_agent_api_key" ``` ## Install and run the worker [Section titled “Install and run the worker”](#install-and-run-the-worker) The `oz-agent-worker` is open source. See the [oz-agent-worker repository](https://github.com/warpdotdev/oz-agent-worker) for source code, issues, and contribution guidelines. There are three ways to install and run the worker: as a Docker container, via Homebrew, or as a prebuilt binary from GitHub Releases. Docker is the recommended default. The worker can be configured entirely via CLI flags, or via a YAML [config file](/platform/self-hosting/reference/#config-file) for more complex setups. ### Option 1: Docker (recommended) [Section titled “Option 1: Docker (recommended)”](#option-1-docker-recommended) The worker needs access to the Docker daemon to spawn task containers. Mount the host’s Docker socket into the worker container: ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` **Expected outcome:** The worker connects to the Automation Platform and logs that it’s listening for tasks. ### Option 2: Homebrew [Section titled “Option 2: Homebrew”](#option-2-homebrew) Install the worker binary with [Homebrew](https://brew.sh/) on macOS or Linux from the [`warpdotdev/warp` tap](https://github.com/warpdotdev/homebrew-warp): ```bash brew install warpdotdev/warp/oz-agent-worker ``` Run the binary directly. It uses the same Docker-daemon discovery described in [Docker connectivity](#docker-connectivity) below: ```bash oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` ### Option 3: GitHub Releases binary [Section titled “Option 3: GitHub Releases binary”](#option-3-github-releases-binary) Download the archive for your platform from the [oz-agent-worker releases page](https://github.com/warpdotdev/oz-agent-worker/releases), extract it, and run the binary. The example below uses Linux amd64; choose the archive that matches your OS and CPU architecture: ```bash tar -xf oz-agent-worker-linux-amd64.tar.gz ./oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Once started, the worker connects to the Automation Platform, waits for tasks routed to its `--worker-id`, runs each task in an isolated Docker container, and reports status and results back. The worker automatically reconnects if the connection drops. You can run multiple workers with the same `--worker-id` for redundancy — the Automation Platform distributes tasks across connected workers. *** ## Docker backend configuration [Section titled “Docker backend configuration”](#docker-backend-configuration) The worker can take configuration either via CLI flags or via a YAML [config file](/platform/self-hosting/reference/#config-file). CLI flags take precedence over config file values. **Common CLI flags:** ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "prod-runner-1" \ --log-level debug \ --max-concurrent-tasks 4 \ --idle-on-complete 10m \ -v /opt/shared-cache:/cache:ro \ -e NPM_TOKEN=your_token \ -e GITHUB_TOKEN ``` Caution When running the worker via Docker, there are two levels of `-e` flags. Docker’s `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker’s `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct: ```bash # Docker -e: passes WARP_API_KEY to the worker container # Worker -e: passes MY_SECRET to task containers docker run \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "my-worker" \ -e MY_SECRET=hunter2 ``` **Equivalent config file** (`config.yaml`): ```yaml worker_id: "prod-runner-1" log_level: "debug" max_concurrent_tasks: 4 idle_on_complete: "10m" backend: docker: volumes: - "/opt/shared-cache:/cache:ro" environment: - name: NPM_TOKEN value: "your_token" - name: GITHUB_TOKEN # inherits from host environment ``` Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/platform/self-hosting/reference/) for the full flag and config schema. *** ## Docker connectivity [Section titled “Docker connectivity”](#docker-connectivity) The worker uses the standard Docker client discovery mechanism to find the Docker daemon: 1. **`DOCKER_HOST`** environment variable (e.g., `unix:///var/run/docker.sock`, `tcp://localhost:2375`). 2. **Default socket** (`/var/run/docker.sock` on Linux, `~/.docker/run/docker.sock` for rootless Docker). 3. **Docker context** via `DOCKER_CONTEXT` environment variable. 4. **Config file** (`~/.docker/config.json`) for context settings. Additional Docker environment variables the worker respects: * `DOCKER_API_VERSION` — Specify Docker API version. * `DOCKER_CERT_PATH` — Path to TLS certificates. * `DOCKER_TLS_VERIFY` — Enable TLS verification. **Example: Connecting to a remote Docker daemon** ```bash export DOCKER_HOST="tcp://remote-host:2376" export DOCKER_TLS_VERIFY=1 export DOCKER_CERT_PATH="/path/to/certs" oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` *** ## Private Docker registries [Section titled “Private Docker registries”](#private-docker-registries) The worker automatically uses credentials from your Docker config (`~/.docker/config.json`) when pulling task images. If your [environments](/platform/environments/) use images from a private registry, authenticate the worker’s host first: ```bash docker login your-registry.example.com ``` When running the worker via Docker, mount the Docker config into the container: ```bash docker run \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.docker/config.json:/root/.docker/config.json:ro \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` *** ## Routing runs to this worker [Section titled “Routing runs to this worker”](#routing-runs-to-this-worker) Once your Docker worker is connected, route tasks to it with `--host ""`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting quickstart](/platform/self-hosting/quickstart/) — \~10-minute path to a running Docker worker. * [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands for tasks. * [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, egress, and Docker socket considerations. * [Troubleshooting](/platform/self-hosting/troubleshooting/) — Common issues with the Docker backend. # Managed: Kubernetes backend Canonical page: [/platform/self-hosting/managed-kubernetes/](https://docs.warp.dev/platform/self-hosting/managed-kubernetes/) > Deploy the Automation Platform managed worker into a Kubernetes cluster with the included Helm chart. Each agent task runs as a Kubernetes Job in your cluster. Deploy the `oz-agent-worker` daemon into a Kubernetes cluster using the included Helm chart. Each agent task runs as a **Kubernetes Job** in your cluster. The Automation Platform orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. ## When to use the Kubernetes backend [Section titled “When to use the Kubernetes backend”](#when-to-use-the-kubernetes-backend) * You already operate a Kubernetes cluster and want agents to run there. * You need Kubernetes-native scheduling, resource management, or policy enforcement. * You want to use Kubernetes Secrets, ServiceAccounts, and admission policies to control task behavior. *** ## How it works [Section titled “How it works”](#how-it-works) 1. The worker connects to the Kubernetes API server (using in-cluster auth by default, or an explicit kubeconfig). 2. On startup, the worker runs a short-lived **preflight Job** to verify that cluster permissions, admission policies, and Pod Security Standards are compatible. If the preflight fails, the worker exits with a diagnostic error before accepting any tasks. 3. For each assigned task, the worker creates a Kubernetes Job in the configured namespace. 4. The worker monitors the Job and Pod status via Kubernetes Watch (with a 30-second safety-net poll for watch disconnects). 5. After the task completes, the Job is cleaned up (unless `--no-cleanup` is set). *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Kubernetes cluster** with the worker process able to reach the API server. The cluster must: * Allow the worker’s namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. * **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to the Automation Platform. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. *** ## Install with the Helm chart [Section titled “Install with the Helm chart”](#install-with-the-helm-chart) The `oz-agent-worker` repository includes a namespace-scoped Helm chart at `charts/oz-agent-worker`. This is the recommended way to deploy the worker into a cluster. ### What the chart deploys [Section titled “What the chart deploys”](#what-the-chart-deploys) * A long-lived `Deployment` running `oz-agent-worker` with the Kubernetes backend. * A namespaced `ServiceAccount` for the worker. * A namespaced `Role` / `RoleBinding` with the minimum permissions needed to manage task Jobs and Pods. * A `ConfigMap` containing the worker config YAML. * An optional `Secret` for `WARP_API_KEY` (or a reference to an existing Secret). The chart does not create CRDs or cluster-scoped RBAC resources. ### 1. Set your API key and namespace [Section titled “1. Set your API key and namespace”](#1-set-your-api-key-and-namespace) ```bash export WARP_API_KEY="your_agent_api_key" ``` Create the namespace if it doesn’t exist: ```bash kubectl create namespace warp-oz ``` ### 2. Create the API key Secret [Section titled “2. Create the API key Secret”](#2-create-the-api-key-secret) If you’re not using an existing Secret, create one with the API key: ```bash kubectl create secret generic oz-agent-worker \ --from-literal=WARP_API_KEY="$WARP_API_KEY" \ --namespace warp-oz ``` **Expected outcome:** `kubectl get secret -n warp-oz oz-agent-worker` shows the Secret. ### 3. Install the chart [Section titled “3. Install the chart”](#3-install-the-chart) Clone the worker repo and install the chart: ```bash git clone https://github.com/warpdotdev/oz-agent-worker.git helm install oz-agent-worker ./oz-agent-worker/charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=oz-k8s-worker \ --set image.tag= ``` Caution Set `image.tag` explicitly to pin the worker image. Check the [oz-agent-worker releases](https://github.com/warpdotdev/oz-agent-worker/releases) for the latest version. Do not rely on `latest`. **Expected outcome:** `kubectl get pods -n warp-oz` shows the worker Deployment pod as `Running`, and the worker logs show `Connected to Oz` / `Listening for tasks`. To scale horizontally, deploy multiple Helm releases with distinct worker IDs rather than increasing replicas on a single release. *** ## Key chart values [Section titled “Key chart values”](#key-chart-values) **Required:** * `worker.workerId` — The worker ID (same as `--worker-id`). * `image.tag` — The worker image tag to deploy. **Worker configuration:** * `worker.logLevel` — Log verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`. * `worker.cleanup` — Whether to clean up task Jobs after execution. Defaults to `true`. * `worker.maxConcurrentTasks` — Maximum concurrent tasks. Defaults to `0` (unlimited). * `worker.idleOnComplete` — Duration to keep the oz process alive after task completion. * `worker.resources` — Resource requests/limits for the worker Deployment. Defaults to `100m` CPU and `128Mi` memory. * `worker.livenessProbe` — Liveness probe for the worker Deployment. Defaults to an `exec` probe (`kill -0 1`). Override with a custom probe or set to `null` to disable. * `worker.nodeSelector`, `worker.tolerations`, `worker.affinity` — Scheduling constraints for the worker Deployment pod. **Kubernetes backend:** * `kubernetesBackend.namespace` — Namespace for task Jobs. Defaults to the release namespace. * `kubernetesBackend.defaultImage` — Default Docker image for task pods when no [Warp environment](/platform/environments/) has been supplied. Leave empty (default) to fall back to `ubuntu:22.04`. * `kubernetesBackend.imagePullPolicy` — Image pull policy for task pods. Defaults to `IfNotPresent`. * `kubernetesBackend.preflightImage` — Image for the startup preflight Job. Set this if your cluster restricts allowed registries. * `kubernetesBackend.unschedulableTimeout` — How long a pod may remain unschedulable before failing. Defaults to `30s`. * `kubernetesBackend.setupCommand` — Shell command to run before each task. * `kubernetesBackend.teardownCommand` — Shell command to run after each task. * `kubernetesBackend.extraLabels` — Additional labels for task Jobs and Pods. * `kubernetesBackend.extraAnnotations` — Additional annotations for task Jobs and Pods. * `kubernetesBackend.activeDeadlineSeconds` — Maximum task Job lifetime. * `kubernetesBackend.workspaceSizeLimit` — Size limit for workspace `emptyDir` volume. * `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/platform/self-hosting/reference/#config-file)). **API key Secret:** * `warp.apiKeySecret.create` — Set to `true` to have the chart create a Secret from `warp.apiKeySecret.value`. Defaults to `false` (expects a pre-existing Secret). * `warp.apiKeySecret.value` — The API key value to store in the chart-managed Secret. Only used when `warp.apiKeySecret.create` is `true`. * `warp.apiKeySecret.name` — Name of the Secret containing `WARP_API_KEY`. Defaults to `oz-agent-worker`. * `warp.apiKeySecret.key` — Key within the Secret. Defaults to `WARP_API_KEY`. See the [self-hosted worker reference](/platform/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. *** ## Cluster selection [Section titled “Cluster selection”](#cluster-selection) Cluster selection follows Kubernetes client config conventions: * Set `backend.kubernetes.kubeconfig` to use an explicit kubeconfig file. * If `kubeconfig` is omitted and the worker runs inside a Kubernetes pod, the worker uses in-cluster config automatically. * Otherwise, the worker falls back to the default kubeconfig loading rules and uses the current context. `namespace` selects the namespace inside the chosen cluster. It defaults to `default` when omitted. *** ## Pod template [Section titled “Pod template”](#pod-template) The `pod_template` field accepts standard Kubernetes PodSpec YAML and is the declarative way to configure task pod scheduling, service accounts, image pull secrets, resources, and environment variables. When using `pod_template`, define a container named `task` to customize the main task container directly. Otherwise, the worker appends its own `task` container to the PodSpec. Use `valueFrom.secretKeyRef` to inject Kubernetes Secret values into task container environment variables: ```yaml pod_template: serviceAccountName: agent-task-sa imagePullSecrets: - name: my-registry-creds containers: - name: task resources: requests: cpu: "2" memory: 4Gi limits: memory: 8Gi env: - name: GITHUB_TOKEN valueFrom: secretKeyRef: name: my-k8s-secret key: github-token tolerations: - key: "dedicated" operator: "Equal" value: "agents" effect: "NoSchedule" ``` *** ## Preflight check [Section titled “Preflight check”](#preflight-check) On startup, the worker creates a short-lived preflight Job to verify that: * The worker has sufficient RBAC permissions in the target namespace. * Cluster admission policies (Pod Security Standards, OPA Gatekeeper, Kyverno, etc.) allow the worker’s task pod shape. * The preflight image can be pulled. If the preflight fails, the worker logs a diagnostic error and exits before accepting any tasks. This surfaces policy and configuration issues at deploy time rather than at task execution time. The preflight image defaults to `busybox:1.36`. If your cluster restricts allowed registries or images, set `preflight_image` to an allowlisted image. When `imagePullSecrets` is configured in `pod_template`, those secrets apply to the preflight Job as well, so you can point `preflight_image` at an image in your private registry. *** ## Environment variables for Kubernetes tasks [Section titled “Environment variables for Kubernetes tasks”](#environment-variables-for-kubernetes-tasks) There are two ways to pass environment variables to Kubernetes task containers: 1. **`pod_template`** (recommended for Kubernetes-native config) — Use standard Kubernetes `env` syntax in the `task` container, including `valueFrom.secretKeyRef` for Kubernetes Secrets. 2. **`-e` / `--env` flags** — Backend-agnostic runtime overrides that work across all managed backends. When configuring the Kubernetes backend via YAML or Helm, declarative task-container env belongs in `pod_template` rather than a separate top-level list. *** ## Setup and teardown commands [Section titled “Setup and teardown commands”](#setup-and-teardown-commands) Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/platform/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. *** ## Metrics [Section titled “Metrics”](#metrics) The Helm chart includes built-in support for exporting OpenTelemetry metrics from the worker. Enable metrics by setting `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=oz-k8s-worker \ --set image.tag=VERSION \ --set metrics.enabled=true ``` With the default `metrics.exporter=prometheus`, the chart creates a `Service` with Prometheus scrape annotations and exposes port `9464`. For clusters using the Prometheus Operator, set `metrics.podMonitor.create=true` to create a `PodMonitor`. To push metrics to an OTLP collector instead, set `metrics.exporter=otlp` and configure the endpoint via `metrics.extraEnv`. See [Monitoring](/platform/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. *** ## Operational notes [Section titled “Operational notes”](#operational-notes) * **Scaling** — The chart always deploys a single replica for a given `worker.workerId`. To run multiple workers, deploy multiple Helm releases with distinct worker IDs rather than scaling a single release horizontally. * **Security context** — The Deployment defaults to a non-root security context (`runAsUser: 10001`) with `allowPrivilegeEscalation: false` and all capabilities dropped. * **Liveness probe** — The Deployment includes a default `exec` liveness probe (`kill -0 1`). Override `worker.livenessProbe` for a custom probe, or set it to `null` to disable. * **In-cluster auth** — The chart assumes the worker runs inside the target cluster and uses in-cluster Kubernetes auth by default. * **Root init containers** — The worker Deployment itself is non-root, but task Jobs require a root init container for sidecar materialization. Ensure the task namespace’s Pod Security Standards allow this. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. * [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. * [Routing runs to this worker](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. * [Environments](/platform/environments/) — Define the task image, repos, and setup commands. * [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. * [Security and networking](/platform/self-hosting/security-and-networking/) — RBAC, admission policies, and data boundaries. * [Troubleshooting](/platform/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. # Self-hosted worker monitoring Canonical page: [/platform/self-hosting/monitoring/](https://docs.warp.dev/platform/self-hosting/monitoring/) > Monitor self-hosted Automation Platform workers with OpenTelemetry metrics via Prometheus, OTLP, or console export. The `oz-agent-worker` daemon exports infrastructure-level metrics over [OpenTelemetry](https://opentelemetry.io/), giving your team real-time visibility into worker health, task throughput, and capacity. Combine these metrics with the [cloud agent dashboard](https://oz.warp.dev) for full observability across both the orchestration plane and your self-hosted compute. ## Key features [Section titled “Key features”](#key-features) * **Prometheus scrape** — Expose a `/metrics` endpoint for Prometheus to scrape, with optional `PodMonitor` support for the Prometheus Operator. * **OTLP push** — Push metrics to any OpenTelemetry-compatible collector (Grafana Alloy, Datadog Agent, New Relic, etc.). * **Standard configuration** — Exporter selection uses the standard [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/), so the worker integrates with your existing observability stack without custom configuration. * **Pre-seeded series** — All metric series appear at startup (before any tasks run), so dashboards and alerts can reference them immediately. ## How it works [Section titled “How it works”](#how-it-works) The worker uses the [`go.opentelemetry.io/contrib/exporters/autoexport`](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/exporters/autoexport) package to select an exporter at runtime based on the `OTEL_METRICS_EXPORTER` environment variable. Supported values: * `prometheus` — Starts an in-process HTTP server serving `/metrics`. * `otlp` — Pushes metrics over OTLP (HTTP/protobuf by default). * `console` — Writes metrics to stdout (useful for debugging). * `none` — Disables metrics export entirely. When `OTEL_METRICS_EXPORTER` is unset, the worker defaults to OTLP push targeting `OTEL_EXPORTER_OTLP_ENDPOINT` (which itself defaults to `http://localhost:4318` for `http/protobuf` or `http://localhost:4317` for `grpc`). All metrics carry resource attributes (`service.name=oz-agent-worker`, `service.version`, `worker.id`, `worker.backend`) so each worker process shows up as a distinct series in your monitoring system. *** ## Enable Prometheus scrape [Section titled “Enable Prometheus scrape”](#enable-prometheus-scrape) Set these environment variables before starting the worker to expose a Prometheus-compatible `/metrics` endpoint: ```bash export OTEL_METRICS_EXPORTER=prometheus export OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0 export OTEL_EXPORTER_PROMETHEUS_PORT=9464 oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Verify the endpoint is serving metrics: ```bash curl -s localhost:9464/metrics | grep oz_worker_ ``` **Expected outcome:** You see `oz_worker_connected`, `oz_worker_tasks_active`, and other `oz_worker_*` metric families in the output. *** ## Enable OTLP push [Section titled “Enable OTLP push”](#enable-otlp-push) Set these environment variables to push metrics to an OpenTelemetry collector: ```bash export OTEL_METRICS_EXPORTER=otlp export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability.svc:4318 oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` The worker pushes metrics at the SDK’s default interval. Configure the collector endpoint, protocol, and headers using standard [OTLP exporter environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). *** ## Helm chart configuration [Section titled “Helm chart configuration”](#helm-chart-configuration) The [Helm chart](/platform/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=my-worker \ --set image.tag=VERSION \ --set metrics.enabled=true ``` With `metrics.enabled=true` and the default `metrics.exporter=prometheus`, the chart adds: * A `containerPort: metrics` (default 9464) on the worker Deployment. * The `OTEL_METRICS_EXPORTER`, `OTEL_EXPORTER_PROMETHEUS_HOST`, and `OTEL_EXPORTER_PROMETHEUS_PORT` environment variables. * A namespace-scoped `Service` named `-oz-agent-worker-metrics` with `prometheus.io/scrape` annotations. * Optionally, a `PodMonitor` (`metrics.podMonitor.create=true`) for clusters using the Prometheus Operator. ### Helm values [Section titled “Helm values”](#helm-values) **Core:** * `metrics.enabled` — Enable metrics export. Defaults to `false`. * `metrics.exporter` — Exporter type: `prometheus` (default), `otlp`, `console`, or `none`. * `metrics.port` — Port for the Prometheus exporter. Defaults to `9464`. Ignored for `otlp`/`console`. * `metrics.extraEnv` — Extra environment variables for the worker container (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`). **Service (Prometheus scrape):** * `metrics.service.create` — Create a metrics `Service`. Defaults to `true`. * `metrics.service.type` — Service type. Defaults to `ClusterIP`. * `metrics.service.annotations` — Annotations on the Service. Defaults include `prometheus.io/scrape: "true"`. **PodMonitor (Prometheus Operator):** * `metrics.podMonitor.create` — Create a `PodMonitor`. Defaults to `false` (avoids requiring `monitoring.coreos.com` CRDs). * `metrics.podMonitor.interval` — Scrape interval. Defaults to `30s`. * `metrics.podMonitor.scrapeTimeout` — Scrape timeout. Defaults to `10s`. * `metrics.podMonitor.additionalLabels` — Extra labels on the `PodMonitor` resource. ### OTLP push via Helm [Section titled “OTLP push via Helm”](#otlp-push-via-helm) To push metrics to an OTLP collector instead of exposing a Prometheus endpoint, set `metrics.exporter=otlp` and forward the endpoint via `metrics.extraEnv`: ```yaml metrics: enabled: true exporter: otlp extraEnv: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: http://otel-collector.observability.svc:4318 ``` *** ## Metric catalog [Section titled “Metric catalog”](#metric-catalog) All metrics use the `oz_worker_` prefix. Each worker process emits a distinct set of series, identified by the resource attributes `service.name`, `service.version`, `worker.id`, and `worker.backend`. * **`oz_worker_connected`** (gauge) — `1` while the worker has an active WebSocket connection to the Automation Platform‘s backend, `0` otherwise. * **`oz_worker_tasks_active`** (gauge / UpDownCounter) — Tasks currently executing on this worker. * **`oz_worker_tasks_max_concurrent`** (gauge) — Configured concurrency limit (`0` means unlimited). * **`oz_worker_tasks_claimed_total`** (counter) — Total tasks accepted since process start. * **`oz_worker_tasks_rejected_total{reason}`** (counter) — Tasks the worker declined (e.g., `reason="at_capacity"`). * **`oz_worker_tasks_completed_total{result}`** (counter) — Completed tasks labeled `result="succeeded"` or `result="failed"`. * **`oz_worker_task_duration_seconds{result}`** (histogram) — Wall-clock task duration on the worker, labeled by result. * **`oz_worker_websocket_reconnects_total{reason}`** (counter) — WebSocket reconnect attempts (e.g., `reason="dial_failed"`, `reason="remote_close"`). Spikes indicate flapping workers. * **`oz_worker_info{version,backend,worker_id}`** (gauge, constant `1`) — Build and runtime metadata. Useful for joining other series by labels. *** ## Sample PromQL queries [Section titled “Sample PromQL queries”](#sample-promql-queries) Direct mappings for common operational questions: * **Workers available:** ```promql sum(oz_worker_connected) ``` * **Workers active (running at least one task):** ```promql count(oz_worker_tasks_active > 0) ``` * **Fleet saturation:** ```promql sum(oz_worker_tasks_active) / sum(oz_worker_tasks_max_concurrent > 0) ``` This ratio is only meaningful when every worker has a non-zero `oz_worker_tasks_max_concurrent`. Workers configured with `0` (unlimited) are excluded from the denominator, which can make the saturation result look misleadingly high or undefined for fleets that mix bounded and unlimited workers. * **Task success rate (5-minute window):** ```promql sum(rate(oz_worker_tasks_completed_total{result="succeeded"}[5m])) / sum(rate(oz_worker_tasks_completed_total[5m])) ``` * **Task duration p95:** ```promql histogram_quantile(0.95, sum by (le) (rate(oz_worker_task_duration_seconds_bucket[5m]))) ``` * **Failure rate:** ```promql sum(rate(oz_worker_tasks_completed_total{result="failed"}[5m])) ``` * **Reconnect storms (alert threshold):** ```promql sum(rate(oz_worker_websocket_reconnects_total[5m])) > 0.1 ``` *** ## Disabling metrics [Section titled “Disabling metrics”](#disabling-metrics) To fully disable metrics export, set `OTEL_METRICS_EXPORTER=none`: ```bash export OTEL_METRICS_EXPORTER=none oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Or in the Helm chart: ```yaml metrics: enabled: false ``` *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. * [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. * [Troubleshooting](/platform/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. * [Security and networking](/platform/self-hosting/security-and-networking/) — Network egress and data boundaries. # Self-hosting quickstart Canonical page: [/platform/self-hosting/quickstart/](https://docs.warp.dev/platform/self-hosting/quickstart/) > Get a managed self-hosted Automation Platform worker running on Docker and route your first cloud agent run to it in under 10 minutes. Run your first cloud agent on your own infrastructure in \~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. * **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to the Automation Platform. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). *** ## Run your first self-hosted agent [Section titled “Run your first self-hosted agent”](#run-your-first-self-hosted-agent) *\~10 minutes* ### 1. Export your API key [Section titled “1. Export your API key”](#1-export-your-api-key) Export the agent API key so the worker container can authenticate to the Automation Platform automatically: ```bash export WARP_API_KEY="your_agent_api_key" ``` ### 2. Start the worker [Section titled “2. Start the worker”](#2-start-the-worker) Run the `oz-agent-worker` container, mounting the host’s Docker socket so the worker can spawn task containers. Choose any `--worker-id` meaningful for your team — you’ll use this value to route tasks to this worker. ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` **Expected outcome:** The worker connects to the Automation Platform and begins listening for tasks. You should see log output confirming the connection (something like `Connected to Oz` / `Waiting for tasks`). Caution For production deployments, pin to a specific image digest (e.g., `warpdotdev/oz-agent-worker@sha256:...`) instead of the `latest` tag. ### 3. Route a run to your worker [Section titled “3. Route a run to your worker”](#3-route-a-run-to-your-worker) In a separate terminal on any machine with the Oz CLI, route a cloud agent run to your worker by passing `--host` with the worker ID you chose: ```bash oz agent run-cloud --prompt "List the files in the current directory" --host "my-worker" ``` **Expected outcome:** The Automation Platform accepts the task, routes it to your worker, and the worker spawns a Docker container to execute the agent. You’ll see the run appear in the [cloud agent dashboard](https://oz.warp.dev) with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. ### 4. Verify the run [Section titled “4. Verify the run”](#4-verify-the-run) Open the [cloud agent dashboard](https://oz.warp.dev), find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer it. *** ## Next steps [Section titled “Next steps”](#next-steps) * [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) — \~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. * [Managed: Docker](/platform/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. * [Environments](/platform/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run. * [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the Oz web app. * [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. * [Self-hosted worker reference](/platform/self-hosting/reference/) — All CLI flags and config file options. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Worker won’t start**\ Verify Docker is running (`docker info`) and that the daemon platform is `linux/amd64` or `linux/arm64`. Musl-based (Alpine) worker hosts are not supported. **Worker won’t connect**\ Verify your API key has team scope. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details. **Task stays queued and never runs**\ Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker’s team matches the team creating the task. For more, see [Troubleshooting](/platform/self-hosting/troubleshooting/). # Self-hosted worker reference Canonical page: [/platform/self-hosting/reference/](https://docs.warp.dev/platform/self-hosting/reference/) > Complete reference for the oz-agent-worker daemon — CLI flags and config file schema for the Docker, Kubernetes, and Direct backends. Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/platform/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. For installation instructions, see [Install and run the worker](/platform/self-hosting/managed-docker/#install-and-run-the-worker). *** ## Worker flags [Section titled “Worker flags”](#worker-flags) The following flags are available when starting the worker. ### Required [Section titled “Required”](#required) * `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. * `--api-key` or `WARP_API_KEY` env var — Your agent API key for authentication. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. ### Optional [Section titled “Optional”](#optional) * `--config-file` — Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. * `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) and [Managed: Direct](/platform/self-hosting/managed-direct/) for backend-specific setup. * `--log-level` — Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. * `--no-cleanup` — Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. Useful for debugging failed tasks. * `-v` / `--volumes` — Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. * `-e` / `--env` — Set environment variables for tasks. Format: `KEY=VALUE` (explicit value) or `KEY` (pass through from host environment). Can be specified multiple times. * `--max-concurrent-tasks` — Maximum number of tasks to run concurrently. Defaults to `0` (unlimited). When set, additional tasks wait until a slot is available. * `--idle-on-complete` — How long to keep the `oz` process alive after a task’s conversation finishes, allowing follow-up interactions via session sharing. Uses duration format (e.g. `45m`, `10m`, `0s`). Defaults to `45m` when not set. Set to `0s` to disable. ### Example with all flags [Section titled “Example with all flags”](#example-with-all-flags) ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "prod-runner-1" \ --log-level debug \ --no-cleanup \ --max-concurrent-tasks 4 \ --idle-on-complete 10m \ -v /opt/shared-cache:/cache:ro \ -e NPM_TOKEN=your_token \ -e GITHUB_TOKEN ``` Caution When running the worker via Docker, there are two levels of `-e` flags. Docker’s `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker’s `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct. *** ## Config file [Section titled “Config file”](#config-file) For complex setups, use a YAML config file instead of (or in addition to) CLI flags. Pass it with `--config-file`: ```bash oz-agent-worker --api-key "$WARP_API_KEY" --config-file config.yaml ``` CLI flags always take precedence over config file values. ### Docker backend config [Section titled “Docker backend config”](#docker-backend-config) ```yaml worker_id: "my-worker" cleanup: true max_concurrent_tasks: 4 idle_on_complete: "10m" backend: docker: volumes: - "/data:/data:ro" - "/cache:/cache" environment: - name: NPM_TOKEN value: "your_token" - name: GITHUB_TOKEN # inherits from host environment ``` ### Kubernetes backend config [Section titled “Kubernetes backend config”](#kubernetes-backend-config) ```yaml worker_id: "k8s-worker" max_concurrent_tasks: 4 backend: kubernetes: namespace: "warp-oz" default_image: "my-registry.io/dev-image:latest" unschedulable_timeout: "2m" pod_template: nodeSelector: kubernetes.io/os: linux containers: - name: task resources: requests: cpu: "2" memory: 4Gi env: - name: GITHUB_TOKEN valueFrom: secretKeyRef: name: my-k8s-secret key: github-token ``` ### Direct backend config [Section titled “Direct backend config”](#direct-backend-config) ```yaml worker_id: "direct-worker" max_concurrent_tasks: 2 backend: direct: workspace_root: "/var/lib/oz/workspaces" oz_path: "/usr/local/bin/oz" setup_command: "/opt/scripts/setup.sh" teardown_command: "/opt/scripts/teardown.sh" environment: - name: MY_VAR value: "hello" ``` ### Config file fields [Section titled “Config file fields”](#config-file-fields) **Top-level:** * `worker_id` — Worker identifier (same as `--worker-id` flag). * `cleanup` — Whether to clean up after tasks. Defaults to `true`. Set to `false` to keep containers/workspaces for debugging (equivalent to `--no-cleanup`). * `max_concurrent_tasks` — Maximum concurrent tasks. Defaults to unlimited. * `idle_on_complete` — Duration to keep the `oz` process alive after task completion (e.g. `"45m"`, `"0s"`). * `backend` — Backend configuration block. Only one backend (`docker`, `kubernetes`, or `direct`) may be specified. **`backend.docker`:** * `volumes` — List of volume mounts (same format as `-v` flag). * `environment` — List of environment variables with `name` and optional `value`. If `value` is omitted, the variable is inherited from the host. **`backend.kubernetes`:** * `namespace` — Kubernetes namespace for task Jobs. Defaults to `default`. Selects the namespace inside the chosen cluster; does not choose the cluster. * `kubeconfig` — Path to an explicit kubeconfig file. If omitted, the worker uses in-cluster config when running inside Kubernetes, or falls back to the default kubeconfig loading rules. * `default_image` — Default Docker image for task Jobs when the run has no Warp environment image. Precedence: Warp environment image > `default_image` > `ubuntu:22.04`. Set this to skip creating a Warp environment when all your tasks use the same base image. * `image_pull_policy` — One of `Always`, `Never`, or `IfNotPresent`. Defaults to `IfNotPresent`. * `preflight_image` — Image used for the startup preflight Job. Defaults to `busybox:1.36`. Override this if your cluster only allows pulling from an internal or allowlisted registry. * `setup_command` — Shell command to run before each task. * `teardown_command` — Shell command to run after each task completes. * `extra_labels` — Map of additional labels to add to task Jobs and Pods. * `extra_annotations` — Map of additional annotations to add to task Jobs and Pods. * `active_deadline_seconds` — Maximum lifetime for a task Job (Kubernetes `activeDeadlineSeconds`). * `workspace_size_limit` — Size limit for the workspace `emptyDir` volume (e.g., `10Gi`). * `unschedulable_timeout` — How long a pod may remain unschedulable before the task is failed early. Defaults to `30s`. Set to `0s` to disable the fail-fast behavior. * `pod_template` — Raw Kubernetes PodSpec YAML merged with the worker’s required fields at runtime. Use this to configure task pod scheduling, `serviceAccountName`, `imagePullSecrets`, `nodeSelector`, `tolerations`, resources, and environment variables (including `valueFrom.secretKeyRef` for Kubernetes Secrets). Define a container named `task` to customize the main task container directly; otherwise the worker appends its own. **`backend.direct`:** * `workspace_root` — Directory where per-task workspaces are created. Defaults to `/var/lib/oz/workspaces`. * `oz_path` — Path to the oz CLI binary. If omitted, the worker looks up `oz` in `PATH`. * `setup_command` — Shell command to run before each task. Receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, `OZ_ENVIRONMENT_FILE`, and `OZ_WORKER_BACKEND` as environment variables. * `teardown_command` — Shell command to run after each task completes. * `environment` — List of environment variables (same format as the Docker backend). *** ## Metrics configuration [Section titled “Metrics configuration”](#metrics-configuration) The worker exports metrics over OpenTelemetry. Exporter selection is controlled by standard environment variables, not CLI flags or config file fields. Set these variables on the worker process (or the worker container via Docker `-e` / Kubernetes `env`). * `OTEL_METRICS_EXPORTER` — Exporter to use: `prometheus`, `otlp`, `console`, or `none`. When unset, defaults to `otlp`. * `OTEL_EXPORTER_PROMETHEUS_HOST` — Bind address for the Prometheus exporter. Defaults to `localhost`. Set to `0.0.0.0` when running in Docker or Kubernetes. * `OTEL_EXPORTER_PROMETHEUS_PORT` — Port for the Prometheus exporter. Defaults to `9464`. * `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). * `OTEL_EXPORTER_OTLP_PROTOCOL` — OTLP protocol: `http/protobuf` (default) or `grpc`. When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. *** ## Routing runs to self-hosted workers [Section titled “Routing runs to self-hosted workers”](#routing-runs-to-self-hosted-workers) Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Managed: Docker](/platform/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. * [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. * [Managed: Direct](/platform/self-hosting/managed-direct/) — Direct backend setup and workspace model. * [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands used by task containers. * [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. * [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker and task failure diagnostics. # Security and networking Canonical page: [/platform/self-hosting/security-and-networking/](https://docs.warp.dev/platform/self-hosting/security-and-networking/) > Security model, data boundaries, and network requirements for self-hosted Automation Platform cloud agents — including per-backend considerations and BYOLLM. Self-hosting uses a split-plane architecture. Understanding which data stays on your infrastructure and which data routes through Warp is critical for security evaluation. This page summarizes the data model, network egress requirements, and backend-specific security considerations for self-hosted workers. ## Data boundaries [Section titled “Data boundaries”](#data-boundaries) Self-hosted execution keeps repository clones, source files, build artifacts, runtime secrets, environment variables, and agent workspaces on infrastructure you control. Agents can also reach internal systems that your host can reach, such as VPN-only services, private databases, or self-hosted source control. **Stored and executed only on your infrastructure:** * Repository clones and source files. * Build artifacts and compiled outputs. * Runtime secrets and environment variables. * Container filesystem state (managed architecture) or host workspace (Direct backend / unmanaged). **Routes through Warp’s backend** (under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr)): * Orchestration metadata (task status, lifecycle events). * Session transcripts, which include agent-generated summaries of code context, file contents the agent reads, and command output. * LLM inference requests and responses, which include code context from the agent’s interactions. *** ## Network requirements [Section titled “Network requirements”](#network-requirements) Self-hosted agents **do not require any network ingress**. They require outbound (egress) access to the following services: **Warp’s backend (all architectures):** * `app.warp.dev` — port 443 * `rtc.app.warp.dev` — port 443 * `sessions.app.warp.dev` — port 443 * `oz.warp.dev` — port 443 (managed architecture only) **Docker Hub** — for pulling task images (managed architecture only). Tasks use the following Docker images: * [`warpdotdev/warp-agent:latest`](https://hub.docker.com/r/warpdotdev/warp-agent) * [`warpdotdev/warp-xvfb-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-xvfb-sidecar) (only if [computer use](/agents/capabilities/computer-use/) is enabled) * [`warpdotdev/warp-claude-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-claude-cli-sidecar) (only if using Claude Code) * [`warpdotdev/warp-codex-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-codex-cli-sidecar) (only if using Codex) * The base image specified by your [environment](/platform/environments/) **Google Cloud Storage (`storage.googleapis.com`)** — port 443, for downloading managed Docker Sandbox tooling sidecar archives (Warp CLI, computer use, and coding CLI tooling), uploading conversation transcripts so conversations can be resumed locally, and providing attachments to the agent. **GitHub (`github.com`)** — only with the managed architecture, when using a Warp [environment](/platform/environments/) with configured GitHub repositories. **Linux distribution-specific package repositories** — only with the managed architecture, when using a Warp environment whose base image does not have Git pre-installed. The exact repositories depend on the package manager configuration in the environment’s base image. *** ## Backend-specific security considerations [Section titled “Backend-specific security considerations”](#backend-specific-security-considerations) ### Docker backend [Section titled “Docker backend”](#docker-backend) * **Docker socket access** — The worker requires access to the Docker daemon to create task containers. When running the worker via Docker, this means mounting `/var/run/docker.sock`. Ensure appropriate access controls on the host. * **Volume mounts** — If using `-v` / `--volumes`, be mindful of what host paths you expose to task containers. * **Task isolation** — Each task runs in its own container. Containers are removed after execution by default (disable with `--no-cleanup` for debugging). ### Kubernetes backend [Section titled “Kubernetes backend”](#kubernetes-backend) * **Kubernetes RBAC** — The worker needs namespaced permissions to create, get, list, watch, and delete Jobs and Pods. The Helm chart creates a minimal Role/RoleBinding scoped to a single namespace. The task namespace must allow creating Jobs with a root init container, as sidecar materialization currently depends on that pattern. Review your Pod Security Standards and admission policies accordingly. * **Kubernetes service accounts** — The worker Deployment’s ServiceAccount (used by the long-lived worker process) is separate from the optional task Job `serviceAccountName` you may configure in `pod_template`. Scope each appropriately. * **API key management** — Store `WARP_API_KEY` in a Kubernetes Secret. Avoid hardcoding it in scripts or config files. If your organization uses an external secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, etc.), you can inject secrets into task pods via the CSI Secrets Store Driver or a similar operator — configure the required `volumes`, `volumeMounts`, and annotations in `pod_template`. * **Task isolation** — Each task runs as a separate Kubernetes Job/Pod. Jobs are removed after execution by default (disable with `--no-cleanup` for debugging). ### Direct backend [Section titled “Direct backend”](#direct-backend) * **Shared host kernel** — The Direct backend does not provide container-level isolation. Each task runs in an isolated workspace directory but shares the host OS and kernel. * **Minimal environment by default** — The Direct backend intentionally starts tasks with a minimal environment (`HOME`, `TMPDIR`, `PATH` only). Sensitive worker credentials like `WARP_API_KEY` are not passed to tasks unless explicitly configured. * **Workspace cleanup** — Workspaces under `workspace_root` are removed after execution by default (disable with `--no-cleanup` for debugging). ### Unmanaged [Section titled “Unmanaged”](#unmanaged) * **Host inheritance** — Agents inherit the host’s network access, tools, and credentials. If the host has access to a VPN or internal services, the agent will too. Evaluate accordingly. * **Kubernetes pod isolation** — Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements. *** ## VPN and on-premises access [Section titled “VPN and on-premises access”](#vpn-and-on-premises-access) Since self-hosted agents run on your infrastructure, they inherit your network access. Self-hosted agents can reach services behind VPNs, self-hosted GitLab/Bitbucket instances, databases, and any other internal resources your host can reach. This is one of the primary reasons teams choose self-hosting. See [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for SCM integration details. *** ## LLM inference and BYOLLM [Section titled “LLM inference and BYOLLM”](#llm-inference-and-byollm) LLM inference routes through Warp’s backend. With Warp-managed inference, requests go to contracted providers covered by [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. With customer-supplied inference, provider-side retention follows your team’s agreement with that provider. Enterprise teams that want inference routed and billed through their own accounts can use [team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/); cloud agent support varies by provider, so check each provider’s page. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and architecture decision guide. * [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp’s broader security model, including ZDR. * [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts. * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. # Self-hosting troubleshooting Canonical page: [/platform/self-hosting/troubleshooting/](https://docs.warp.dev/platform/self-hosting/troubleshooting/) > Diagnose and fix common problems with self-hosted Automation Platform worker daemons across Docker, Kubernetes, and Direct backends. Diagnostic guides for the `oz-agent-worker` daemon and its task execution. Use this page when a worker won’t start, won’t connect, tasks stay queued, or tasks fail. *** ## Worker won’t start [Section titled “Worker won’t start”](#worker-wont-start) ### Docker backend [Section titled “Docker backend”](#docker-backend) **Cause:** Docker isn’t running, or the daemon platform isn’t supported. **Fix:** 1. Verify Docker is running: `docker info`. 2. Confirm the daemon platform is `linux/amd64` or `linux/arm64`. Windows containers are not supported. 3. If the worker runs inside Docker, confirm the `/var/run/docker.sock` mount is correct and the mounting user has permission to the socket. ### Kubernetes backend [Section titled “Kubernetes backend”](#kubernetes-backend) **Cause:** The startup preflight Job failed. Common reasons include insufficient RBAC, restrictive Pod Security policies, or an unreachable Kubernetes API server. **Fix:** 1. Check the worker logs for the preflight diagnostic message. 2. Confirm the worker’s namespace has these permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. 3. Confirm the task namespace allows pods with a **root init container** (required for sidecar materialization). 4. If your cluster restricts image sources, set `preflight_image` in the worker config to an allowlisted image (default is `busybox:1.36`). 5. To pull the preflight image from a private registry, configure `imagePullSecrets` in `pod_template` — these secrets also apply to the preflight Job. ### Direct backend [Section titled “Direct backend”](#direct-backend) **Cause:** The `oz` CLI isn’t installed or isn’t on the worker’s `PATH`. **Fix:** 1. Install the Oz CLI on the worker host. See [Installing the CLI](/reference/cli/#installing-the-cli). 2. If the CLI isn’t on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. *** ## Worker won’t connect [Section titled “Worker won’t connect”](#worker-wont-connect) **Cause:** The API key is invalid, expired, or the host cannot reach the Automation Platform‘s backend. **Fix:** 1. Confirm your API key is correct, not expired, and has team scope. 2. Regenerate the API key in **Settings** > **Cloud platform** > **API keys** if you suspect it’s invalid. 3. Ensure the host has outbound internet access to `oz.warp.dev:443`. 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`. 5. Increase log verbosity with `--log-level debug` to see connection details. See [Security and networking](/platform/self-hosting/security-and-networking/#network-requirements) for the full list of outbound endpoints the worker needs. *** ## Tasks not being picked up [Section titled “Tasks not being picked up”](#tasks-not-being-picked-up) **Cause:** The worker isn’t running, the `--host` value doesn’t match the worker’s `--worker-id`, or the worker and task belong to different teams. **Fix:** 1. Confirm the worker is running and connected. Check the worker logs for `Listening for tasks` or similar. 2. Verify the `--host` (or `worker_host`) value you passed matches your `--worker-id` exactly. Case-sensitive. 3. Ensure the worker’s team matches the team creating the task. *** ## Metrics not appearing [Section titled “Metrics not appearing”](#metrics-not-appearing) **Cause:** The worker is running but metrics aren’t showing up in Prometheus or your collector. **Fix:** 1. Verify `OTEL_METRICS_EXPORTER` is set correctly on the worker process. Run `curl -s localhost:9464/metrics` from the worker host (for `prometheus` mode) to confirm the endpoint is serving. 2. For Prometheus scrape mode, confirm the bind address is `0.0.0.0` (not `localhost`) when running in Docker or Kubernetes. `localhost` is only reachable from inside the container. 3. Confirm no firewall or network policy blocks the metrics port (default `9464`). 4. For OTLP push mode, verify `OTEL_EXPORTER_OTLP_ENDPOINT` points to a reachable collector and that the protocol matches (`http/protobuf` vs `grpc`). 5. When using the Helm chart, confirm `metrics.enabled=true` is set. Check that the `Service` and (optionally) `PodMonitor` were created: `kubectl get svc,podmonitor -n `. 6. If using `metrics.podMonitor.create=true`, verify the `monitoring.coreos.com` CRDs are installed in the cluster. The `PodMonitor` resource requires the Prometheus Operator. 7. Restart the worker with `--log-level debug` and look for metrics-related error messages at startup. See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. *** ## Task failures [Section titled “Task failures”](#task-failures) **Cause:** A variety of reasons depending on backend. Start with the diagnostic steps common to all backends, then follow the backend-specific checks. **Fix (all backends):** 1. Review task logs in the [cloud agent dashboard](https://oz.warp.dev) or via [session sharing](/agents/local-agents/session-sharing/). 2. Use `--no-cleanup` to keep the container, Job, or workspace around for inspection after failure. 3. Use `--log-level debug` to see detailed execution logs. 4. Ensure the worker machine or cluster has sufficient resources (CPU, memory, disk). ### Docker backend (task failures) [Section titled “Docker backend (task failures)”](#docker-backend-task-failures) 1. Verify Docker is running (`docker info`). 2. If using a custom image, confirm it is **glibc-based** (not Alpine/musl) and that its architecture matches the worker’s Docker daemon platform. ### Kubernetes backend (task failures) [Section titled “Kubernetes backend (task failures)”](#kubernetes-backend-task-failures) 1. Check task Job and Pod status: `kubectl get jobs,pods -n `. 2. Common issues: * **Unschedulable pods** — Check node selectors, tolerations, and resource requests in `pod_template`. * **Image pull failures** — Check `imagePullSecrets` in `pod_template`. * **Admission policy rejections** — Review Pod Security Standards, OPA Gatekeeper, Kyverno, or similar admission controllers. 3. The worker fails a task early if its pod remains unschedulable beyond `unschedulable_timeout` (default `30s`). Raise the timeout or fix the scheduling issue. ### Direct backend (task failures) [Section titled “Direct backend (task failures)”](#direct-backend-task-failures) 1. Verify the Oz CLI is accessible. 2. Verify the workspace root directory has write permissions for the user running the worker. *** ## Image pull failures [Section titled “Image pull failures”](#image-pull-failures) ### Docker backend (image pull) [Section titled “Docker backend (image pull)”](#docker-backend-image-pull) 1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/platform/self-hosting/managed-docker/#private-docker-registries). 2. Try pulling the image manually on the worker host: `docker pull `. ### Kubernetes backend (image pull) [Section titled “Kubernetes backend (image pull)”](#kubernetes-backend-image-pull) 1. Configure `imagePullSecrets` in the `pod_template` section of your worker config. 2. Verify the Secret exists in the task namespace and contains valid credentials. ### Both backends (image pull) [Section titled “Both backends (image pull)”](#both-backends-image-pull) * Verify the image exists and the tag is correct. * Check network connectivity from the worker/cluster to the registry. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/platform/self-hosting/) — Architecture and decision guide. * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. * [Security and networking](/platform/self-hosting/security-and-networking/) — Outbound endpoints the worker needs. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running tasks to debug interactively. # Unmanaged architecture Canonical page: [/platform/self-hosting/unmanaged/](https://docs.warp.dev/platform/self-hosting/unmanaged/) > Run agents in your existing CI, Kubernetes, or dev environments using the `oz agent run` CLI with Warp tracking and observability. With the unmanaged architecture, **you orchestrate agent runs** by invoking `oz agent run` directly from your existing CI pipelines, Kubernetes pods, VMs, or dev boxes. The agent runs on whatever host the command is executed from; Warp tracks the session for you but does not start or stop agents. ## When to use unmanaged [Section titled “When to use unmanaged”](#when-to-use-unmanaged) * **CI/CD pipelines** — Run agents as part of a build or deployment workflow. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. * **Kubernetes pods** — Run agents inside pods with access to your cluster’s network and services. * **Dev boxes and VMs** — Run agents in pre-provisioned development environments. Especially useful for large monorepos with long setup times. * **Existing orchestrators** — Drop `oz agent run` into any system that schedules work (Jenkins, Buildkite, internal job schedulers). Unmanaged works on any platform Warp supports (Linux, macOS, Windows) with no dependency on Docker or any other sandboxing platform. *** ## Unmanaged quickstart [Section titled “Unmanaged quickstart”](#unmanaged-quickstart) *\~5 minutes* No Docker, no worker daemon, no environment required — just the Oz CLI on any host that can reach the internet. ### Prerequisites [Section titled “Prerequisites”](#prerequisites) * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. * **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate [Section titled “1. Authenticate”](#1-authenticate) Export your API key so the CLI can authenticate requests automatically: ```bash export WARP_API_KEY="your_agent_api_key" ``` ### 2. Run an agent [Section titled “2. Run an agent”](#2-run-an-agent) Invoke `oz agent run` in the directory where you want the agent to operate. The agent has access to whatever tools, network resources, and credentials the host provides. ```bash oz agent run --prompt "Refactor the authentication module" --share team ``` **Expected outcome:** The agent starts immediately in the current working directory, and a tracked session appears in the [cloud agent dashboard](https://oz.warp.dev). ### 3. Control sharing [Section titled “3. Control sharing”](#3-control-sharing) Use `--share` to control who can attach to the session and steer the agent: * `--share` — Share the session with yourself (accessible on other devices or in a browser). * `--share team` or `--share team:view` — Give all team members read-only access. * `--share team:edit` — Give all team members read/write access. * `--share user@example.com` — Give a specific user read-only access. * `--share user@example.com:edit` — Give a specific user read/write access. The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with an agent API key, runs are automatically team-scoped. *** ## Example: GitHub Actions [Section titled “Example: GitHub Actions”](#example-github-actions) Warp maintains the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) action for running agents in GitHub Actions. The action wraps `oz agent run` and is a drop-in for CI workflows: ```yaml - name: Run agent uses: warpdotdev/oz-agent-action@v1 # wraps `oz agent run` under the hood with: prompt: "Review the code changes on this branch" warp_api_key: ${{ secrets.WARP_API_KEY }} ``` See [GitHub Actions integration](/platform/integrations/github-actions/) for full details. ## Example: Kubernetes [Section titled “Example: Kubernetes”](#example-kubernetes) Run an agent inside a Kubernetes pod with access to your cluster’s services: ```yaml apiVersion: batch/v1 kind: Job metadata: name: oz-agent-task spec: template: spec: containers: - name: oz-agent image: warpdotdev/warp-agent:latest command: ["agent", "run", "--prompt", "Run the test suite and report failures"] env: - name: WARP_API_KEY valueFrom: secretKeyRef: name: warp-credentials key: api-key restartPolicy: Never ``` Caution For production deployments, pin to a specific Docker image digest (e.g., `warpdotdev/warp-agent@sha256:...`) instead of `latest` to ensure reproducible builds. *** ## Tracking and observability [Section titled “Tracking and observability”](#tracking-and-observability) Unmanaged agents are tracked on Warp’s backend. Each run creates a persistent session that your team can: * **View** in the [cloud agent dashboard](https://oz.warp.dev). * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. * **Query** through the [Oz API & SDK](/reference/api-and-sdk/) for custom dashboards or monitoring. Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. Unmanaged runs don’t ship with the bundled declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/platform/handoff/) into a follow-up run, see [Customizing workspace snapshots](/platform/handoff/snapshots/). *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/platform/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. * [GitHub Actions integration](/platform/integrations/github-actions/) — Run agents in CI with the official action. * [Deployment patterns](/platform/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. * [Oz CLI](/reference/cli/) — Full CLI reference for `oz agent run` and related commands. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running sessions to monitor or steer them. # Skills as Agents Canonical page: [/platform/skills-as-agents/](https://docs.warp.dev/platform/skills-as-agents/) > Run agents based on skills for consistent, repeatable workflows. Use skills with local or cloud agents from the CLI, Oz web app, API, or on a schedule. You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable set of instructions that defines what the agent should do. When you run an agent based on a skill, the skill provides the base prompt and behavior, while you supply additional context for that specific run. Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp’s infrastructure). This is useful when you want: * **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs. * **Repeatable automation** — Run skills on schedules for maintenance tasks like code cleanup, dependency updates, or issue triage. * **Shareable workflows** — Skills live in repositories, so your team can version, review, and collaborate on agent behavior. *** ## How Skills become available [Section titled “How Skills become available”](#how-skills-become-available) Skill discovery depends on whether you’re running a local or cloud agent. ### Local agents [Section titled “Local agents”](#local-agents) For local agent runs (`oz agent run`), skills are automatically discovered from your current repository. Warp scans these directories in order of precedence: * **`.warp/skills/`** * **`.agents/skills/`** * **`.claude/skills/`** * **`.codex/skills/`** * **`.cursor/skills/`** * **`.gemini/skills/`** * **`.copilot/skills/`** * **`.factory/skills/`** * **`.github/skills/`** * **`.opencode/skills/`** You can also specify a skill from any accessible repository using the fully qualified format: `owner/repo:skill-name`. ### Cloud agents [Section titled “Cloud agents”](#cloud-agents) For cloud agent runs (`oz agent run-cloud`), skills are discovered from repositories configured in your [environments](/platform/environments/). **Discovery workflow:** 1. **Create a skill** in your repository (see [Creating skills](/agents/capabilities/skills/#creating-skills)) 2. **Add the repository** to an environment 3. **The skill appears** in the Agents list in the Oz web app ### Extra skill directories in cloud runs [Section titled “Extra skill directories in cloud runs”](#extra-skill-directories-in-cloud-runs) Skills that don’t live in a cloned repository’s standard skill directories can still be indexed. Set the `WARP_SKILL_DIRS` environment variable to a comma-separated list of skill directories, and a cloud run picks them up alongside the skills it discovers from your repositories. This is useful for skills baked into a custom Docker image, mounted from shared storage, or installed by a setup step outside a repo. Set the variable in the environment’s Docker image so it’s present when the agent starts: Dockerfile ```dockerfile ENV WARP_SKILL_DIRS="/opt/team-skills,tooling/skills" ``` How the value is interpreted: * **Directory layout** - Each entry is a skills directory whose direct children are skill folders containing a `SKILL.md`, the same layout as `.agents/skills/`. Point the variable at the parent directory, not at an individual skill folder. * **Path resolution** - A leading `~` expands to the home directory. Relative entries resolve against the run’s working directory rather than the agent process’s current directory, so they stay stable even when setup steps change directories. * **Precedence** - Skills loaded this way are treated as personal (home) skills, so they stay in scope for the whole run regardless of which directory the agent is working in. Repository skills of the same name still appear separately, as described in [skill name conflicts](/agents/capabilities/skills/#skill-name-conflicts). The Warp Agent harness reads `WARP_SKILL_DIRS` directly. For [third-party harnesses](/platform/harnesses/) such as Claude Code and Codex, a cloud run publishes each of these skills into that harness’s own skill root before launch, so the harness discovers them through its native skill system. *** ## Running skill-based agents [Section titled “Running skill-based agents”](#running-skill-based-agents) You can start an agent from a skill using multiple entry points. ### Web app [Section titled “Web app”](#web-app) Use the [Oz web app](/platform/oz-web-app/) to run skill-based agents from a visual interface. From the web app, you can: * Browse all skills available from your environments on the **Agents** page * View suggested agents from Warp’s public [oz-skills repository](https://github.com/warpdotdev/oz-skills) * Start a new run by selecting a skill, environment, and prompt * Create scheduled agents that run skills on a cron schedule For a complete walkthrough of the web app interface, see [Oz web app](/platform/oz-web-app/). ### CLI [Section titled “CLI”](#cli) Use the `--skill` flag with the Oz CLI: ```sh # Run locally with a skill oz agent run --skill "owner/repo:skill-name" --prompt "additional context" # Run in the cloud with a skill oz agent run-cloud \ --environment \ --skill "owner/repo:skill-name" \ --prompt "additional context" ``` For full CLI documentation, see [Using skills](/reference/cli/#using-skills) in the CLI reference. ### API & SDK [Section titled “API & SDK”](#api--sdk) Use the `skill_spec` parameter when creating a run: ```json { "prompt": "additional context for this run", "config": { "environment_id": "", "skill_spec": "owner/repo:skill-name" } } ``` For full API documentation, see [Agent configuration](/reference/api-and-sdk/#agent-configuration) in the API reference. *** ## Running skills on a schedule [Section titled “Running skills on a schedule”](#running-skills-on-a-schedule) One of the most powerful uses for skill-based agents is running them on a schedule. [Scheduled agents](/platform/triggers/scheduled-agents/) execute automatically at specified times, making them ideal for: * **Dead code cleanup** — Weekly scans for unused code or stale feature flags * **Dependency updates** — Daily or weekly checks for security updates * **Issue triage** — Regular categorization and prioritization of open issues * **Documentation refresh** — Periodic updates to keep docs in sync with code **Creating a scheduled skill-based agent:** ```sh oz schedule create \ --name "Weekly Code Cleanup" \ --cron "0 10 * * 1" \ --environment \ --prompt "Scan for dead code and unused feature flags. Open a PR with removals." ``` You can also create schedules from the [Oz web app](/platform/oz-web-app/) using the **New schedule** action. For full scheduling documentation, see [Scheduled Agents](/platform/triggers/scheduled-agents/). *** ## Suggested Skills [Section titled “Suggested Skills”](#suggested-skills) The [Oz web app](/platform/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows. Suggested skills appear on the Agents page under the **Suggested** filter. *** ## Related resources [Section titled “Related resources”](#related-resources) * [Skills](/agents/capabilities/skills/) — How to create skills and skill file format * [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Oz web app](/platform/oz-web-app/) — Visual interface for managing cloud agents * [Oz CLI](/reference/cli/) — Command-line interface for running agents * [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents # Access, billing, and identity permissions Canonical page: [/platform/team-access-billing-and-identity/](https://docs.warp.dev/platform/team-access-billing-and-identity/) > Understand how access to cloud agents works for individuals and teams, how billing and credits apply, and how Warp maps user identities across integrations. This page explains how access to cloud agents works for both individual users and teams, how billing and credits apply, and how Warp maps user identities across integrations. *** ## Overview: individual vs team access [Section titled “Overview: individual vs team access”](#overview-individual-vs-team-access) Cloud agents can be used in two ways: **Individual users** (without a team): * Can run cloud agents via CLI or API * Can use Warp credits, including [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) * Agents run on Warp-hosted infrastructure * Cannot use integrations (Slack, Linear, Jira, GitHub) or self-hosted agents **Teams** (users who are part of a [Warp team](/knowledge-and-collaboration/teams/)): * All individual capabilities, plus: * Can use integrations (Slack, Linear, Jira, and the [GitHub integration](/platform/integrations/github/)) to trigger agents * Can self-host agents on their own infrastructure (Enterprise only) * Share team-level configuration (environments, secrets, integrations) * Team must be on Build, Max, or Business plan with at least 20 credits for cloud agents and integrations *** ## Individual access [Section titled “Individual access”](#individual-access) Individual users can run cloud agents via the CLI or API without being part of a team. **How it works:** * Run agents using `oz agent run-cloud` or the Oz API & SDK * Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure **What you can do:** * Run cloud agents from CI/CD pipelines * Trigger agents programmatically via API * Use personal secrets for authentication **What requires a team:** * Integrations (Slack, Linear, Jira, and the [GitHub integration](/platform/integrations/github/)) * Self-hosted agent execution * Team secrets and shared configuration *** ## Team access [Section titled “Team access”](#team-access) A [Warp team](/knowledge-and-collaboration/teams/) is a group of users who share configuration and collaborate on cloud agents. Teams can be created on any plan, including Free. **What teams enable:** * **Integrations** - Create Slack, Linear, and Jira integrations that all team members can use, and enable the [GitHub integration](/platform/integrations/github/) so teammates can start agents with an `@warp-agent` mention * **Shared configuration** - Team-level environments, secrets, and settings * **Self-hosting** - Run agents on your own infrastructure (Enterprise only) * **Team visibility** - Shared observability into agent runs and history Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@warp** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. The GitHub integration is team-level in the same way: once an admin enables the GitHub organization, any teammate with a connected GitHub account can start a run by mentioning **@warp-agent**. When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. #### Requirements for integrations [Section titled “Requirements for integrations”](#requirements-for-integrations) Integrations and [cloud agents](/platform/) run inside Warp’s cloud, which means usage is billed based on [credits](/support-and-community/plans-and-billing/credits/). Your team must meet the following requirements to run integrations: * You must be on a **Build, Max, or Business** plan with [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) enabled, or on an **Enterprise** plan with a team credit pool per your contract. * Your team needs at least **20 credits** available to run cloud agents and integrations When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user’s plan-included credits, then the team’s shared add-on credit pool. * **Agent API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner’s plan-included credits, then the team’s shared add-on credit pool. With auto-reload off, the request is blocked when both are depleted. With auto-reload on, usage can trigger a reload into the team’s shared pool subject to the team-wide monthly spend cap; once the cap is reached, runs are blocked until the cap resets or increases. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. ### Identity mapping [Section titled “Identity mapping”](#identity-mapping) Warp needs a reliable way to know which person a cloud agent run is acting for, across Warp, Slack, Linear, and GitHub. * Slack uses a dedicated account-linking flow to map a Slack user to their Warp account. This is the recommended path for Slack-triggered agents, since it doesn’t rely on email matching. * Linear currently maps identities using email address matching. Your Linear email must match your Warp account email for Warp to correctly attribute and scope agent runs. * The [GitHub integration](/platform/integrations/github/) maps the GitHub account that mentioned `@warp-agent` to the Warp account that connected it, rather than by email. Until a teammate connects their GitHub account, Warp replies in the thread with a link to connect instead of starting a run. That binding sets run attribution, team ownership, and billing; the run’s GitHub access comes from the app installation instead. * Each teammate must authorize GitHub before an agent can write PRs or push branches on their behalf * For Slack-triggered, Linear-triggered, and locally triggered runs, agents operate using the GitHub permissions of the triggering user This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. The two exceptions are agent API key runs with [team GitHub authorization](#team-github-authorization) and runs started from an `@warp-agent` mention, which both authenticate as the Warp Factories GitHub App installation. *** ## Team GitHub authorization [Section titled “Team GitHub authorization”](#team-github-authorization) By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Warp Factories** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual’s token. This is useful for fully automated workflows that use an [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works [Section titled “How it works”](#how-it-works) When an agent task is initiated with an agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Warp Factories** GitHub App installation to authenticate directly with GitHub. The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what agent API key runs can access. ### Setting up team GitHub authorization [Section titled “Setting up team GitHub authorization”](#setting-up-team-github-authorization) 1. **Install the Warp Factories GitHub App.** A user with admin permissions on the GitHub organization installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App. During installation, grant the app access to **all repositories** or **selected repositories** in your org. There are two places you may encounter this installation flow: * During the first-time experience for the Automation Platform, when you connect your GitHub account. * When you click **Configure access on GitHub** in the repository selector while creating an environment. Each installation is scoped to a single GitHub organization or personal account — you can install the app to multiple orgs separately. :::  Installing the Warp Factories GitHub App. 2. **Enable the GitHub org for your Warp team.** A Warp team admin opens the Admin Panel in the Warp app (**Settings** > **Admin Panel** > **Platform**) and adds the GitHub organization under **Enabled GitHub Orgs**. This associates the GitHub App installation with your Warp team.  Enabled GitHub Orgs setting in the Admin Panel. 3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Warp Factories GitHub App rather than any individual user; in the cloud agent dashboard, the run is attributed to the bound [cloud agent](/platform/agents/). ### How this relates to environments [Section titled “How this relates to environments”](#how-this-relates-to-environments) An [environment](/platform/environments/) is a template for a cloud agent’s sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by agent API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: * **Environment repo list** - “This agent needs repos A, B, and C.” * **Enabled GitHub Orgs** - “This team can use the Warp Factories GitHub App to access repos in this GitHub organization.” ### Personal tokens vs. GitHub App tokens [Section titled “Personal tokens vs. GitHub App tokens”](#personal-tokens-vs-github-app-tokens) Team GitHub authorization is complementary to the existing personal token flow: * **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates using the triggering user’s personal token. PRs and commits are attributed to that user. * **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Warp Factories GitHub App rather than any individual user. In the cloud agent dashboard, the run is attributed to the bound [cloud agent](/platform/agents/), which controls run filtering and audit attribution on the Warp side. * **[GitHub integration](/platform/integrations/github/) runs** (an `@warp-agent` mention on an issue or pull request) - The agent authenticates as the installation that delivered the event, so its repository access and its GitHub attribution match the agent API key flow. In the cloud agent dashboard the run is still attributed to the teammate who wrote the mention, and their team is billed. These flows can coexist on the same team. Personal tokens are still used for user-triggered runs from a personal API key, Slack, Linear, and the Warp app, and the GitHub App installation token is used for agent API key runs and for GitHub integration runs. Caution GitHub App installation tokens are scoped to a single GitHub organization at a time. If your team works across repos in multiple GitHub organizations, the agent can only use the installation token for the organization enabled in the Admin Panel. Repos in other organizations require user-triggered runs with a personal API key. *** ## Data and permissions [Section titled “Data and permissions”](#data-and-permissions) #### Slack / Linear [Section titled “Slack / Linear”](#slack--linear) Installing the Automation Platform app gives Warp access to the Slack channels or Linear teams where the app is installed. **When a run is triggered, Warp receives:** * The content of the tagged thread or issue * Relevant surrounding context used to build the agent prompt Warp stores only the content required for the agent to complete its task. You can message @warp directly, mention it in channels, or tag it on specific issues depending on the integration. #### GitHub [Section titled “GitHub”](#github) Warp’s behavior in GitHub is defined by two layers of control: 1. **The Warp GitHub App installation scope** * Determines which organizations and repositories Warp can read and write to * Can be edited at any time in GitHub settings 2. **Permissions of the triggering user** * Agents inherit the user’s read/write privileges * Agents cannot elevate permissions, see additional repos, or write to repos the user cannot access **In practice, agents can only operate on repositories that:** * Are included in the environment configuration * Are accessible to both the GitHub app and the triggering user. Runs triggered by an `@warp-agent` mention through the [GitHub integration](/platform/integrations/github/) follow the first layer only. Warp receives the content of the issue, pull request, or review thread that carried the mention, including the recent comments and the diff of a commented file, and the run authenticates with the GitHub App installation that delivered the event. Cloning, commits, branches, pull requests, and status comments all use that installation’s access rather than the mentioning user’s, so the installation’s repository selection is the only boundary on what those runs can reach. The repository that triggered the mention is cloned alongside any repositories in the configured environment, and only the repositories that installation covers are available to the agent. *** ## Additional notes: how cloud agents use credits [Section titled “Additional notes: how cloud agents use credits”](#additional-notes-how-cloud-agents-use-credits) Cloud agents can run automatically in the background when activated by a trigger such as a Slack mention, a Linear update, or a scheduled task. These runs require compute and model usage, which translates to credit consumption. **Typical credit usage:** Cloud agent runs consume credits based on the complexity of the task and whether an environment is used. The exact amount varies by run. #### How credit usage works [Section titled “How credit usage works”](#how-credit-usage-works) How credits are consumed depends on how the agent run is triggered and authenticated: **User-triggered runs** (CLI with personal API key, Slack, Linear, or the Warp app): * Runs are tied to the triggering user’s identity. * On Build, Max, and Business plans, Warp consumes credits in a fixed order. You cannot prioritize user-scoped grants ahead of shared team grants: 1. The triggering user’s monthly credits included with their plan. 2. Shared bonus or add-on grants available to the active team (team-wide pool first). 3. The triggering user’s remaining user-scoped bonus or add-on grants that apply to the active team. This includes any remaining add-on credit balance purchased between May and August 2026. Warp uses these grants only after shared team grants are exhausted. * On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. **Agent API key and scheduled cloud agent runs** (fully automated workflows): * Runs are not tied to any individual user. * On Build, Max, and Business plans, Warp bills the team owner: the owner’s plan-included credits, then the team’s shared add-on credit pool. With auto-reload off, the request is blocked when both are depleted. With auto-reload on, usage can trigger a reload into the team’s shared pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. For more details on creating and using API keys, see [API Keys](/reference/cli/api-keys/). #### Who configures triggers and workflows [Section titled “Who configures triggers and workflows”](#who-configures-triggers-and-workflows) All triggers and instructions used by cloud agents are defined and controlled by your team’s authorized users. * Admins or other authorized users decide which triggers exist, when they fire, and what the agent should do in response. * Trigger behavior and the agent’s instructions (system prompts, workflow steps, repo access, etc.) are fully managed by your admins or other designated users. #### Staying aware of usage [Section titled “Staying aware of usage”](#staying-aware-of-usage) Because triggers and instructions are configured by your team, the credits consumed when an agent runs are billed according to the model above: * **Build, Max, Business** - User-triggered runs draw from the triggering user’s plan-included credits, then shared team grants, then any remaining user-scoped grants. Agent API key runs and scheduled cloud agent runs are billed to the team owner (the owner’s plan-included credits, then the team’s shared add-on credit pool, subject to the team-wide spend cap when auto-reload is on). * **Enterprise** - All runs draw from the team-scoped credit pool, per your Enterprise contract terms. It’s the team’s responsibility to manage triggers, confirm they behave as intended, and monitor usage. Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix: * **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. * **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. * **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. *** ## Related resources [Section titled “Related resources”](#related-resources) * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) - How team-shared add-on credits, auto-reload, and the team-wide spend cap work on self-serve plans. * [Platform credits](/support-and-community/plans-and-billing/platform-credits/) - The third credit bucket that applies to every cloud agent run, alongside AI credits and compute credits. * [Credits overview](/support-and-community/plans-and-billing/credits/) - The full credit model across plans. # Triggers overview Canonical page: [/platform/triggers/](https://docs.warp.dev/platform/triggers/) > Configure triggers to run cloud agents automatically based on schedules or events. A trigger is anything that starts a cloud agent run without you typing a prompt: a recurring schedule, an integration like Slack or Linear, a CI event, or a call to the API. This page covers the full set, including the [integrations](/platform/integrations/) that connect agents to the tools your team already uses. To set up your first recurring agent, follow the [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/). If you’re choosing between schedules, Slack, Linear, GitHub, GitHub Actions, the Oz CLI, or the API, start with [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). ## Available trigger types [Section titled “Available trigger types”](#available-trigger-types) * **[Scheduled Agents](/platform/triggers/scheduled-agents/)** - Run agents on a recurring schedule using cron expressions. * **[CLI](/reference/cli/)** - Trigger cloud agents directly from your terminal using the Oz CLI. * **[API & SDK](/reference/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. * **[Integrations](/platform/integrations/)** - Trigger agents from external services like Slack, Linear, or Jira. * **[GitHub](/platform/integrations/github/)** - Mention `@warp-agent` on an issue, pull request, or review comment to start an agent that replies in the thread. * **[GitHub Actions](/platform/integrations/github-actions/)** - Run agents from your own CI workflows and repository events. * **[Custom webhooks](/factories/webhooks/)** - Give a [factory](/factories/) an authenticated URL that any system can POST JSON to, and start its automations from the deliveries. After a trigger fires, track and review the resulting runs across your team from the [Agent Management Panel and Oz web app Runs page](/platform/managing-cloud-agents/), where you can filter by source, status, day, or creator. # Scheduled Agents Canonical page: [/platform/triggers/scheduled-agents/](https://docs.warp.dev/platform/triggers/scheduled-agents/) > Run cloud agents on a cron schedule for automated maintenance and recurring tasks. Warp’s Scheduled Agents let you run cloud agents automatically on a **recurring schedule**. They are designed for routine, repeatable tasks that should happen without manual intervention, such as dead code cleanup, dependency maintenance, issue triage, or periodic refactors.  Scheduled Agents run in the background on Warp’s infrastructure. Each run starts from a clean session, executes a fixed prompt, and produces its own task and session history that can be inspected after the fact. For a guided, no-CLI walkthrough that creates a recurring agent from the Oz web app, see the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/). This page is the full reference for managing schedules with the Oz CLI. If you’re deciding whether to use a schedule, Slack or Linear trigger, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). *** ### What are Scheduled Agents? [Section titled “What are Scheduled Agents?”](#what-are-scheduled-agents) A Scheduled Agent is a [cloud agent](/platform/) that runs on a cron-based schedule. **Key characteristics:** * Runs automatically based on a cron expression. * Uses a fixed prompt defined at schedule creation time. * Starts a fresh agent session for every run. * Executes in a specific Warp [Environment](/platform/environments/), if provided. * Consumes credits when it runs. * Can be paused, updated, or deleted at any time. Scheduled Agents are ideal for work that should happen regularly and predictably, without needing a human to trigger the agent manually. ### Common use cases [Section titled “Common use cases”](#common-use-cases) Scheduled Agents are best suited for maintenance-style workflows, including skills that automate recurring tasks. For more on running skill-based agents on schedules, see [Skills as Agents](/platform/skills-as-agents/). Common use cases include: * Dead code or unused feature flag cleanup. * Dependency updates or security scans. * Issue or PR triage on a recurring cadence. * Periodic documentation refreshes. * Repository hygiene tasks like formatting or lint checks. * Scheduled reporting or audits. Because each run is isolated, Scheduled Agents are safe to use for tasks that benefit from a clean, repeatable execution environment. *** ### Scheduling agents with the CLI [Section titled “Scheduling agents with the CLI”](#scheduling-agents-with-the-cli) Automation Platform scheduled agents are managed through the Automation Platform `schedule` family of CLI commands. All scheduling operations require the Oz CLI and an authenticated session. #### Creating a schedule [Section titled “Creating a schedule”](#creating-a-schedule) Use `oz schedule create` (with required flags) to define a new Scheduled Agent. **Each schedule requires:** * A name, for identification. * A cron schedule. * A prompt or skill that the agent will execute. * An optional environment in which the agent will run. * An optional [model selection](/reference/cli/#using-agent-profiles). * [Optional MCP server configuration](/platform/mcp/). ```bash oz schedule create \ --name=NAME \ --cron=SCHEDULE \ --prompt=PROMPT \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--model=MODEL_ID] \ [--file=PATH] ``` **Optional flags:** * `--skill ` — use a skill as the base prompt (format: `repo:skill_name` or `org/repo:skill_name`). See [Skills as Agents](/platform/skills-as-agents/). * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--mcp ` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated. * `--model ` — override the default model. * `--file ` — load schedule configuration from a YAML or JSON file. Caution `oz schedule create` has no **Agent** flag, so a schedule created with the CLI runs as its creator and opens pull requests under that person’s GitHub account. To run it as a [cloud agent](/platform/agents/) instead, set **Agent** on the schedule from the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app after creating it. See [Run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship). **Example** The following command schedules an agent to clean up old feature flags every four days: ```bash oz schedule create \ --name "Feature Flag Cleanup" \ --cron "0 10 */4 * *" \ --prompt "Scan the repository for stale feature flags and remove any that are no longer referenced. Open a PR with the changes and include a summary." \ --environment "KB1ndNMQAs5kjPdX2jatA8" ``` Once created, the agent will automatically run at the specified times without further action. Scheduled Agents support the same [model selection](/reference/cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. #### Cron schedule format [Section titled “Cron schedule format”](#cron-schedule-format) Warp uses standard cron syntax to define schedules. A cron expression consists of five fields: ```plaintext minute hour day-of-month month day-of-week ``` For example: * `0 10 * * *` runs every day at 10:00 AM. * `0 10 */4 * *` runs every four days at 10:00 AM. * `0 8 1 * *` runs at 8:00 AM on the first day of every month. Make sure your cron expression reflects the cadence you want, as Scheduled Agents will run exactly according to this schedule. ### Listing Scheduled Agents [Section titled “Listing Scheduled Agents”](#listing-scheduled-agents) To view all Scheduled Agents for your team, use: ```bash oz schedule list ``` This command prints a table with details about each schedule, including: * Schedule ID * Name * Cron schedule * Paused * Last run time * Next scheduled run * Scope | ID | Name | Schedule | Paused | Last Ran | Next Run | Scope | | ------ | -------------------- | -------------- | ------ | -------------------------------------------- | --------------------- | ----- | | abc123 | Feature Flag Cleanup | `0 10 */4 * *` | No | `2025-11-24 10:00 AM` | `2025-11-28 10:00 AM` | Team | | def456 | Issue Triage | `0 8 1 * *` | Yes | `2025-11-24 08:00 AM` | Paused | - | Each completed run also includes links to: * The task created by the agent. * The full agent session, including logs and outputs. This makes it easy to review what ran, when it ran, and what the agent did. You can also monitor scheduled runs alongside your other agents in the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where you can filter by the **Scheduled** source to isolate them. #### Viewing a specific Scheduled Agent [Section titled “Viewing a specific Scheduled Agent”](#viewing-a-specific-scheduled-agent) Use `oz schedule get` to view detailed information about a single Scheduled Agent. ```bash oz schedule get SCHEDULE_ID ``` This command returns additional details not shown in the list view, including: * Full schedule configuration * Prompt and model configuration * Environment and MCP settings * Recent runs and execution metadata * Links to related tasks and agent sessions This is useful when reviewing behavior, debugging failures, or inspecting how a Scheduled Agent is configured. ### Pausing and unpausing schedules [Section titled “Pausing and unpausing schedules”](#pausing-and-unpausing-schedules) Scheduled Agents can be temporarily disabled without deleting them. ```bash oz schedule pause SCHEDULE_ID ``` When paused, the agent will not run at its scheduled times. **Example** ```bash oz schedule pause abc123 ``` #### Unpausing a schedule [Section titled “Unpausing a schedule”](#unpausing-a-schedule) ```bash oz schedule unpause SCHEDULE_ID ``` Once unpaused, the agent resumes running according to its original cron schedule. ### Editing Scheduled Agents [Section titled “Editing Scheduled Agents”](#editing-scheduled-agents) You can modify an existing schedule using `oz schedule update`. You can update one or more properties at a time, including: * The schedule name. * The cron schedule. * The prompt used for future runs. * The skill used as the base prompt. * The environment used for execution. * The model, MCP, and host configuration used for future runs. The **Agent** setting can’t be changed with this command. Change it from the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app. #### Command [Section titled “Command”](#command) ```bash oz schedule update SCHEDULE_ID \ [--name=NAME] \ [--cron=SCHEDULE] \ [--prompt=PROMPT] \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--remove-skill] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--remove-mcp=SERVER_NAME] \ [--model=MODEL_ID] ``` **Additional update flags:** * `--skill ` — update the skill used as the base prompt. * `--remove-skill` — remove the skill from this scheduled agent. * `--host ` — update the execution host. * `--mcp ` — add MCP servers to this schedule. * `--remove-mcp ` — remove an MCP server by name. * `--remove-environment` — remove the environment from this schedule. #### Examples [Section titled “Examples”](#examples) Change when a scheduled agent runs, leaving everything else unchanged: ```bash oz schedule update abc123 --cron "0 9 */4 * *" ``` Update the environment used for future runs: ```bash oz schedule update abc123 --environment=jkl789 ``` Changes apply only to future runs. Past runs and their session history remain unchanged. ### Deleting a Scheduled Agent [Section titled “Deleting a Scheduled Agent”](#deleting-a-scheduled-agent) To permanently remove a schedule, use: ```bash oz schedule delete SCHEDULE_ID ``` **Example** ```bash oz schedule delete abc123 ``` Deleting a schedule immediately stops all future runs. Previous runs and their session history remain accessible for inspection and review. *** ### Execution model and behavior [Section titled “Execution model and behavior”](#execution-model-and-behavior) Each scheduled run behaves like a standard cloud agent run, with a few important guarantees: * Every run starts a fresh session. * No state is carried over between runs unless your environment explicitly persists data. * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility [Section titled “Permissions and responsibility”](#permissions-and-responsibility) Scheduled Agents are created and managed by authorized users on a Warp team. By creating a Scheduled Agent, you are responsible for: * The cron schedule and how often the agent runs. * The instructions provided in the prompt. * The environment and integrations the agent has access to. * The credits consumed by scheduled executions. Carefully review prompts and schedules before deploying them broadly, especially for agents that can modify production code or infrastructure. ### When to use Scheduled Agents vs triggers [Section titled “When to use Scheduled Agents vs triggers”](#when-to-use-scheduled-agents-vs-triggers) Scheduled Agents are best when work should happen on a predictable cadence. If you want an agent to run in response to an event, such as a Slack mention, PR update, or issue change, use [integrations](/platform/integrations/) to trigger cloud agents instead. Many teams use both together: [triggers](/platform/triggers/) for reactive workflows, and Scheduled Agents for proactive maintenance. ## Related pages [Section titled “Related pages”](#related-pages) * [Environments](/platform/environments/) — configure the repo, image, and setup commands scheduled runs execute with * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) — inspect transcripts, logs, and outputs from each scheduled run * [Skills as Agents](/platform/skills-as-agents/) — run a reusable skill definition on a schedule * [Run unattended agents](/guides/agent-workflows/how-to-run-unattended-agents/) — compare schedules with Slack, Linear, GitHub Actions, CLI, and API triggers # Scheduled Agents quickstart Canonical page: [/platform/triggers/scheduled-agents-quickstart/](https://docs.warp.dev/platform/triggers/scheduled-agents-quickstart/) > Schedule a cloud agent to run recurring tasks automatically — issue triage, dependency checks, code cleanup, and more. Scheduled agents are cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You’ll use a prebundled skill and the Oz web app; no CLI or custom code required. Watch this short demo of creating and testing a scheduled agent:  *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Warp account on an eligible plan** - Build, Max, or Business, with credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/). * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have one, follow the [Cloud Agents Quickstart](/platform/quickstart/) to create one first. *** ## 1. Set up a scheduled agent [Section titled “1. Set up a scheduled agent”](#1-set-up-a-scheduled-agent) 1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click **New schedule**. 2. Enter a schedule name, e.g. `Weekly bug report triage`. 3. Expand **General**, then under **Agent**, choose the identity that will run the schedule. **Quick run** is the default and runs every execution as you. See [Run identity and pull request authorship](#run-identity-and-pull-request-authorship) before you decide. 4. Under **Skills**, select **github-bug-report-triage**. 5. Choose your environment. 6. Under **Frequency**, choose a preset or enter a custom cron expression (e.g., `0 9 * * 1` for every Monday at 9 AM). 7. Click **Create schedule**. **Breaking it down:** The schedule lives in the Automation Platform‘s cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and reviewable in the [Oz web app](/platform/oz-web-app/). ### Run identity and pull request authorship [Section titled “Run identity and pull request authorship”](#run-identity-and-pull-request-authorship) The **Agent** setting controls the identity behind every run, which determines how the agent authenticates to GitHub: * **Quick run** (default) - Runs execute as the user who created the schedule, using that person’s GitHub credentials. Pull requests the agent opens are authored by that person. * **Cloud agent** - Runs execute as the [cloud agent](/platform/agents/) you select. With [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, the agent authenticates as the **Warp Factories** GitHub App, so pull requests are authored by the app instead of an individual. Choose a cloud agent for any schedule that opens pull requests. Pull requests authored by the app are clearly attributable to automation, and anyone on the team can review and approve them — including the person who created the schedule, who cannot approve a pull request authored by their own account. Caution The Oz CLI has no **Agent** flag, so a schedule created with `oz schedule create` always runs as its creator. To run it as a cloud agent, set **Agent** on the schedule in the Oz web app after creating it. *** ## 2. Watch your first run [Section titled “2. Watch your first run”](#2-watch-your-first-run) To verify your setup without waiting for the schedule to fire, trigger a test run now: 1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click the schedule you just created. 2. Click ⋮ and select **Run now**, then click **Run** to confirm. Your test run will appear under **All** on the [Runs page](https://oz.warp.dev/runs). Once the schedule fires on its cron, those runs will appear under **Recurring**. Runs are also accessible from the conversation panel view in the Warp app and on mobile via the Oz web app. *** ## Next steps [Section titled “Next steps”](#next-steps) * **Choose the right unattended trigger** - Compare schedules, Slack, Linear, GitHub Actions, CLI, and API workflows in [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). * **Trigger agents from your tools** - Connect the Automation Platform to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/platform/integrations/quickstart/). * **Manage and refine your schedule** - Change the frequency, swap skills, or pause and resume the schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/) for the full reference. * **Share with your team** - Schedules and environments are shared across your Warp team, so everyone benefits automatically. # Cloud agent session sharing Canonical page: [/platform/viewing-cloud-agent-runs/](https://docs.warp.dev/platform/viewing-cloud-agent-runs/) > Open, inspect, and steer remote cloud agent runs in real time from Warp or the web. Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/platform/integrations/) like Slack, Linear, GitHub Actions, or the [Oz CLI](/reference/cli/), you can view its full session, follow along in real time, ask follow-up questions, and even “fork” the work into your local Warp environment. Use cloud agent session sharing when you need to inspect a cloud agent run, debug a failed automation, or give teammates a shared record of what the agent did. The shared session is the review surface for the run: it shows the prompt, plan, commands, logs, outputs, and follow-up messages where available. [Cloud agent run sharing walkthrough](https://www.loom.com/embed/edd662da8de345ae979c4d39eb19c513) This makes cloud agent runs observable, steerable, and collaborative — even if they weren’t initiated from your machine. *** ### What it enables [Section titled “What it enables”](#what-it-enables) With cloud agent session sharing, you can view the full remote session for a cloud agent run and: * See every command the agent executed in the virtual environment * Inspect context, logs, and outputs directly in Warp or the web viewer * Review the prompt, plan, task list, and decisions that led to the result * Ask follow-up questions or give additional instructions after the task completes * Bring the conversation into your local Warp session with Fork to local * Continue working on remote-generated code locally * Share links so teammates can view or collaborate on the session Everything is accessible whether or not Warp is installed on the viewer’s machine. ## How it works [Section titled “How it works”](#how-it-works) #### 1. Open a remote cloud agent run [Section titled “1. Open a remote cloud agent run”](#1-open-a-remote-cloud-agent-run) When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/reference/cli/) trigger — Warp attaches a shareable link to the run. * From [Slack](/platform/integrations/slack/), click **View Agent** in the agent response to open the session. * From [Linear](/platform/integrations/linear/), click the ↗ **Warp** button (“Open in Warp”) on the ticket to open the session. You can also open the session directly in your browser without installing Warp. Here, you’ll see the complete agent session running on a cloud VM, including all steps, logs, and context. #### 2. Inspect the session like it’s your own [Section titled “2. Inspect the session like it’s your own”](#2-inspect-the-session-like-its-your-own) Once the session loads, you can: * Scroll through the cloud agent’s actions * See the prompt, plan, and decisions it made * Review commands, logs, terminal output, and generated artifacts * Review the code or config changes it produced * Understand what environment it executed in * Copy the session link into a PR, issue, incident review, or team thread when teammates need the same execution context You’re viewing a remote VM, but the UI behaves like a local Warp session. #### 3. Keep chatting with the remote agent [Section titled “3. Keep chatting with the remote agent”](#3-keep-chatting-with-the-remote-agent) Even if the cloud agent has completed its task, you can still ask follow-up questions or request more work. Warp sends your message back to the remote VM and continues the conversation. Examples: * “Can you explain which flag you changed?” * “Give me a summary of what you modified.” * “Show me the reasoning behind your last step.” This works as long as the remote environment is still active. #### 4. Handle inactive or shut-down sessions [Section titled “4. Handle inactive or shut-down sessions”](#4-handle-inactive-or-shut-down-sessions) Cloud agent environments automatically shut down after a period of inactivity. When that happens, you’ll see a notice that the virtual machine has been stopped. If you still want to continue the conversation or work on the code, you can click **Fork to local**. #### 5. Fork the session to your local Warp [Section titled “5. Fork the session to your local Warp”](#5-fork-the-session-to-your-local-warp) Forking is the cloud-to-local direction of [Handoff between local and cloud agents](/platform/handoff/) — see that page for the other directions (local-to-cloud and cloud-to-cloud). Forking brings the cloud agent conversation into your local machine, so you can pick up where the agent left off. Once forked: * The session appears as a normal conversation in your local Warp * You can keep prompting the agent using all your local tools * You can continue inspecting or modifying the generated code * The agent responds using your local environment instead of the remote VM **Note:** If the cloud agent created a new git branch or repository in the remote VM, you’ll need to clone that branch locally first so the agent can keep working on the same code. Warp will streamline this workflow in a future release. ### Viewing sessions across devices [Section titled “Viewing sessions across devices”](#viewing-sessions-across-devices) Cloud agent sessions can be viewed from: * The Warp app * A browser via the web viewer * Remote teammates using the shared link * Local Warp sessions after forking You get consistent visibility into the work regardless of where you open it. ### Related pages [Section titled “Related pages”](#related-pages) * [Managing cloud agents](/platform/managing-cloud-agents/) — Find cloud agent runs by source, status, trigger, or owner. * [Multi-agent orchestration](/platform/orchestration/) — Inspect parent and child cloud runs that fan work out in parallel. * [Remote Control](/agents/cli-agents/remote-control/) — Publish a third-party CLI agent session to monitor and steer it from another device. * [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) — Share a run link with a PR so reviewers can inspect the agent’s execution context. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Share local Warp agent or third-party CLI agent sessions. # Warp-hosted agents Canonical page: [/platform/warp-hosting/](https://docs.warp.dev/platform/warp-hosting/) > Run cloud agents on Warp's infrastructure. Warp handles scaling, isolation, and performance for agent execution. Warp’s managed infrastructure lets your team run cloud agent workloads in fast, secure sandboxes. Use Warp-hosted agents to quickly get started with the Automation Platform, without needing to configure compute resources or maintain services. ## Sandbox environment [Section titled “Sandbox environment”](#sandbox-environment) All Warp-hosted agents run in fully-isolated sandboxes. Warp uses a mix of infrastructure providers to ensure reliable sandbox startup. ### OS and architecture [Section titled “OS and architecture”](#os-and-architecture) Warp-hosted agents use the container image specified in your [environment](/platform/environments/). They are compatible with any Linux x86-64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`. ### Resources [Section titled “Resources”](#resources) The resources available to Warp-hosted agents depend on your [plan](https://www.warp.dev/pricing) - see the latest details there. On [Enterprise](/enterprise/) plans, resources are configurable up to 32 vCPUs and 64 GiB of memory. If additional resources are required, reach out to Warp support about custom provisioning. ### Concurrency [Section titled “Concurrency”](#concurrency) To fairly allocate resources across all Warp users, concurrency of Warp-hosted agents is limited on a per-team basis. If an agent is started while at your concurrency limit, it is automatically queued and will start as soon as another agent completes. ### Networking [Section titled “Networking”](#networking) Warp’s hosted agents have network egress enabled by default. Outgoing requests may come from the following IP addresses: * `64.6.38.192/26` * `64.6.39.192/26` * `104.128.70.192/26` * `104.128.71.192/26` * `216.176.224.192/26` * `185.212.186.0/24` * `50.31.178.128/26` * `50.31.146.192/26` * `75.102.37.208/28` * `44.253.165.189/32` * `16.145.188.113/32` * `16.145.133.251/32` *** ## Related pages [Section titled “Related pages”](#related-pages) * [Automation Platform](/platform/overview/) - Learn how Warp-hosted agents fit into the Automation Platform. * [Self-hosting](/platform/self-hosting/) - Run agents on infrastructure you manage when execution must stay inside your network.