---
title: "Environments"
description: "Named environment profiles a session launches under, kept with agent-manager env and picked per session or per group."
canonical: "https://agent-manager.dev/docs/environments/"
last-updated: "2026-11-01"
section: "Documentation"
language: "en"
source: "agent-manager"
---

# Environments

An environment profile is a named set of environment variables a session launches under, on top of the environment the manager itself runs in. You pick one per session or per group. The commands are `agent-manager env`.

## Profiles

`env list` prints each name and its keys, and leaves the values out. `env show` prints `KEY=VALUE`. `env set` writes variables and creates the profile when it is new. `env unset` removes variables. `env rm` deletes the profile. `list` and `show` take `--json`.

```bash
agent-manager env list
agent-manager env show work
agent-manager env set work AWS_PROFILE=work
agent-manager env unset work AWS_PROFILE
agent-manager env rm work
```

A name is 1 to 60 characters, with no leading or trailing space, and it cannot contain a control character. A key takes letters, digits and `_`, and it cannot start with a digit. A key that starts with `AGENT_MANAGER_`, in any case, is refused, because the manager sets those itself. A value cannot hold a NUL byte.

The next launch of every session under a profile picks up a change, including a revive or a restart. A session that is already running keeps the environment it started with. Deleting a profile makes sessions that still name it refuse to launch until it is set again. A missing name is refused, and the message names the profiles that exist, or tells you to create one with `agent-manager env set`.

Settings lists each profile as its name and its keys, and never the values. The `environments` row is hidden until at least one profile exists. `enter` on that row does not edit it. Changing a profile is the `env` command, so a token stays out of the settings screen. [Export](/docs/config/#export) does not include profiles.

## Which profile a session uses

A session left unset inherits the nearest ancestor group's profile. With no group profile, it inherits the profile of the session that created it, so a helper keeps that account. Otherwise it launches with none. An explicit choice wins, and an empty choice means none.

On the new-session form the `env` row shows when a profile exists or the group already names one. Leave it untouched and the row is marked as the group's. Under a parent group that names a profile, a child group left on none keeps inheriting it, and the form notes which profile that is. Stepping the row stores a profile on the child itself. The new-group form and the group edit card (`r`) have the same row when there is a choice.

In quick prompt mode, `ctrl+g` steps the profile a new session launches under, once a profile exists. A click on the env chip does the same. [Quick prompt](/docs/prompt/#keys) lists the key.

`agent-manager spawn --env` sets the profile for that launch. Leave the flag out and the session inherits. Pass an empty string for none. `create_session` takes the same choice in `environment`: omit it to inherit, pass an empty string for none. It is refused together with `host`, because a profile applies to a session on this machine. A session on an SSH connection does not offer the row, and quick prompt mode does not offer `ctrl+g` there.