Run a software factory in the cloud

The GitHub Actions approach in Set up your software factory gets the four-agent loop working. This guide covers the Oz-native production setup for teams running the factory at scale: dedicated cloud environments, team-scoped secrets, native triggers beyond GitHub Actions, and full run auditability.

This guide covers four things: environments, secrets and permissions, triggers, and observability.

Prerequisites

• A working software factory loop (set one up)
• A Warp account (sign in at oz.warp.dev or access Oz from within Warp)

Why cloud agents, not cloud computers

A common approach to cloud-based agents is to spin up a persistent virtual machine — a “cloud computer” — that the agent logs into and uses like a developer’s laptop. Oz uses a different model: each agent run is a short-lived, scoped execution with its own environment and permissions, similar to a cloud function rather than a long-running server.

The practical difference:

• Per-agent permissions — Your triage agent only needs to read issues and post comments. Your implementation agent needs to push branches and open PRs. Each agent gets exactly the permissions it needs, not a single shared credential that everything uses.
• Audit trails — Every cloud agent run is logged separately. You can see exactly what the triage agent did versus what the implementation agent did, when it ran, and what it produced.
• Team visibility — Any teammate can open a run in the Oz web app to inspect the session transcript, steer a stuck agent, or pick up where the agent left off.
• Scale without contention — Multiple triage runs can execute in parallel without fighting over a shared dev box, local git checkouts, or CPU.

See Deployment patterns for a full comparison of Oz-hosted, CLI-based, and self-hosted execution patterns.

1. Set up a cloud environment

An Oz environment is a Docker-based sandbox with your repository, secrets, and any tools the agents need. Create one from the Oz web app or the CLI:

oz environment create \
  --name my-factory \
  --repo YOUR_ORG/YOUR_REPO

For repositories that need language toolchains, databases, or other dependencies, start from a predefined environment in warpdotdev/oz-dev-environments. These are Docker images pre-configured for common stacks. Copy the relevant Dockerfile into your repository and reference it when creating the environment.

See Environments for the full reference.

2. Add secrets and permissions

Each agent role in your factory needs access to different secrets. Add them at the environment level rather than embedding them in prompts:

oz secret create --name GITHUB_TOKEN

The CLI prompts for the value interactively so it never appears in shell history or process arguments. Secrets are scoped to your team, injected into cloud runs at execution time, and never visible in session transcripts.

Grant each agent role only the GitHub permissions it needs:

• Triage agent — Read issues and post comments
• Spec agent — Push branches and open draft PRs
• Implementation agent — Push branches and open PRs
• Reviewer agent — Post review comments on PRs

Use fine-grained personal access tokens or separate GitHub App installations to enforce least privilege per role. See Secrets for management details and GitHub Actions integration for token setup patterns.

3. Configure triggers

With GitHub Actions, your factory already has event-based triggers. Oz also provides first-party integrations that handle triggering without GitHub Actions boilerplate:

• Slack — Teammates can kick off a run by mentioning @warp in a Slack thread. Useful for one-off requests that don’t need the full label workflow. See Slack integration.
• Linear — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See Linear integration.
• Scheduled agents — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See Scheduled agents.
• Oz API and SDK — For custom triggers — webhooks, internal dashboards, other events — use the Oz API and SDK to start runs programmatically.

4. Monitor factory runs

Every cloud agent run in your factory appears in the Oz dashboard with:

• A session transcript showing every action the agent took
• Artifacts: PRs, branches, plans, and reports the agent produced
• Status history: queued, in progress, succeeded, or failed with error details
• A session sharing link any teammate can open to inspect or steer the run

Open runs from oz.warp.dev or from the Agent Management Panel in the Warp app. Include the session link in PR descriptions so reviewers can see exactly how the agent built the change — see Attach agent context to GitHub PRs.

See Viewing cloud agent runs for the full reference.

5. Use multi-agent orchestration for large backlogs

When a sprint starts and you want to process many issues in parallel, Oz can fan out to child agents — one per issue — from a single parent run. The parent coordinates; the children execute in parallel, each with their own environment, prompt, and permissions.

See Multi-agent orchestration for fan-out, sharding, and result aggregation patterns.

Productivity tips

• Start with one agent role in the cloud — Get the triage agent running as a cloud run before moving all four roles. Confirm that the environment, secrets, and permissions work correctly before expanding.
• Add session links to PR descriptions — When the implementation agent opens a PR, include the Oz run link so reviewers get the full context. See Attach agent context to GitHub PRs for a template.
• Monitor credit usage — Cloud agent runs consume credits. Monitor usage in the Oz web app and adjust run scope if needed. See Credits.

Next steps

• What is a software factory? — The conceptual overview of the full loop.
• Build a self-improving agent — Add the outer improvement loop on a schedule.
• Environments — Full reference for cloud agent environments.
• Deployment patterns — Choose the right architecture for your team.
• Self-hosting — Run Oz agent workers on your own infrastructure when code must stay on-premises.