This page lists the environment variables the Loom command, installers, and plugins actually read, and says which ones you might ever need to set.
Most people set none of them. Loom is configured by stores.toml, not by the environment.
| Variable | Read by | Meaning |
|---|---|---|
LOOM_WEB_BASE | loom setup and loom login | The web server to use when --base is not given. Defaults to https://loomcloud.ai. An origin only (no path). Must be https, except for an IP address in 10/8, 172.16/12, 192.168/16, 100.64/10 or fc00::/7, where http is allowed; http is refused for localhost and loopback addresses (https://localhost and https://127.0.0.1 are accepted), and an empty value is an error. For loom setup, a web_origin recorded in stores.toml outranks it when stores.toml has exactly one store section and that section has a web_origin. Commands that act on an existing store (create_store, drop_store, unlock_store, set_store_domain) do not read it: they use the web_origin of the section they act on or authenticate with from stores.toml (https://loomcloud.ai when the section has none). |
LOOM_CLI_BOOTSTRAP_URL | the CLI installers (install.sh, install.ps1) | The folder URL the installer downloads loom-cli-bootstrap.tar.gz and SHA256SUMS from. Defaults to https://loomcloud.ai/.well-known/cli. |
LOOM_UV_RELEASE_BASE | install.ps1 (Windows) | Where the installer fetches the uv Python tool from. Defaults to the latest release on GitHub. |
export LOOM_WEB_BASE=https://loom.example.org
loom login| Variable | Meaning |
|---|---|
LOOM_CURVE_SECRET_KEY | Your secret connection key for a direct connection (one that does not go through the store gateway). It is used only when the store's section in stores.toml does not already give curve_secret_key. It lets a secret manager supply the key without writing it to a file. |
The server-side administration scripts also read the variable families LOOM_ADMIN_STORE, LOOM_AUTO_SIGNUP, LOOM_CAPTCHA_*, LOOM_CLOUD_ROOT, LOOM_INVITE_*, LOOM_PUBLIC_SITE, LOOM_REGISTRY_DIR, LOOM_RESULT_TTL, LOOM_SERVER_ROOT, LOOM_TRIAL_*, LOOM_TRUSTED_PROXY and LOOM_MASTER_CACHE_FILE. They are for server operators and not for client use.
| Variable | Meaning |
|---|---|
LOOM_STORES_TOML | Path of the stores.toml that the server-side administration scripts read. Not used by the loom command. |
LOOM_SRC_DIR | Directory holding the client source files: the web server loads its Kanban support files from it, and the server-side administration scripts read the client source from it. Set by the server's service unit; not for client use. |
LOOM_DIR | Where the Loom runtime files live. Hooks and the environment check use it to find them; Loom's own launchers set it for you. Set it yourself only when running hooks against a runtime in an unusual place. |
LOOM_EMBED_BACKEND | Obsolete selector for the embedding backend. The only supported value is fastembed; any other non-empty value makes Loom stop with an error. Leave it unset. |
These control the update check that Claude Code and Codex hooks run at session start.
| Variable | Meaning |
|---|---|
LOOM_PLUGIN_AUTOUPDATE | Set to 1 to let the check run the upgrade commands itself instead of only reporting that a newer plugin exists. |
LOOM_PLUGIN_SKIP_REMOTE | Set to 1 to skip asking the remote marketplace for the latest version. The check asks the server the plugin was installed from: https://loomcloud.ai for the hosted service, your own server for a plugin installed from it. |
LOOM_PLUGIN_HARNESS | Force the harness the check assumes: claude or codex. |
LOOM_PLUGIN_MARKETPLACE_ROOT | Path to a local plugin marketplace clone to compare against, instead of the harness's own clone. Setting it also bypasses the check that the plugin was installed from the hosted marketplace; a path that does not exist silences the update nudge. |
| Variable | Meaning |
|---|---|
LOOM_POST_TOOL_HINTS | Set to 1, true, yes or on to turn on extra hints in Codex after file-editing tool calls and after Bash test, build or lint commands. |
LOOM_CODEX_DEFAULTS | Set by the Codex hook command for compatibility with older hook files. It has no effect today; do not rely on it. |
LOOM_HOOK_INPUT | A JSON hook payload that the OpenCode hook script reads instead of standard input, if it is set. Nothing in Loom sets it; it exists for testing the hook by hand. |
LOOM_OPENCODE_ROOT | Where the OpenCode installer puts its bundle. Defaults to ~/.loom/opencode. The OpenCode plugin (plugins/loom.ts) also reads it. |
LOOM_OPENCODE_VERSION | The OpenCode bundle version to install. Defaults to latest. |
LOOM_OPENCODE_BASE | The marketplace Git URL the OpenCode installer clones. Defaults to https://loomcloud.ai/loom-plugins.git; an installer script fetched from a private server that serves its own plugins defaults to that server's <origin>/loom-plugins.git instead. |
LOOM_OPENCODE_TOKEN | The name OpenCode's sign-in flow declares for the token it collects. Loom's own installer script does not read it. |
Do not set these. The launcher that loom residual install creates sets LOOM_FLEET_RUNTIME_BUNDLE_ID and LOOM_FLEET_RUNTIME_VERSION to record which runtime bundle a Fleet computer is running. They are reported to the board in the computer's heartbeat (as runtime_bundle_id and runtime_loom_version); loom residual status does not print them.
Server operators: the LOOM_WEB_*, LOOM_BROKER_* and LOOM_PRIVATE_* variables are written into the server's service units by loom setup --mode private; you do not set them by hand. This includes LOOM_WEB_TERMS_URL and LOOM_WEB_PRIVACY_URL, which carry the Terms and Privacy URLs from the config (v0.674 or later).
Kanban identifies each agent as <harness>@<session-id>. whoami reads the session id from the variable the harness sets:
| Harness | Variable |
|---|---|
| Claude Code | CLAUDE_CODE_SESSION_ID |
| Codex | CODEX_THREAD_ID |
| OpenCode | OPENCODE_SESSION_ID |
| Hermes | HERMES_SESSION_ID |
You do not set these; the harness does. If you resume a Claude Code session, Loom checks that the id names a real transcript before using it. From v0.674 a Codex id used from a plain shell must likewise name a real Codex session file (under ~/.codex/sessions, or under CODEX_HOME when you set it). Otherwise it refuses rather than guess, so a stray id does not create a phantom agent.