Do I have to use Warp? Can I do this with the OZ CLI alone?

Yes — everything goes through the oz CLI under the hood. Warp’s value is letting you drive it with natural language and giving you the dashboard alongside the terminal in one window. If you’re comfortable with the raw CLI, you can skip Warp.

How many agents can I run in parallel?

Practically: as many as you can review PRs from. Plan-wise: three to five is the sweet spot for most projects. Past that the merge conflicts and review load outweigh the speed gain.

Why does the agent need a Team Environment for cloud runs?

Team environments have the right networking, secrets, and integration plumbing to run jobs on OZ’s cloud infrastructure. Personal environments are scoped to local sessions only. If a cloud run silently does nothing, environment scope is the first thing to check.

Can multiple cloud agents write to the same branch?

Don’t. Each agent should target its own branch and open its own PR. Letting two agents commit to the same branch concurrently is a merge-conflict factory.

What models are supported?

OZ supports multiple frontier models, and you pick per-skill or per-run. Use stronger models for planning-heavy skills and cheaper models for routine work like linting and test scaffolding.

How is this different from Claude Code sub-agents?

Claude Code sub-agents run locally inside one Claude Code session. OZ agents run on remote cloud machines, can be triggered by external events (GitHub, Slack, Linear), and persist across your laptop’s state. Different scopes, complementary patterns.

Is there a free tier?

Warp itself is free. OZ has free credits to start with and paid tiers beyond that. Costs track tokens and cloud time, so cap your per-agent budgets early in the learning phase.

Warp and OZ: Cloud AI Agents Tutorial

Introduction

Running one AI agent locally is great. Running fifteen at once across cloud machines is a different workflow entirely — and once you’ve tried it, going back to a single terminal feels like coding with one hand. The interesting question isn’t “does the agent work?” anymore; it’s “how do I scale agents to match the work?”

This walkthrough uses Warp, the agentic development environment, and its OZ agent platform to distribute work across multiple cloud agents in parallel — one for the front end, one for the back end, one for testing, and a GitHub Action that fires a review agent on every pull request. By the end, you’ll have a project scaffold, three cloud agents running concurrently, and an automated PR review pipeline.

📚 Table of contents

Why parallel cloud agents change the workflow
What Warp and OZ actually do
Initial setup: sign-in, GitHub MCP, project scaffold
Creating a Team Environment
The spec-first pattern with /init and agents.md
Splitting the work into per-agent plans
Wrapping plans as reusable skills
Running three agents in the cloud, in parallel
Triggering agents from GitHub Actions on every PR
Steering and observing agents mid-run
Common mistakes
Pro tips
Best practices
Frequently asked questions

⚡ Why parallel cloud agents change the workflow

A single local agent is sequential. You hand it a task, it works, you wait. The cycle scales linearly with token speed and your patience. Parallel cloud agents flip that — three independent contexts working at the same time on different parts of the same project, none of them blocking you. While the front-end agent scaffolds components, the back-end agent designs schemas, and the testing agent writes specs. By the time you check in, three PRs are sitting in your repo.

Single local agent

One context, one focus
Tasks queue up sequentially
Your laptop = the runtime; close it and progress stops
Hard to scale beyond what one terminal can hold

Parallel cloud agents

Many contexts, focused per agent
Real parallelism — minutes, not hours
Cloud-hosted; you can close the laptop or get on a train
Scales by adding skills and environments

🧰 What Warp and OZ actually do

Warp is a terminal-first agentic development environment. It looks like a terminal because most of the work in a complex project happens in a terminal — Docker commands, servers, test runners, deploys. Warp’s twist is that you can interleave natural-language prompts with real shell commands in the same buffer, and it auto-detects which is which.

OZ is Warp’s agent platform. It lets you spin up cloud-hosted agent runs, organise them into reusable skills, scope them to environments (Docker image + GitHub repos), and trigger them from GitHub, Slack, Linear, or a scheduler. Everything you can do in the OZ dashboard you can also do through the oz CLI inside Warp itself, so you can stay in the terminal end-to-end.

🛠️ Initial setup

Download Warp, create an account, and sign in.
In a new terminal tab, run oz login to authenticate the agent platform.
Open Settings → MCP Servers. Toggle GitHub on and authenticate. This is what gives agents the ability to create repos, open pull requests, and check status.
Tell Warp to create a fresh working directory: “Make a new folder on my desktop called multi-agent-demo and open it.” Warp runs the command, switches into the directory, and you’re ready.

📦 Create a Team Environment

Environments are the sandbox cloud agents run inside — a Docker image plus one or more GitHub repositories the agent can read and write. Two practical notes:

Pick a Docker image that already has the toolchain your project needs. Saves the agent five minutes of apt install per run.
Mark the environment as a Team Environment. Personal environments can’t run cloud agents — this is the single most common “why isn’t this working” mistake.

The fastest way to create one: tell Warp directly. “Create a new team environment for this GitHub repository so I can run OZ agents in the cloud.” Warp drives the OZ CLI for you.

📐 Spec-first, then /init

Before you touch a cloud agent, write the spec. The reason: cloud agents work without you holding their hand, so the quality of their work tracks directly to the quality of the brief.

Drop a long-form description of the app into Warp: features, tech stack, data model, key user flows. Save it as SPEC.md.
Ask Warp to scaffold a minimal front-end and back-end folder structure based on the spec — just the directories, nothing else yet.
Create a GitHub repo and push the scaffold so the environment has something to clone.
Run /init. Warp indexes the codebase and generates agents.md — a per-project rule file every cloud agent will read on every run. Decline any prompt to also make a new environment if you already created one.

