Environment variable contract

Version: 0.44.1 | Date: 2026-06-12 | Commit: 6d282acf

This document is the canonical reference for every AGENTMUX_* (and legacy WAVEMUX_*) environment variable that flows through the AgentMux process tree. Its absence was the direct cause of the Win11 focused-border invisibility bug (AGENTMUX_AGENT_COLOR = #000000 silently became the pane’s focused-border colour, making it invisible against a dark background).

Process Tree Overview

agentmux-launcher  (J0 Job Object owner)
  │   sets: path vars, BACKEND_WS/WEB/PID, AUTH_KEY, SRV_PIPE_PATH
  │         LAUNCHER_PIPE, HOME, SPLASH_EVENT, INSTANCE_ID
  │
  ├── agentmux-srv  (sidecar, J0 member)
  │     reads: path vars, AUTH_KEY, APP_PATH, SRV_PIPE_PATH
  │     sets own env: LOCAL_URL (after binding), DATA_HOME, CONFIG_HOME
  │     strips: AUTH_KEY from its own process env after reading
  │
  └── agentmux-cef  (Chromium host, J0 member)
        reads: BACKEND_WS/WEB/PID, AUTH_KEY, LAUNCHER_PIPE/PID
               HOME, SPLASH_EVENT, INSTANCE_ID, RUNTIME_MODE, path vars
        │
        └── [PTY shell per pane]  (child of srv, not host)
              reads: AGENTMUX, BLOCKID, TABID, VERSION, LOG_DIR,
                     LOCAL_URL, AGENT_ID, AGENT_COLOR, AGENT_TEXT_COLOR,
                     TERM, COLORTERM, TERM_PROGRAM, PATH (augmented)
              shell integration sends OSC 16162;E back to srv

Source files cited throughout:

Group 1 — Identity Variables

These variables identify the agent persona assigned to a pane and drive focused-border colour, pane title, and jekt auto-registration.

AGENTMUX_AGENT_ID

Attribute	Value
Who sets it	srv shell controller (`shell.rs`) from block `cmd:env` metadata (never from global settings `cmd_env`); `crates/srv/src/server/app_api/agent_open.rs:656` on `agent.open`; `agent_config.rs:231` for MCP env injection
Who reads it	PTY shell process; shell integration scripts (`bash.sh:60`, `pwsh.ps1:37`, `zsh.sh:60`) encode it into OSC 16162;E on every prompt; `shell.rs` reads it to decide jekt auto-registration
Example value	`AgentX`, `Aria`, `Terminal`
Lifetime	Set once at pane spawn; persists for the lifetime of the PTY session

Priority chain (shell.rs:280-285):

Block metadata cmd:env["AGENTMUX_AGENT_ID"]
Legacy compat: WAVEMUX_AGENT_ID in the same block cmd:env (read-only fallback for jekt registration)

Global settings cmd_env["AGENTMUX_AGENT_ID"] and the srv process env are deliberately not consulted.

Strip logic (shell.rs): if none of the above sources provides a value, AGENTMUX_AGENT_ID, AGENTMUX_AGENT_COLOR, AGENTMUX_AGENT_TEXT_COLOR, WAVEMUX_AGENT_ID, and WAVEMUX_AGENT_COLOR are actively removed from the PTY child’s environment so a parent AgentMux pane’s identity does not bleed into a new plain terminal pane.

PITFALL — jekt pseudo-agent: AGENTMUX_AGENT_ID='Terminal' is the string that a plain (non-agent) pane would show if the strip logic were absent. Do not configure this value unless you actually want the pane treated as a named agent named “Terminal”. The jekt registry will accept it and route messages there.

PITFALL — OSC 16162;E feedback loop: The shell integration re-emits the value on every prompt via an OSC sequence that the srv parses. If you export AGENTMUX_AGENT_ID=X inside a running shell, the next prompt triggers an identity update that the frontend applies immediately. This is intentional (live agent re-binding), but setting the var to an empty string emits {} rather than nothing, which clears the pane’s displayed identity.

AGENTMUX_AGENT_COLOR

Attribute	Value
Who sets it	Same chain as `AGENTMUX_AGENT_ID`; typically set alongside it in block `cmd:env`
Who reads it	Nothing since its decommission on 2026-09-20 (`crates/srv/src/backend/pane_env.rs:71-76`): the shell integration scripts no longer send it in the OSC 16162;E payload, and the pane border uses the agent’s persisted `ui:color`
Example value	`#4A90E2`, `#FF6B35`
Format	CSS hex colour string, 6-digit `#RRGGBB`

SECURITY/PITFALL — Win11 border bug (the bug that required this doc): AGENTMUX_AGENT_COLOR=#000000 is valid and accepted. The focused-border renderer uses this value directly as the border colour. On a dark-themed desktop (the default on Win11), a pure-black border is invisible, making it impossible to tell which pane has keyboard focus. Always use a colour that contrasts with your background theme.

Strip logic: same as AGENTMUX_AGENT_ID — removed when no explicit agent identity is configured (shell.rs).

AGENTMUX_AGENT_TEXT_COLOR

Attribute	Value
Who sets it	Block `cmd:env` metadata; not emitted via OSC 16162;E by the current shell integration scripts
Who reads it	Frontend pane header; used as text colour for the agent name label in the pane title bar
Example value	`#FFFFFF`, `#1A1A1A`

Strip logic: removed at pane spawn when no agent identity is configured (shell.rs). Unlike AGENTMUX_AGENT_COLOR, this variable is NOT currently forwarded via OSC 16162;E — only AGENTMUX_AGENT_ID and AGENTMUX_AGENT_COLOR are in the OSC payload. Changing it inside a running shell has no effect until the next pane restart.

WAVEMUX_AGENT_ID / WAVEMUX_AGENT_COLOR (legacy)

Attribute	Value
Status	Deprecated — read-only backward-compat bridge
Who reads them	`shell.rs` reads `WAVEMUX_AGENT_ID` as the lowest-priority fallback for jekt registration only
Strip logic	Both are removed from PTY children when no explicit agent identity is configured (`shell.rs`)

These variables were the pre-rebrand names from the WaveMux era. Do not set them in new configurations; use AGENTMUX_* equivalents instead. The only surviving use is as a read-only fallback in the jekt auto-registration path — they are never written by AgentMux.

Group 2 — Path Variables

All path variables are set by the launcher from DataPaths::to_env_vars() (data_paths.rs:295-324) and consumed by downstream binaries via DataPaths::from_env() (data_paths.rs:332-372). The launcher is the single source of truth; downstream binaries must not recompute paths.

~/.agentmux/                              ← AGENTMUX_INSTANCE_DIR anchor (home_dir field)
├── shared/                               ← AGENTMUX_SHARED_DIR
├── channels/<channel>/                   ← AGENTMUX_INSTANCE_DIR  (Installed/Portable)
│   ├── config/                           ← AGENTMUX_CONFIG_DIR
│   ├── agents/                           ← AGENTMUX_AGENTS_DIR
│   └── versions/<ver>/
│       ├── data/                         ← AGENTMUX_DATA_DIR (+ legacy AGENTMUX_DATA_HOME)
│       ├── logs/                         ← AGENTMUX_LOG_DIR
│       ├── cef-cache/                    ← AGENTMUX_CEF_CACHE_DIR
│       └── runtime/                      ← AGENTMUX_INSTANCE_RUNTIME_DIR
└── dev/<branch>/[<clone_id>/]            ← AGENTMUX_INSTANCE_DIR  (Dev mode)
    └── (same children, no version/ nesting)

AGENTMUX_INSTANCE_DIR

Attribute	Value
Who sets it	Launcher, via `DataPaths::to_env_vars()` (`data_paths.rs:298`)
Who reads it	srv, host via `DataPaths::from_env()`
Example	`C:\Users\<name>\.agentmux\channels\stable`
Purpose	Channel root; config and agents directories hang directly off this

AGENTMUX_DATA_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:299`)
Who reads it	srv for SQLite database location (`objects.db`, `sagas.db`); `DataPaths::from_env()`
Example	`C:\Users\<name>\.agentmux\channels\stable\versions\0.44.1\data`

Legacy alias: srv also publishes AGENTMUX_DATA_HOME for any code path that pre-dates the unification (crates/srv/src/bootstrap/stores.rs:78). New code should read AGENTMUX_DATA_DIR.

AGENTMUX_CONFIG_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:300`)
Who reads it	srv `config.rs:162`, which re-exports it as `AGENTMUX_CONFIG_HOME` for `config_watcher_fs.rs:51` (`settings.json` and related config files)
Example	`C:\Users\<name>\.agentmux\channels\stable\config`

