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

# Herm configuration

> Environment variables Herm reads, local preference paths, and when to use overrides.

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:

```text theme={null}
$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:

```bash .env theme={null}
# 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
```

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## Related docs

* [Quickstart](/quickstart)
* [Config tab](/features/config)
* [Common issues](/troubleshooting/common-issues)