From this point, every agent that runs will see SPEC.md, the scaffold, and agents.md automatically. That’s the context floor — below it, agents flail; above it, they ship.

📝 Split the work into per-agent plans

Three agents need three briefs. Have Warp generate them:

“Create three markdown files in a plans/ directory. frontend.md lists the tasks needed to build the front end. backend.md lists the tasks for the back end. testing.md lists the testing tasks. Base them on SPEC.md.”

Each file should be specific enough that another agent could pick it up cold and produce useful work. Good plan files are short prose followed by a checklist — not vague intent. The exact contents matter less than the discipline of writing them down before the agents start.

♻️ Wrap each plan as a reusable skill

A skill is OZ’s unit of repeatable work. Wrap each plan as a skill and you can call it from anywhere — the dashboard, the CLI, a scheduled job, a GitHub trigger.

Tell Warp: “Set up three skills, one for each plan in plans/.”
Make sure they land in .agents/skills/ — that’s the path OZ scans automatically when running cloud agents.
Each skill should reference its plan file so the agent loads it as part of the prompt.

Once skills exist, you can re-run them later without rewriting the brief, schedule them on a cron, or chain them — back-end first, then testing once back-end completes.

☁️ Run three agents in the cloud, in parallel

The big moment. One natural-language prompt is enough:

“Run three cloud agents in parallel — one for the front end, one for the back end, one for testing — using the skills I just created, in the team environment I set up for this repo. Each agent opens its own pull request.”

Under the hood Warp invokes oz agent run --cloud three times with the right skill, environment, and model flags. You can do this manually if you prefer the CLI; the natural-language version is just faster.

Three things happen quickly:

Three runs appear in the OZ dashboard with live status.
Three branches are created on the repo, each tied to its agent.
Pull requests start opening as each agent finishes its plan.

Your laptop fans don’t spin. The work happens elsewhere. You review PRs when they’re ready, not when one process gets unblocked.

🪝 Trigger agents from GitHub Actions on every PR

The next pattern worth wiring up: have a review agent fire automatically on every pull request. OZ ships a pre-built GitHub Action exactly for this.

In the OZ dashboard, open Integrations → GitHub Action. Copy the workflow YAML.
Tell Warp to add a .github/workflows/ folder, drop the YAML in as review.yml, and push.
Create a new OZ API key (Team scope) at Settings → Platform → API Keys.
In your GitHub repo, go to Settings → Secrets and variables → Actions. Add a new repository secret named WARP_API_KEY with the key value.
Open a test PR. The Action fires, the review agent comments on the diff, and the green check arrives a few minutes later.

From that point on, every PR — whether opened by you, a teammate, or one of your own cloud agents — gets a structured review before merge. The same pattern works for Slack triggers (review a thread), Linear (act on a ticket), or any custom integration via the OZ API.

🎮 Steering and observing agents mid-run

Cloud agents aren’t fire-and-forget. You can step into any running session to redirect or halt it.

From the OZ dashboard: open the run, “View Session”, choose “Open in Warp.” Warp opens a remote terminal SSH’d into the agent’s machine.
From inside Warp: press Ctrl + Shift + Enter on a streaming agent to take over and inject instructions live.
From the CLI: oz agent list shows active runs; pick one and attach.
To stop: Escape interrupts, or click Stop in the dashboard. Stop early — you never lose tokens by ending a clearly off-track run.

A small habit that pays off: peek at one or two of the running agents in the first minute, just to confirm they read the plan correctly. Two minutes of supervision early beats two hours of rework.

❌ Common mistakes

Creating a Personal Environment by accident — cloud runs will silently refuse to start.
Skipping /init and agents.md. Agents work without context and produce generic results.
Writing one mega-plan instead of three focused ones. Parallel agents need parallel briefs.
Forgetting to set the WARP_API_KEY secret on GitHub — the Action fails on its first run.
Running agents without pushing the latest scaffold to GitHub first. The clone is empty.
Spawning so many parallel agents that you can’t review the PRs. Three is plenty; ten is theatre.
Not capping per-agent token budgets — runaway runs are how the bill surprises you.

💡 Pro tips

Mix local and cloud agents in the same session. Local for fast iteration, cloud for long runs.
Schedule a nightly “cleanup” agent that runs tests, lints, and opens fix PRs.
For Linear/Slack triggers, scope agents to specific labels or channels to avoid noise.
Keep SPEC.md and agents.md in git. The agents’ context is your context.
Version your .agents/skills/ folder — skills evolve and you’ll want history.
Use Warp’s built-in code-review pane (Cmd/Ctrl + R) before merging an agent PR. A 30-second skim catches most issues.

✅ Best practices

Spec first, code second. Every agent run is downstream of the brief quality.
One agent, one concern. Front-end, back-end, testing, review — don’t blend them.
Always run in a Team Environment for cloud runs.
Bake reusable work into skills, not one-off prompts.
Trigger from real signals — PR opened, ticket created, Slack message — not arbitrary crons unless there’s a reason.
Review every PR before merge, even if the agent says it’s done.

Conclusion

The shift from local single-agent coding to parallel cloud agents is the same kind of step function as the shift from solo developer to team. The tools that make it cheap — Warp’s natural-language CLI, OZ’s skills and environments, GitHub Action triggers — have landed in the last few months. Set them up once, and a single PR can fire off three agents, receive three PRs back, and get an automated review on each.

Start small. Spec a real project, write three plans, run three agents, take the train. The workflow does the rest.

Run AI Agents in the Cloud with Warp and OZ