SOP 004: Cloud Agents Setup

Fresh

Field	Value
SOP ID	SOP-004
Version	1.0
Status	Active
Source	docs.warp.dev/agent-platform/cloud-agents

Overview

Oz Cloud Agents are background agents that run on Warp's infrastructure (or your own) for automation at scale. They react to events, run on schedules, and provide full observability.

Prerequisites

• Warp account with active plan (Build, Max, or Business)
• Minimum 20 credits available
• Oz CLI installed and authenticated

WARNING

BYOK (Bring Your Own Key) is not supported for cloud agent runs. All cloud agent runs consume Warp credits.

Procedure

Step 1: Understand Cloud Agent Use Cases

Cloud agents are ideal when you need:

• Event-driven automation - React to crashes, bug reports, Slack messages
• Team observability - Track what ran, when, and what it did
• Parallelism - Run many agent tasks concurrently
• Continuous operation - Scheduled maintenance, integration-driven workflows

Step 2: Run Your First Cloud Agent

# Simple cloud agent run
oz agent run --prompt "Summarize this repo and list top 5 risky areas"

# Cloud agent with environment
oz agent run-cloud \
  --environment SVhg783GBFQHk1OfdPfFU9 \
  --name "Repo summary" \
  --prompt "Summarize this repo and list the top 5 risky areas" \
  --open

Step 3: Configure an Environment

Environments define the runtime context for cloud agents:

• Repository to clone
• Docker image to use
• Startup commands

Configure environments through the Oz web app or via the CLI.

Step 4: Set Up Integrations

Connect cloud agents to external triggers:

Integration	Trigger
Slack	Messages, reactions, commands
Linear	Issue creation, status changes
GitHub Actions	PR events, CI steps
Webhooks	Custom events

Step 5: Create Scheduled Runs

Use the Oz web app to set up recurring agent tasks:

• Dependency updates
• Dead code removal
• Security scanning
• Code quality reports

Step 6: Monitor Agent Activity

Oz Web App: View runs, sessions, and agent history at oz.warp.dev

Session Sharing: Attach to running tasks to monitor or steer

# Share a session with teammates
oz agent run --share team:view --prompt "fix the bug"

API Access:

# Query running tasks via API
# GET /agent/runs with name filter

Cloud Agent Run Lifecycle

Each run produces:

• Session transcript - Full record of agent actions
• Task metadata - Status, runtime, trigger info
• Persistent record - Auditable and shareable

Naming Runs

Use --name for tracking and filtering:

oz agent run-cloud \
  --environment SVhg783GBFQHk1OfdPfFU9 \
  --name "nightly-dependency-check" \
  --prompt "Check for outdated dependencies and open a PR"

INFO

Skill-based runs are automatically named after the skill. Custom runs should use consistent --name values.

Verification Checklist

• [ ] Cloud agent runs successfully with oz agent run-cloud
• [ ] Environment configured with correct repo and image
• [ ] Agent profile allows needed commands and MCP servers
• [ ] Session transcript available after run completes
• [ ] Team members can view shared sessions

Troubleshooting

Issue	Solution
"Insufficient credits"	Purchase add-on credits or upgrade plan
Cloud run fails	Verify environment config, check profile permissions
Can't see session	Ensure --share flag was used, check team membership
Integration not triggering	Verify integration is connected in Oz web app

See Also

• SOP 005: MCP Servers
• Workflow 002: Cloud Agent Deployment
• Workflow 003: Team Collaboration