Cloud environments for Warp agents

Create isolated cloud environments that give Oz agents a consistent, pre-configured workspace — with your repos cloned and dependencies installed.

A cloud environment is an isolated execution context that Oz provisions for each agent run. It defines which GitHub repositories to clone, which Docker base image to use, and which setup commands to run after cloning. By creating a reusable environment, you ensure that every agent run — whether triggered manually or on a schedule — starts from the same predictable baseline.

Managing environments

All environment commands are available under oz environment (alias: oz e).

List environments

oz environment list

Create an environment

oz environment create \
  --name "my-app" \
  --repo owner/my-app \
  --docker-image warpdev/node-20 \
  --setup-command "npm install" \
  --setup-command "npm run build"

Run oz environment image list to see the available Warp dev base images from Docker Hub. If you omit --docker-image, Oz will prompt you to choose from the list interactively.

oz environment create flags:

Flag	Short	Description
--name	-n	Name for the environment (required)
--description	—	Optional description, up to 240 characters
--docker-image	-d	Docker image to use as the base. Run oz environment image list to see options
--repo	-r	Git repo in owner/repo format to clone. Repeatable
--setup-command	-c	Shell command to run after cloning. Repeatable, runs in order

Get environment details

oz environment get <id>

Update an environment

You can add repos, swap the Docker image, change the description, or append new setup commands without recreating the environment.

# Add a second repo and a new setup command
oz environment update <id> \
  --repo owner/shared-lib \
  --setup-command "pip install -r requirements.txt"

# Remove a repo
oz environment update <id> --remove-repo owner/old-repo

# Remove a setup command
oz environment update <id> --remove-setup-command "npm run old-script"

# Clear the description
oz environment update <id> --remove-description

oz environment update flags:

Flag	Short	Description
--name	-n	New name for the environment
--description	—	New description (up to 240 characters)
--remove-description	—	Remove the existing description
--docker-image	-d	New Docker base image
--repo	-r	Git repo to add. Repeatable
--setup-command	-c	Setup command to append. Repeatable
--remove-repo	—	Git repo to remove. Repeatable
--remove-setup-command	—	Setup command to remove. Repeatable
--force	—	Update without checking for integration usage

Delete an environment

oz environment delete <id>

# Skip the integration-usage check
oz environment delete <id> --force

Connecting an environment to a GitHub repository

The --repo flag accepts the owner/repo format and can be repeated to include multiple repositories. Oz clones each repo into the environment before running setup commands.

oz environment create \
  --name "full-stack" \
  --repo acme/frontend \
  --repo acme/backend \
  --repo acme/shared-types \
  --setup-command "cd frontend && npm install" \
  --setup-command "cd backend && pip install -r requirements.txt"

Base images

Warp publishes a set of curated dev base images. List them with:

oz environment image list

You can also use any publicly accessible Docker image with the --docker-image flag.

Using an environment for an agent run

Pass --environment <id> (short: -e) when running a cloud agent to specify which environment to use.

oz agent run-cloud \
  --prompt "Refactor the database connection pool in src/db/pool.ts" \
  --environment <environment_id>

When using oz schedule create for recurring agents, pass the same --environment flag to pin every scheduled run to the same environment.

If you want to run an agent without any environment (not recommended for most use cases), pass --no-environment instead:

oz agent run-cloud \
  --prompt "List the files in the current directory" \
  --no-environment

Scoping environments

By default, environments are created in your personal scope. To create an environment that is shared across a team or organization, pass the appropriate scope flag when creating or updating:

oz environment create \
  --name "shared-env" \
  --repo owner/repo \
  --scope org