Legacy alias: AGENTMUX_CONFIG_HOME (base.rs:17). Same caveats as DATA_DIR/DATA_HOME above.

AGENTMUX_LOG_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:301`); also injected into PTY child environment by srv shell controller (`shell.rs`) with a hardcoded `~/.agentmux/logs` path
Who reads it	Shell integration `muxlog` helper (`bash.sh:92-106`, `pwsh.ps1:63-81`); `memory_heartbeat.rs:260`; any process in a pane that wants to locate logs
Example	`/home/alice/.agentmux/logs` or `C:\Users\<name>\.agentmux\logs`

Note on dual injection: The launcher sets the canonical per-channel log dir; the shell controller re-injects the value into PTY children using dirs::home_dir().join(".agentmux").join("logs") (a fixed path, shell.rs). The two values are identical in production but diverge in test scenarios. PTY children should use whatever value is in their environment.

PITFALL: On Windows with MSIX packaging, AGENTMUX_DATA_DIR and friends resolve inside the virtual file system, but AGENTMUX_LOG_DIR is always under the real home dir (shell.rs) because ConPTY child processes cannot see virtualised MSIX writes at their literal path.

AGENTMUX_CEF_CACHE_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:302`)
Who reads it	CEF host for Chromium profile / cache directory
Example	`C:\Users\<name>\.agentmux\channels\stable\versions\0.44.1\cef-cache`

