> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# guild runtime-environment

> Create, modify, and test runtime environments.

Manage runtime environments. A runtime environment pairs a base container image with an optional setup script. Like `container-image`, every command identifies its target with `--owner` and `--name` flags rather than a positional argument.

```bash theme={null}
guild runtime-environment list                                      # List environments
guild runtime-environment get --owner acme --name build             # Show one, with its setup script
guild runtime-environment create --owner acme --name build \
  --image acme~base --setup @setup.sh                               # Create from an image and a script
guild runtime-environment modify --owner acme --name build --clear-setup
guild runtime-environment test --owner acme --name build            # Provision a throwaway container
```

## list

| Option              | Description                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--owner <name>`    | Owner account name or ID. Without this flag, lists your configured default owner, then falls back to your personal account. |
| `--limit <number>`  | Number of results to return (default: 20).                                                                                  |
| `--offset <number>` | Offset for pagination (default: 0).                                                                                         |

## get

Shows an environment, including its setup script. `--owner` and `--name` are both required.

## create

`--owner` and `--name` are required. Supply the base image with `--image`, or omit it in a terminal to pick from a searchable list.

| Option                 | Description                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `--owner <name>`       | Owner account name or ID.                                                                       |
| `--name <name>`        | Environment name. Lowercase letters, digits, hyphens, dots, and underscores; 1–100 characters.  |
| `--image <id_or_name>` | Base container image, as an ID or a full name such as `guildai~experimental-coding`.            |
| `-i, --interactive`    | Pick the base image from a searchable list of the images you own plus all public images.        |
| `--setup <script>`     | Setup script, given inline or as `@path` to read from a file — for example `--setup @setup.sh`. |

## modify

`--owner` and `--name` identify the environment; pass at least one of the remaining options.

| Option                 | Description                                                            |
| ---------------------- | ---------------------------------------------------------------------- |
| `--image <id_or_name>` | Set a new base container image.                                        |
| `-i, --interactive`    | Pick the new base image from the searchable list.                      |
| `--setup <script>`     | Replace the setup script, inline or as `@path`.                        |
| `--clear-setup`        | Remove the setup script.                                               |
| `--public`             | Make the environment public. **One-way door** — this cannot be undone. |
| `--yes`                | Skip the confirmation prompt for `--public`.                           |

## test

Provisions a throwaway container from the environment, streams the setup script's logs, and reports whether the container came up. Use it to check a setup script before an agent depends on it.

| Option           | Description                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `--owner <name>` | Owner account name or ID. Defaults to your configured default owner, falling back to your personal account. |
| `--name <name>`  | Environment name. Required.                                                                                 |

<Note>
  `--image` and `-i, --interactive` cannot be combined. `--interactive` needs a terminal and is rejected in machine-readable mode, so in a script or CI job pass `--image` explicitly. On `modify`, `--setup` and `--clear-setup` are likewise mutually exclusive.
</Note>