Herm configuration

Herm is designed to work with zero configuration out of the box. As long as Hermes Agent is installed and your Hermes home directory exists at ~/.hermes, you can run herm with no extra setup. Every environment variable described on this page is optional: set them only when the defaults do not match your environment.

Environment variables

Herm’s environment-variable surface is generated from the Herm source repo. Most users only need HERMES_HOME, HERMES_AGENT_ROOT, HERMES_PYTHON, or HERM_CONFIG_DIR when their install lives outside the default paths.

Variable	Purpose
`CONTROL`	Enable the local control server when set to `1`.
`CONTROL_BIND`	Control server bind address. Defaults to `127.0.0.1`.
`CONTROL_PORT`	Control server port. Defaults to `7777`.
`EDITOR`	Fallback editor for opening prompt drafts.
`EIKON_URL`	Override the native Eikon Marketplace catalog URL.
`HERMES_AGENT_ROOT`	Hermes Agent source/install tree used to launch the gateway.
`HERMES_CWD`	Working directory passed to the gateway session.
`HERMES_HOME`	Hermes data directory. Defaults to `~/.hermes`.
`HERMES_KANBAN_BOARD`	Default kanban board filter/selection.
`HERMES_KANBAN_BUSY_TIMEOUT_MS`	Kanban busy timeout in milliseconds.
`HERMES_KANBAN_HOME`	Pin the kanban data home.
`HERMES_MANAGED`	Marks package-manager-managed Hermes installs.
`HERMES_PYTHON`	Python interpreter used for the gateway subprocess.
`HERMES_TUI_NO_CONFIRM`	Skip Herm client-side destructive slash confirmations when set to `1`.
`HERM_CONFIG_DIR`	Herm TUI preferences directory. Defaults to `$HERMES_HOME/herm`.
`HERM_EIKON_MARKETPLACE`	Override the lower-level Eikon catalog loader default. The native Marketplace tab uses `EIKON_URL`.
`HERM_IO_INLINE`	Inline I/O payload mode for Herm internal I/O.
`PERF`	Enable performance logging or verbose performance mode.
`VIRTUAL_ENV`	Preferred Python virtualenv when resolving the gateway interpreter.
`VISUAL`	Preferred editor for opening prompt drafts.

Where Herm stores preferences

Herm writes its own runtime preferences to a single JSON file:

$HERM_CONFIG_DIR/tui.json

This file stores themes, keybinding overrides, and other runtime preferences. You can edit it by hand, but the recommended way to change themes and keybindings is through the TUI itself: use /theme to pick a color scheme or /keys to view and rebind shortcuts. Changes are written to tui.json automatically. If HERM_CONFIG_DIR is not set, the file lives at ~/.hermes/herm/tui.json.

Using a `.env` file

Because Herm runs on Bun, it automatically loads a .env file from the working directory when you run the herm command. You can use this to set any of the variables above without exporting them in your shell profile. Create a .env file alongside your project or in the directory from which you typically launch Herm:

.env

# These overrides are optional. Herm uses defaults when they are unset.

# Relocate the Hermes data directory (profiles, sessions, eikons, etc.).
# Default: ~/.hermes
# HERMES_HOME=/path/to/alt-hermes-home

# Override the hermes-agent source tree location.
# Default: $HERMES_HOME/hermes-agent
# HERMES_AGENT_ROOT=/path/to/hermes-agent

# Python interpreter for the gateway subprocess.
# Default: tries $VIRTUAL_ENV → <root>/venv → <root>/.venv → python3
# HERMES_PYTHON=/usr/bin/python3

# Relocate Herm's own prefs and input history.
# Default: $HERMES_HOME/herm
# HERM_CONFIG_DIR=/path/to/alt-herm-config

The .env auto-load behavior is provided by Bun, not by Herm itself. If you run Herm through a different Node package runner, .env loading depends on that runner’s own behavior.

Do not commit a .env file that contains real credentials or sensitive paths to a public repository. The example above shows all variables commented out for safety: uncomment only the ones you actually need.

Get Started

Core Features

Eikon Avatars

Customization

Plugins

Troubleshooting

Herm configuration

Environment variables

Where Herm stores preferences

Using a `.env` file

​Environment variables

​Where Herm stores preferences

​Using a .env file

​Related docs

Environment variables

Where Herm stores preferences

Using a `.env` file

Related docs