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

# Runtime environments

> A runtime environment is the agent's computer: the CLIs, packages, config files, setup scripts and standing context it finds installed on every run. Defined once under Platform > Agents > Runtime > Environments, attached per agent, inherited from a parent.

A **runtime environment** is the agent's computer. Everything a person has preinstalled on a laptop before starting work, the AWS CLI with a kubeconfig, `kubectl`, the Snowflake or Google Cloud CLI, a language toolchain, the team's conventions, is what the agent finds installed when its session starts. It is attached **per agent**, not per session: every conversation of that agent starts on the same computer.

This is a different thing from the two other places an agent has:

| | What it is | Where it is set |
| - | - | - |
| **Runtime environment** | What is installed: CLIs, packages, config files, setup scripts, standing context | Platform > Agents > Runtime > **Environments**, attached under Agent settings > **Advanced** > **Runtime environment** |
| **Workspace** | The agent's files: its working directory, the files it produces and shares | The agent's **Agent workspace** |
| **Location** | Where the computer runs: xpander cloud or one of your self-hosted clusters | Platform > Agents > Runtime > **Locations**, the **Environment** picker on **New agent** |

A CLI in the runtime environment often replaces a skill. An agent with the AWS CLI and a kubeconfig operates the account the way an engineer does, one command at a time, instead of needing a skill for every operation. The same holds for a Snowflake or Google Cloud CLI, or anything else a laptop would have.

## What goes in

Platform > Agents > Runtime > **Environments** > **New runtime environment**: "Context, packages, setup scripts and config files an agent inherits when it attaches this environment."

![Runtime page on the Environments tab with New environment and three environments, two nested under Acme engineering base](https://mintcdn.com/xpanderai-099931d1/wqIIXSsh0kqA2hZ_/images/verify/platform-runtime-environments.png?fit=max\&auto=format\&n=wqIIXSsh0kqA2hZ_\&q=85\&s=74f18990381f3a6b52089ecddf0ed36b)

Platform > Agents > Runtime > Environments. Shown with sample data.

| Field | What it does |
| - | - |
| **Name**, **Icon**, **Description** | How the environment appears in the agent's picker |
| **Inherits from** | A parent environment, or **No parent (root)**. A child gets everything the parent has and adds its own |
| **Context** | Markdown the agent reads at the start of every run: team conventions, what each repository does, what to check before opening a pull request. Up to 32,768 characters |
| **Packages** | **pip**, **npm** and **pnpm** packages, one entry each. The form also has a **brew** field, but agent machines do not install brew packages. See [Install a CLI](#install-a-cli) |
| **Setup scripts** | Scripts that run when the environment is built, for anything a package manager does not cover. A file a script saves into `$XPANDER_ENV_BIN` is on the agent's PATH |
| **Config files** | Non-secret files written at a home-relative path, for example `.kube/config`; a leading `~/` is fine. Never put a secret here; workspace secrets always win at turn time |

## Install a CLI

Agent machines do not install brew packages. The **brew** field says so: "Agent machines do not install brew packages. Agents see these names as not installed." The agent is told which brew packages were not installed, so it can tell you.

Install a CLI in one of these ways:

* Use its pip, npm or pnpm package when one exists, for example `awscli` (pip).
* Add a setup script that downloads the CLI's release binary into `$XPANDER_ENV_BIN`. Every agent on the environment then has it on PATH:

  ```sh theme={"dark"}
  curl -fsSL -o "$TMPDIR/tflint.zip" https://github.com/terraform-linters/tflint/releases/download/v0.53.0/tflint_linux_amd64.zip
  unzip -o "$TMPDIR/tflint.zip" -d "$XPANDER_ENV_BIN"
  ```

## How it reaches the agent

The environment is built once and mounted read-only into every session of the agents that attach it. The context is read at the start of every run and is managed only in Xpander Chat, so an agent cannot rewrite the guidance it was given. After you save a change, new sessions get it within 5 minutes. Because the environment is attached to the agent, it follows the agent to whichever location it runs in.

Secrets are not part of a runtime environment. A CLI reads its credential from the agent's **Workspace secrets** at the moment of a call, so a kubeconfig or a cloud profile in **Config files** names the endpoint and the account, never the key.

## Attach it to an agent

Agent settings > **Advanced** > **Runtime environment** lists the organization's environments; pick one. The agent's next session starts on it. Switching environments does not touch the agent's files.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.