Regenerable; can be deleted without data loss.

AGENTMUX_AGENTS_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:303`)
Who reads it	srv agent definition storage; channel-wide (does not include the version segment)
Example	`C:\Users\<name>\.agentmux\channels\stable\agents`

AGENTMUX_INSTANCE_RUNTIME_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:304-307`)
Who reads it	srv and launcher for single-instance lock files, IPC port file, named-pipe path
Example	`C:\Users\<name>\.agentmux\channels\stable\versions\0.44.1\runtime`

AGENTMUX_SHARED_DIR

Attribute	Value
Who sets it	Launcher (`data_paths.rs:308`)
Who reads it	Identity/OAuth code; provider auth dirs live here so credentials persist across channel/version upgrades
Example	`C:\Users\<name>\.agentmux\shared`

Channel-independent and version-independent. The fix for the per-channel OAuth re-authentication regression (each channel had an empty auth dir → Claude would spin prompting for login on every new channel). Provider credential directories now always live under shared/providers/<provider>/.

AGENTMUX_HOME

Attribute	Value
Who sets it	Launcher (Windows only, `crates/launcher/src/host_spawn.rs:129`) to the `runtime/` directory containing the host binary
Who reads it	CEF host for asset resolution (`crates/cef/src/commands/window/creation.rs:136`): `index.html`, frontend bundle
Example	`C:\Users\<name>\Desktop\agentmux-portable\runtime`

Purpose: Shields against a Windows bug where GetModuleFileName returns the load-time path even after the directory is renamed or unlinked. The launcher resolves the real exe path and exports the parent dir. Not set on Unix (fallback to current_exe().parent() is reliable there).

AGENTMUX_HOME_OVERRIDE (test-only)

Attribute	Value
Who sets it	Test harness only
Who reads it	`data_paths.rs:1000`, `crates/srv/src/bootstrap/stores.rs:147`, `crates/srv/src/registry/paths.rs:144`
Purpose	Replaces `~/.agentmux` root with a temp directory so tests don’t touch the real user data

SECURITY: Do not set this in production. Any process that sets this variable can redirect the entire AgentMux state tree to an arbitrary path.

Group 3 — Runtime / Mode Variables

AGENTMUX_RUNTIME_MODE

Attribute	Value
Who sets it	Launcher, computed once by `RuntimeMode::current()` (`runtime_mode.rs:73-121`)
Who reads it	srv and host via `RuntimeMode::from_env()` / `from_env_with_clone()`
Values	`installed`, `portable`, `dev:<branch>`
Example	`dev:main`, `installed`, `portable`

Detection priority (launcher):

AGENTMUX_RUNTIME_MODE env override (CI / testing)
agentmux-portable.marker file next to launcher binary
Exe path contains dist/cef-dev/, target/debug/, or target/release/
AGENTMUX_DEV_BRANCH env override (CI)
Default: installed

