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