Cloud agents overview

Oz Cloud Agents are cloud-connected, background agents that run on the Oz Platform.

New to cloud agents? Start with the Cloud agents quickstart to run your first cloud agent in ~10 minutes.

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, 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, and what it did.
• You need more parallelism than local execution typically allows.
  • For example, running many agent tasks concurrently in the cloud, sharding a repo-wide task into multiple runs, or fanning out the same task across multiple targets.
• You want agents to operate continuously as part of engineering infrastructure.
  • This includes scheduled maintenance tasks and integration-driven automation.

---

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

Note

If you are evaluating whether something should be a cloud agent, a good test is whether you can define:
(1) what triggers it, (2) what context it needs, and (3) how the team will inspect or validate the output.

How cloud agents work

Cloud agents run on the Oz Platform, 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, with whatever 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 pages.

For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a managed worker daemon that lets Oz 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 for details.

What you get by default

Because cloud agents run on the Oz Platform, each run is tracked and produces a persistent record that can be observed, shared, and audited (even if execution happens outside the Warp app).

Codebase Context

Cloud agent runs automatically benefit from 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 for details.

Observability and steerability

Cloud agent tasks are designed to be inspectable by the team:

• Agent Session Sharing lets authorized teammates attach to a running task to monitor progress and, where supported, steer the agent while it runs.
• Each run produces a session transcript and task metadata, which provides a record of what the agent did.
• A management experience surfaces task status and history.

Centralized configuration

Cloud agent workflows often rely on shared configuration such as MCP servers, rules, saved prompts, environment variables, and 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.

API access to tasks

The Oz Platform exposes task visibility via the Oz API and SDKs, 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

Cloud agents do not require the Warp desktop app. Teams can deploy and operate them through the Oz Platform using:

• Oz CLI — run agents from scripts, CI, or the terminal
• Oz web app — visual interface for managing runs, schedules, environments, and integrations (works on mobile)
• Agent Session Sharing — attach to running tasks to monitor or steer
• Agent Management UX — view agent activity and run history
• APIs and SDKs — 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

Cloud agents and integrations run on the Oz Platform control plane, and usage is billed using credits.

Note

Bring Your Own Key (BYOK) is not supported for cloud agent runs. BYOK keys are stored locally on your device and are not accessible to cloud-hosted agents. All cloud agent runs consume Warp credits.

For Cloud Agents via CLI/API

Individual users can run cloud agents without being on a team. Requirements:

• You need at least 20 credits (any type: normal Warp credits, Cloud Agent Credits, or Build plan credits)
• Cloud agents run on Warp-hosted infrastructure
• Self-hosted agents require a team subscription

For Integrations (Slack/Linear)

Integrations require you to be part of a Warp team and additional requirements:

• Plan requirements
  • Supported plans: Build, Max, Business
  • Not supported: Pro, Turbo, Lightspeed, legacy Business
  • Your plan must support Add-on Credits.
• Credit requirements
  • Your team must have at least 20 credits available (any type of Warp credits work) to run cloud agents and integrations.
  • Usage is billed based on credit type and team configuration.
  • Normal credits, Cloud Agent Credits, and Add-on Credits all work.

For more details, see Access, Billing, and Identity Permissions.

Caution

If your credit balance reaches zero, cloud agent runs will not be able to execute until credits are replenished.

---

Learn more

• Cloud agents quickstart — run your first cloud agent with an environment in ~10 minutes.
• Oz Platform — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more.
• Skills as Agents — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule.
• Oz CLI — shows how to run Oz agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands.
• Environments — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks.
• Oz API and SDK — documents the REST API for creating, querying, and monitoring agent tasks programmatically.
• Agent Secrets — covers how to store, scope, and inject credentials into agent runs safely.
• MCP Servers — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs.
• Deployment Patterns (beta) — compares common ways to deploy cloud agents and when to use each.
• Access, Billing, and Identity Permissions — explains individual and team-level requirements, credit billing behavior, and the permission model for who can run, view, and steer cloud agent tasks.