PITFALL — dev builds inside an agent pane: If you run task dev from inside an agent pane in a portable build, the child process inherits the parent’s AGENTMUX_RUNTIME_MODE=portable (and AGENTMUX_CHANNEL=stable). The dev host uses resolve_path_only (data_paths.rs:160) which ignores the env and relies on the exe path to detect dev mode — preventing cross-contamination. Do not override AGENTMUX_RUNTIME_MODE in an agent pane’s environment unless you know exactly what you are doing.

AGENTMUX_CHANNEL

Attribute	Value
Who sets it	Launcher (`data_paths.rs:313`) from channel resolution; also a user override for `Installed`/`Portable` modes
Who reads it	`crates/srv/src/bootstrap/stores.rs:138` for pre-migration snapshot naming; `DataPaths::from_env()` (required field — missing value causes `from_env()` to return `None`)
Example	`stable`, `beta`, `local-main`, `experiment`
Constraints	Max 64 chars; cannot be `shared`, `snapshots`, `dev`, `versions`, `channels`, `runtime`; `default` maps to `stable`

User-settable: For Installed and Portable modes, setting this before launch redirects the entire state tree to ~/.agentmux/channels/<value>/. Useful for parallel-channel testing. Ignored in dev mode when using resolve_path_only (see above).

AGENTMUX_CLONE_ID (Dev mode only)

Attribute	Value
Who sets it	Launcher (`data_paths.rs:320-322`) only when `RuntimeMode::Dev { clone_id: Some(...) }`
Who reads it	`RuntimeMode::from_env_with_clone()` (`runtime_mode.rs:199-209`) to reconstruct the full `Dev` variant
Example	`deadbeefcafebabe` (16-char hex FNV-1a hash of the clone’s workspace root path)

Ensures two clones of the same branch land in separate subdirectories (~/.agentmux/dev/<branch>/<clone_id>/), preventing lockfile collisions when running task dev from two clones simultaneously.

AGENTMUX_DEV_BRANCH (build/CI override)

Attribute	Value
Who sets it	CI pipelines or developer shell before launching
Who reads it	`runtime_mode.rs:108` as step 4 of mode detection (after portable marker and exe-path checks)
Example	`main`, `agenta-feature-x`

Allows forcing dev mode for a specific branch without matching the exe-path heuristics. Value is sanitized (path traversal stripped). If the sanitized value is empty, mode falls through to Installed.

AGENTMUX_VERSION

Attribute	Value
Who sets it	srv shell controller (`shell.rs`), `shellexec.rs:360`; baked at compile time via `env!("CARGO_PKG_VERSION")`
Who reads it	Shell integration `muxlog` helper to locate pointer files (`bash.sh:101`, `pwsh.ps1:72`); `crates/srv/src/bootstrap/stores.rs:139` reads it from env as a fallback
Example	`0.44.1`

Available in every PTY pane shell session. Required by muxlog to resolve the current-host-v<AGENTMUX_VERSION>.path pointer file.

AGENTMUX_DEV (legacy sentinel)

Attribute	Value
Status	Deprecated — no longer set by the launcher
Who reads it	`base.rs:20` defines the constant; some legacy code paths (`config.rs:166`) note it is no longer emitted
Replacement	`AGENTMUX_RUNTIME_MODE=dev:<branch>`

AGENTMUX_BUILD_CHANNEL_DEFAULT (compile-time)

Attribute	Value
Who sets it	Build script (`crates/common/build.rs:37`) from the env at compile time
Who reads it	`data_paths.rs:54-58` as `option_env!` — baked into the binary, not read at runtime
Example	`stable` (release CI), `local-main` (local `task package` on `main` branch)

This is a compile-time variable, not a runtime env var. Setting AGENTMUX_BUILD_CHANNEL_DEFAULT before running cargo build bakes a different default channel into the resulting binary. The agentmux-common build script emits cargo:rerun-if-env-changed=AGENTMUX_BUILD_CHANNEL_DEFAULT so incremental compilation detects the change.

Group 4 — IPC Variables

These variables wire together the launcher, host, and srv processes. Child processes inside panes also see some of them (LOCAL_URL, BLOCKID).

AGENTMUX_LOCAL_URL

