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

# Configuration

> Config files, directory layout, and platform support.

## Directory layout

<CodeGroup>
  ```bash Linux / macOS theme={null}
  ~/.steerholm/
  ├── config.json
  └── policies/
      ├── coding-agent.json
      └── research-agent.json
  ```

  ```bash Windows theme={null}
  %APPDATA%\steerholm\
  ├── config.json
  └── policies\
      ├── coding-agent.json
      └── research-agent.json
  ```
</CodeGroup>

Access-key hashes are stored in the system keyring, not in config files.

Set `STEERHOLM_CONFIG_DIR` to override the config directory (both the CLI and
the daemon read it) — useful for isolated setups or testing:

```bash theme={null}
STEERHOLM_CONFIG_DIR=/tmp/steerholm-test holm list servers
```

## File permissions

The config directory and files are created **owner-only** — `0700` on
`~/.steerholm` and its `policies/` directory, and `0600` on `config.json` and each
policy file — so `--env` secrets, agent policies, and grants aren't readable by
other users on the machine. Steerholm re-applies these permissions on startup, so
an existing install is tightened automatically after an upgrade. On Windows,
per-user `AppData` already provides this isolation via ACLs.

## config.json

```json theme={null}
{
  "servers": {
    "git": {
      "name": "git",
      "command": "uvx mcp-server-git",
      "server_type": "stdio"
    },
    "remote-api": {
      "name": "remote-api",
      "url": "http://localhost:8000/mcp",
      "server_type": "http"
    }
  },
  "agents": {
    "coding-agent": {
      "name": "coding-agent",
      "key_prefix": "steer_sk_A7x..."
    }
  }
}
```

### Server fields

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Unique identifier |
| `command` | `string` | Full launch command (stdio servers) |
| `url` | `string` | Server URL (HTTP servers) |
| `env` | `object` | Extra environment variables passed to a stdio server |
| `server_type` | `"stdio"` or `"http"` | Transport type (inferred from `--command` or `--url`) |

<Note>
  Set `env` from the CLI: `holm add server <name> --command "..." --env KEY=VALUE`
  (repeatable). It's stored here in `config.json`, and `holm show server` masks the
  values so secrets don't print back.

  **Variable names** must be letters, digits, `_`, `-`, or `.`, and can't start
  with a digit — the same rule Kubernetes and Docker use, so a config stays
  portable across Linux, macOS, and Windows. Values are unrestricted (they may
  contain `=`, spaces, or anything else); only the name is validated, and repeating
  a name is an error.
</Note>

### Agent fields

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Unique identifier |
| `key_prefix` | `string` | First 15 chars of the access key (display only) |

## Defaults

| Setting | Value |
| - | - |
| Host | `127.0.0.1` |
| Port | `4767` |