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

# Environment schemas

> Environment object and configuration structures.

## Environment object

Returned by create, get, list, update, and archive endpoints.

| Field         | Type                                      | Description                                                                                |
| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `id`          | string                                    | Environment ID with the `env_` prefix                                                      |
| `type`        | string                                    | Always `"environment"`                                                                     |
| `name`        | string                                    | Environment name                                                                           |
| `description` | string                                    | Environment description                                                                    |
| `config`      | [Environment config](#environment-config) | Environment configuration                                                                  |
| `metadata`    | object                                    | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object). Defaults to `{}` |
| `archived_at` | string \| null                            | Archive time in UTC, or `null` when not archived                                           |
| `created_at`  | string                                    | Creation time in UTC                                                                       |
| `updated_at`  | string                                    | Last update time in UTC                                                                    |

## Environment config

| Field          | Type                                              | Required | Description                                                                       |
| -------------- | ------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `type`         | string                                            | Yes      | `"cloud"` or `"self_hosted"`                                                      |
| `networking`   | [Environment networking](#environment-networking) | No       | Network access configuration                                                      |
| `packages`     | [Environment packages](#environment-packages)     | No       | Package declarations associated with the environment                              |
| `setup_script` | string                                            | No       | User setup script text. See [Environment setup script](#environment-setup-script) |

For `self_hosted`, the config must be exactly:

```json theme={null}
{"type": "self_hosted"}
```

Other config fields are only valid when `type` is `"cloud"`.

## Environment packages

`packages` maps package managers to arrays of package spec strings. Cloud environment responses include `type` plus `apt`, `npm`, and `pip`; omitted arrays are returned as `[]`.

| Key    | Type            | Description                               | Example                              |
| ------ | --------------- | ----------------------------------------- | ------------------------------------ |
| `type` | string          | Always `"packages"` in responses          | `"packages"`                         |
| `apt`  | array of string | Debian/Ubuntu system package declarations | `["git", "curl", "build-essential"]` |
| `npm`  | array of string | Node.js package declarations              | `["typescript@5.0.0", "eslint"]`     |
| `pip`  | array of string | Python package declarations               | `["pandas", "PyYAML==6.0.1"]`        |

## Environment setup script

`setup_script` is a shell script executed during sandbox preparation, after `packages` are installed. It runs through `/bin/bash -lc`. Use it for initialization steps that cannot be expressed as `packages`, for example, cloning a repository, writing config files, or warming caches.

| Constraint   | Value                                              |
| ------------ | -------------------------------------------------- |
| Type         | string                                             |
| Max length   | 64 KB                                              |
| Interpreter  | `/bin/bash -lc`                                    |
| Timeout      | 10 minutes                                         |
| When it runs | Sandbox preparation, after `packages` installation |

On success a completion marker is written inside the sandbox so the script does not run twice in the same sandbox; when the sandbox is recreated, the script runs again.

A non-zero exit aborts session startup. The error response includes the `setup_script` exit code and a stderr excerpt to help diagnose the failure.

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
  }
}
```

## Environment networking

| Field                    | Type            | Required | Description                                                               |
| ------------------------ | --------------- | -------- | ------------------------------------------------------------------------- |
| `type`                   | string          | Yes      | Valid values: `limited`, `unrestricted`                                   |
| `allowed_hosts`          | array of string | No       | Host allowlist values returned with the config. Defaults to `[]`          |
| `allow_package_managers` | boolean         | No       | Package manager access flag returned with the config. Defaults to `false` |
| `allow_mcp_servers`      | boolean         | No       | MCP server access flag returned with the config. Defaults to `false`      |

## Related

<CardGroup cols={2}>
  <Card title="Cloud environment setup" icon="server" href="/cloud-agents/environments">
    Choose the container, network, and dependencies your agent runs in.
  </Card>
</CardGroup>