Attribute	Value
Who sets it	srv after binding its HTTP listener (`crates/srv/src/bootstrap/network.rs:102`): `std::env::set_var("AGENTMUX_LOCAL_URL", &local_web_url)`
Who reads it	Shell controller propagates it into PTY children (`shell.rs`); `agentmux-bashwrap` reads it for WPS publish authentication (`crates/bashwrap/src/mps_client.rs:81`); jekt registry writer uses it for cross-instance registration (`shell.rs`)
Example	`http://127.0.0.1:49312`
Lifetime	Set once per srv startup; changes only when srv restarts

The URL is an ephemeral loopback HTTP endpoint (port 0 at binding, OS-assigned). It is the address of the srv’s web listener (not the WebSocket listener).

PITFALL: agentmux-bashwrap (the streaming bash runner) reads both AGENTMUX_LOCAL_URL and AGENTMUX_AUTH_KEY to authenticate WPS publish calls. If either is absent the wrapper silently skips publishing and Claude’s bash output does not stream to the drone/log pane.

AGENTMUX_AUTH_KEY

Attribute	Value
Who sets it	Launcher generates a UUID v4 per run (`srv_spawner.rs:422`); sets it on both srv and host
Who reads it	srv `config.rs:136` reads and immediately removes it from the process env (security hardening, PR #801); websocket handler re-injects it into agent process spawns (`crates/srv/src/server/agent_handlers/input.rs:603`) for streaming bash auth; `crates/bashwrap/src/mps_client.rs:82` for WPS publish
Example	`550e8400-e29b-41d4-a716-446655440000` (UUID v4)

SECURITY: srv actively removes this from its own process environment after reading it (config.rs:144). This prevents child processes spawned by srv (not through the PTY/shell path) from inheriting the bearer token. The websocket handler re-injects a fresh copy only for processes that need it (streaming bash runner via agent.run-command).

SECURITY: Do not log this value. It authenticates all WebSocket connections to the srv instance for the lifetime of that srv process.

Container agents don’t get this value. Their docker exec environment carries a per-pane token starting amxc_ in the same variable, which srv accepts only on the agent routes (messaging, work queue, the agent’s own memory, self-quit) and refuses everywhere else (crates/srv/src/backend/container_credential.rs). See Trust model.

AGENTMUX_BACKEND_WS / AGENTMUX_BACKEND_WEB / AGENTMUX_BACKEND_PID

Attribute	Value
Who sets it	Launcher on the host process env (`crates/launcher/src/host_spawn.rs:80-82`)
Who reads it	CEF host `sidecar.rs:85,103,104` to skip spawning its own srv when one is already running
Example	`AGENTMUX_BACKEND_WS=ws://127.0.0.1:49313` / `AGENTMUX_BACKEND_WEB=http://127.0.0.1:49312` / `AGENTMUX_BACKEND_PID=12345`

These three vars form the launcher-managed srv hand-off. When all three are present, the host skips spawn_backend() and connects to the launcher-owned srv instead. If AGENTMUX_BACKEND_WS is set but empty or malformed, the host hard-fails rather than silently spawning a second srv (crates/cef/src/lib.rs:839-845).

PITFALL: Dev builds launched from inside an agent pane inherit these vars from the parent. The host uses launcher_is_genuine_parent() (checks AGENTMUX_LAUNCHER_PID against getppid()) to distinguish a genuine launcher hand-off from an inherited stale value. Without this check, a developer running task dev inside a pane would silently connect the new host to the parent’s srv.

AGENTMUX_SRV_PIPE_PATH

Attribute	Value
Who sets it	Launcher (`srv_spawner.rs:456`) passes it to srv; launcher also advertises it to itself via env for re-use
Who reads it	srv (`crates/srv/src/bootstrap/plumbing.rs:271`): if set, opens a named-pipe IPC server for launcher ↔ srv control channel; CEF host `srv_ipc.rs:62` to connect its IPC bridge
Example	`\\.\pipe\agentmux-srv-3f9a8c1d` (Windows) / `/tmp/agentmux-srv-3f9a8c1d.sock` (Unix)

Absent in task dev mode (no launcher in the loop). The presence of this var is the discriminator between launcher-managed and standalone execution.

AGENTMUX_LAUNCHER_PIPE

Attribute	Value
Who sets it	Launcher on the host env (`crates/launcher/src/host_spawn.rs:106`)
Who reads it	CEF host `crates/cef/src/launcher_ipc/mod.rs:103` to connect the launcher ↔ host control channel; the Unix-socket variant reads it too (`crates/cef/src/launcher_ipc/mod.rs:368`)
Example	Same path format as `AGENTMUX_SRV_PIPE_PATH` with a different leaf name

Absent in standalone / dev mode. Host logs a warning and continues without the IPC bridge.

AGENTMUX_LAUNCHER_PID

Attribute	Value
Who sets it	Launcher on the host env, on every platform (`crates/launcher/src/host_spawn.rs`; Windows too since v0.58.0)
Who reads it	CEF host (`launcher_is_genuine_parent`, `crates/cef/src/parent_process.rs`) to verify the launcher is still alive and is genuinely the current parent
Example	`5432`

Used to distinguish a genuine launcher hand-off from an inherited stale AGENTMUX_BACKEND_WS value (when the host is launched inside an agent pane). The host compares its real parent process id to this value (getppid() on Unix, the process snapshot on Windows). A dev host on Windows used to ignore the hand-off and start a second srv on the same data directory; it now adopts the launcher’s srv, as on macOS and Linux.

AGENTMUX_INSTANCE_ID

Attribute	Value
Who sets it	Launcher on both srv and host (`crates/launcher/src/host_spawn.rs:86`, `srv_spawner.rs:427`)
Who reads it	CEF host `sidecar.rs:116`; identifies the srv instance for multi-instance coordination
Example	`v0.44.1`

Formatted as v<version>. Not the same as AGENTMUX_VERSION (which is the raw semver string without the v prefix injected into PTY children).

AGENTMUX_SPLASH_EVENT (Windows only)

Attribute	Value
Who sets it	Launcher (`crates/launcher/src/host_spawn.rs:132`)
Who reads it	CEF host `crates/cef/src/client/navigation.rs:265` signals this named Win32 event when the first page load completes, causing the launcher to dismiss the splash window
Example	A Win32 event object name, unique per run

Used exclusively for splash-screen synchronisation on Windows. Has no effect on Unix builds.

AGENTMUX_BLOCKID

Attribute	Value
Who sets it	srv shell controller (`shell.rs`); websocket handler for agent process spawns (`crates/srv/src/server/agent_handlers/input.rs:607`); `shellexec.rs:352`
Who reads it	`agentmux-bashwrap` (`bash_wrap.rs:494,499`) to scope WPS publishes to the correct pane; shell integration scripts have access to it in the PTY environment
Example	`550e8400-e29b-41d4-a716-446655440001` (block UUID)

Unique per pane block. The streaming bash runner uses this to route output chunks to the correct pane subscription.

AGENTMUX_TABID

Attribute	Value
Who sets it	srv shell controller (`shell.rs`); `shellexec.rs:353`
Who reads it	Shell integration and any process that needs to know which tab it belongs to
Example	`550e8400-e29b-41d4-a716-446655440002` (tab UUID)

AGENTMUX_CDP_PORT

Attribute	Value
Who sets it	You, before starting AgentMux (optional)
Who reads it	CEF host at startup (`crates/cef/src/cdp_port.rs`, `requested_cdp_port`)
Values	Unset or empty: CDP server off in release builds, on (port 9223) in dev builds. `1024`–`65535`: on, preferring that port. `1`/`on`/`true`/`yes`/`auto`: on, preferring 9222 (release) or 9223 (dev). `0`/`off`/`false`/`no`: off, dev builds included

Controls Chromium’s unauthenticated remote-debugging (CDP) server. AgentMux’s own browser automation doesn’t need it. If the preferred port is taken an OS-assigned port is used, and the port in use is written to authkey.dev. See Network exposure.

AGENTMUX_APP_PATH

Attribute	Value
Who sets it	Launcher (`srv_spawner.rs:455`), host `sidecar.rs:300`; re-set in srv process env at startup (`crates/srv/src/bootstrap/stores.rs:84`)
Who reads it	srv `base.rs:19` (`MUX_APP_PATH_ENV`); used to locate bundled tool binaries (`jq.exe`, `rg.exe`, etc.) alongside the launcher
Example	`C:\Users\<name>\Desktop\agentmux-portable`

Group 5 — Terminal Emulator Capability Variables

Set by the srv shell controller (shell.rs) on every interactive shell pane. These are standard terminal capability variables; values are fixed constants.

TERM

Attribute	Value
Set to	`xterm-256color`
Why	ConPTY on Windows fully supports VT/ANSI sequences. Without TERM, CLI tools (including Claude Code) use different Unicode width tables, causing ANSI colour offset on Windows. `shell.rs`

COLORTERM

Attribute	Value
Set to	`truecolor`
Why	Signals 24-bit colour support. Without this, tools that check for truecolor fall back to 256-colour palettes. `shell.rs`

TERM_PROGRAM

Attribute	Value
Set to	`agentmux`
Why	Allows CLI tools to detect they are running inside AgentMux and enable specific integrations. `shell.rs`

Group 6 — Shell Integration Variables

Variables set by the shellintegration.rs / get_shell_startup() logic (shellintegration.rs:260-315) at shell spawn time.

AGENTMUX (sentinel)

Attribute	Value
Who sets it	srv shell controller (`shell.rs`)
Set to	`1`
Purpose	Presence-check sentinel for shell integration scripts. Scripts test `[[ -n "$AGENTMUX" ]]` to confirm they are running inside AgentMux

History: In WaveMux/Waveterm, AGENTMUX (then WAVETERM) held the path to the wsh binary. Since wsh was retired (docs/specs/archive/SPEC_RETIRE_WSH_2026_04_12.md), the variable is now a plain 1 sentinel. Shell integrations no longer prepend anything to $PATH based on its value.

ZDOTDIR / AGENTMUX_ZDOTDIR (zsh only)

Attribute	Value
Who sets it	`shellintegration.rs:280-282` at zsh spawn
ZDOTDIR	`~/.agentmux/shell/zsh` — causes zsh to load AgentMux’s `.zshrc` instead of `~/.zshrc`
AGENTMUX_ZDOTDIR	Same path — preserved so the integration `.zshrc` can source the real `~/.zshrc`

The AgentMux zsh .zshrc sources ~/.zshrc explicitly (zsh.sh:13) to preserve user configuration.

Group 7 — Legacy / Transition Variables

AGENTMUX_DATA_HOME

Attribute	Value
Status	Deprecated alias for `AGENTMUX_DATA_DIR`
Who sets it	srv `crates/srv/src/bootstrap/stores.rs:78` re-publishes it for backward compatibility if `config.data_home` is non-empty
Who reads it	`base.rs:18` (`MUX_DATA_HOME_ENV`); `crates/srv/src/bootstrap/stores.rs:25`; `sidecar.rs` (pre-unification path)

Use AGENTMUX_DATA_DIR in new code.

AGENTMUX_CONFIG_HOME

Attribute	Value
Status	Deprecated alias for `AGENTMUX_CONFIG_DIR`
Who sets it	srv `crates/srv/src/bootstrap/stores.rs:81`
Who reads it	`base.rs:17`; `config_watcher_fs.rs:51`

Use AGENTMUX_CONFIG_DIR in new code.

Complete Variable Quick-Reference

Variable	Group	Set By	Available In Pane?
`AGENTMUX_AGENT_ID`	Identity	block metadata / settings	Yes
`AGENTMUX_AGENT_COLOR`	Identity	block metadata / settings	Yes
`AGENTMUX_AGENT_TEXT_COLOR`	Identity	block metadata / settings	Yes
`WAVEMUX_AGENT_ID`	Identity (legacy)	user config	Yes (stripped if no identity)
`WAVEMUX_AGENT_COLOR`	Identity (legacy)	user config	Yes (stripped if no identity)
`AGENTMUX_INSTANCE_DIR`	Paths	launcher	No
`AGENTMUX_DATA_DIR`	Paths	launcher	No
`AGENTMUX_CONFIG_DIR`	Paths	launcher	No
`AGENTMUX_LOG_DIR`	Paths	launcher + shell controller	Yes
`AGENTMUX_CEF_CACHE_DIR`	Paths	launcher	No
`AGENTMUX_AGENTS_DIR`	Paths	launcher	No
`AGENTMUX_INSTANCE_RUNTIME_DIR`	Paths	launcher	No
`AGENTMUX_SHARED_DIR`	Paths	launcher	No
`AGENTMUX_HOME`	Paths	launcher (Windows only)	No
`AGENTMUX_HOME_OVERRIDE`	Paths (test)	test harness	No
`AGENTMUX_RUNTIME_MODE`	Runtime	launcher	No
`AGENTMUX_CHANNEL`	Runtime	launcher / user	No
`AGENTMUX_CLONE_ID`	Runtime	launcher (dev mode)	No
`AGENTMUX_DEV_BRANCH`	Runtime	CI / user (pre-launch)	No
`AGENTMUX_VERSION`	Runtime	shell controller	Yes
`AGENTMUX_BUILD_CHANNEL_DEFAULT`	Runtime (build-time)	build script	No
`AGENTMUX_DEV`	Runtime (legacy)	deprecated	No
`AGENTMUX_LOCAL_URL`	IPC	srv (after bind)	Yes
`AGENTMUX_AUTH_KEY`	IPC	launcher	No (stripped from srv; re-injected per-spawn)
`AGENTMUX_BACKEND_WS`	IPC	launcher → host	No
`AGENTMUX_BACKEND_WEB`	IPC	launcher → host	No
`AGENTMUX_BACKEND_PID`	IPC	launcher → host	No
`AGENTMUX_SRV_PIPE_PATH`	IPC	launcher → srv + host	No
`AGENTMUX_LAUNCHER_PIPE`	IPC	launcher → host	No
`AGENTMUX_LAUNCHER_PID`	IPC	launcher → host	No
`AGENTMUX_INSTANCE_ID`	IPC	launcher → srv + host	No
`AGENTMUX_SPLASH_EVENT`	IPC (Windows)	launcher → host	No
`AGENTMUX_BLOCKID`	IPC	shell controller	Yes
`AGENTMUX_TABID`	IPC	shell controller	Yes
`AGENTMUX_APP_PATH`	IPC	launcher → srv	No
`TERM`	Terminal	shell controller	Yes
`COLORTERM`	Terminal	shell controller	Yes
`TERM_PROGRAM`	Terminal	shell controller	Yes
`AGENTMUX`	Shell integration	shell controller	Yes
`ZDOTDIR`	Shell integration (zsh)	shell controller	Yes
`AGENTMUX_ZDOTDIR`	Shell integration (zsh)	shell controller	Yes
`AGENTMUX_DATA_HOME`	Legacy	srv (compat re-publish)	No
`AGENTMUX_CONFIG_HOME`	Legacy	srv (compat re-publish)	No

Key Source Locations

Topic	File	Lines
PTY env injection (shell controller)	`crates/srv/src/backend/blockcontroller/shell/lifecycle.rs`	—
Identity strip logic	`crates/srv/src/backend/blockcontroller/shell/lifecycle.rs`	—
Jekt auto-registration	`crates/srv/src/backend/blockcontroller/shell/lifecycle.rs`	—
DataPaths struct and env var names	`crates/common/src/data_paths.rs`	77–127
DataPaths::to_env_vars()	`crates/common/src/data_paths.rs`	295–324
DataPaths::from_env()	`crates/common/src/data_paths.rs`	332–372
RuntimeMode detection	`crates/common/src/runtime_mode.rs`	73–121
AGENTMUX_LOCAL_URL set point	`crates/srv/src/bootstrap/network.rs`	99–102
AUTH_KEY strip	`crates/srv/src/config.rs`	136–144
AUTH_KEY re-inject for streaming bash	`crates/srv/src/server/agent_handlers/input.rs`	584–603
Shell integration deployment	`crates/srv/src/backend/shellintegration.rs`	166–246
Bash integration script	`crates/srv/src/backend/shellintegration/bash.sh`	whole file
PowerShell integration script	`crates/srv/src/backend/shellintegration/pwsh.ps1`	whole file
Zsh integration script	`crates/srv/src/backend/shellintegration/zsh.sh`	whole file
Launcher → srv env vars	`crates/launcher/src/srv_spawner.rs`	439–456
Launcher → host env vars (Windows)	`crates/launcher/src/host_spawn.rs`	77–133
Launcher → host env vars (Unix)	`crates/launcher/src/host_spawn.rs`	194–221
WSH retirement (AGENTMUX sentinel history)	`docs/specs/archive/SPEC_RETIRE_WSH_2026_04_12.md`	—
Data channels design	`docs/specs/SPEC_DATA_CHANNELS_2026_05_24.md`	—