Skip to main content
Cloud environments define the isolated containers that Warp agents run in when you use oz agent run-cloud. An environment pins a Docker base image, specifies which Git repositories to clone, and configures setup commands that run after the repos are cloned. Reusing the same environment across many agent runs keeps your agents consistent and avoids repeating setup work.

​
Synopsis

oz environment <subcommand> [flags]
Alias: oz e

​
Subcommands

SubcommandDescription
listList all cloud environments
get <id>Get details of a specific environment
createCreate a new cloud environment
update <id>Update an existing environment
delete <id>Delete a cloud environment
image listList available Warp dev base images

​
oz environment list

Lists all cloud environments available to your account. 
oz environment list

​
Examples

oz environment list
oz environment list --output-format json

​
oz environment get

Retrieves details of a specific environment by its ID. 
oz environment get <id>

​
Arguments

ArgumentDescription
idID of the environment to retrieve

​
Examples

oz environment get env_abc123

​
oz environment create

Creates a new cloud environment. 
oz environment create --name <name> [flags]

​
Flags

​
--name
string
required
Name of the environment.Short form: -n
​
--description
string
Description of the environment. Maximum 240 characters.
​
--docker-image
string
Docker image to use as the base for this environment. Run oz environment image list to see suggested Warp dev images. If not specified, you will be prompted to select from available images interactively.Short form: -d
​
--repo
string
Git repository to clone into the environment, in owner/repo format. Repeatable — specify multiple times to clone multiple repositories.Short form: -r
​
--setup-command
string
Command to run after the repositories are cloned. Repeatable — specify multiple times to add multiple setup steps.Short form: -c

​
Examples

# Create a minimal environment
oz environment create --name "my-app"

# Create an environment with a specific image and repo
oz environment create \
  --name "my-app" \
  --docker-image warp/dev:node20 \
  --repo owner/my-app

# Create an environment with setup commands
oz environment create \
  --name "my-app" \
  --docker-image warp/dev:node20 \
  --repo owner/my-app \
  --setup-command "npm install" \
  --setup-command "npm run build"

# Create with a description
oz environment create \
  --name "api-server" \
  --description "Node.js API server with PostgreSQL" \
  --repo owner/api-server \
  --setup-command "npm install"

​
oz environment update

Updates an existing cloud environment. Only the fields you specify are changed; everything else is left as-is. 
oz environment update <id> [flags]

​
Arguments

ArgumentDescription
idID of the environment to update

​
Flags

​
--name
string
New name for the environment.Short form: -n
​
--description
string
New description (max 240 characters). Cannot be combined with --remove-description.
​
--remove-description
boolean
Remove the description from the environment. Cannot be combined with --description.
​
--docker-image
string
New Docker base image.Short form: -d
​
--repo
string
Git repository to add, in owner/repo format. Repeatable.Short form: -r
​
--remove-repo
string
Git repository to remove, in owner/repo format. Repeatable.
​
--setup-command
string
Setup command to append to the list. Repeatable.Short form: -c
​
--remove-setup-command
string
Setup command to remove from the list. Repeatable.
​
--force
boolean
Force the update without checking for integration usage.

​
Examples

# Rename an environment
oz environment update env_abc123 --name "new-name"

# Add a repository to an existing environment
oz environment update env_abc123 --repo owner/another-repo

# Replace the Docker image
oz environment update env_abc123 --docker-image warp/dev:python311

# Remove a setup command
oz environment update env_abc123 --remove-setup-command "npm run build"

# Remove a repository
oz environment update env_abc123 --remove-repo owner/old-repo

​
oz environment delete

Deletes a cloud environment. 
oz environment delete <id> [flags]

​
Arguments

ArgumentDescription
idID of the environment to delete

​
Flags

​
--force
boolean
Delete without checking for integration usage.

​
Examples

oz environment delete env_abc123
oz environment delete env_abc123 --force

​
oz environment image list

Lists available Warp dev base images from Docker Hub. Use the image names returned here as the value for --docker-image when creating or updating an environment. 
oz environment image list

​
Examples

oz environment image list
oz environment image list --output-format json

Build docs developers (and LLMs) love

Get started for freeTalk to us