> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
oz environment list
```

### Create an environment

```bash theme={null}
oz environment create \
  --name "my-app" \
  --repo owner/my-app \
  --docker-image warpdev/node-20 \
  --setup-command "npm install" \
  --setup-command "npm run build"
```

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

**`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

```bash theme={null}
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.

```bash theme={null}
# 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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
oz agent run-cloud \
  --prompt "Refactor the database connection pool in src/db/pool.ts" \
  --environment <environment_id>
```

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

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

```bash theme={null}
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:

```bash theme={null}
oz environment create \
  --name "shared-env" \
  --repo owner/repo \
  --scope org
```