Configuration

Directory layout

~/.steerholm/
├── config.json
├── control-token           # the CLI's credential for the running daemon
├── events-000001.jsonl     # audit log (rotated)
├── events-000002.jsonl
├── update-check.json       # cached "update available" check
├── daemon.log              # macOS: the daemon's output (Linux: the systemd journal)
├── migrations/
│   └── version             # the schema this state is in
├── .pre-migration/         # after an upgrade: the state as it was before it
└── policies/
    ├── agt_9f2a1c4e7b3d05a1.json
    └── agt_5c30bb81f6e2d94a.json

%APPDATA%\steerholm\
├── config.json
├── events-000001.jsonl
├── events-000002.jsonl
├── update-check.json
├── daemon.log
├── migrations\
│   └── version
├── control-token
├── .pre-migration\
└── policies\
    ├── agt_9f2a1c4e7b3d05a1.json
    └── agt_5c30bb81f6e2d94a.json

config.json holds the bcrypt hash of each agent’s access key. A hash verifies a key; it cannot be turned back into one, and the raw key is shown once at creation and never stored. control-token holds the credential the CLI uses to talk to a running daemon — stored raw, because the CLI has to present it, and owner-only like everything else here. The daemon creates it when it first starts, so it is absent until then. .pre-migration is the state as it was before the last upgrade changed its format — see Upgrading. Set STEERHOLM_CONFIG_DIR to override the config directory (both the CLI and the daemon read it) — useful for isolated setups or testing:

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, each policy file, and each audit log file — so --env secrets, agent policies, grants, and recorded activity 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

{
  "servers": {
    "git": {
      "name": "git",
      "id": "srv_654dfec363cf7f7b",
      "command": "uvx mcp-server-git",
      "server_type": "stdio"
    },
    "remote-api": {
      "name": "remote-api",
      "id": "srv_0d83f6b1ce49a27f",
      "url": "http://localhost:8000/mcp",
      "server_type": "http"
    }
  },
  "agents": {
    "coding-agent": {
      "name": "coding-agent",
      "id": "agt_9f2a1c4e7b3d05a1",
      "key_prefix": "steer_sk_A7x...",
      "key_hash": "$2b$12$..."
    }
  },
  "audit": {
    "max_files": 5,
    "max_age_days": 0
  }
}

Top-level fields

Field	Type	Description
`servers`	`object`	Added servers, keyed by name
`agents`	`object`	Registered agents, keyed by name
`audit`	`object`	Audit-log retention

Server fields

Field	Type	Description
`name`	`string`	Unique identifier; reusable once a server is removed
`id`	`string`	Immutable id, minted at creation and kept across `holm modify server`. Grants point at this, not at the name
`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`)

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.

Agent fields

Field	Type	Description
`name`	`string`	Unique identifier; reusable once an agent is removed
`id`	`string`	Immutable id, minted at creation and kept across key rotation. Names the agent’s policy file, and grants point at this rather than the name
`key_prefix`	`string`	First 15 chars of the access key (display only)
`key_hash`	`string`	bcrypt hash of the access key — verifies a key, cannot be turned back into one

The id is what distinguishes two agents that have shared a name — the audit log records it, and holm log --agent <id> isolates one of them.

Audit fields

Field	Type	Description
`max_files`	`number`	How many audit log files to keep (`0` = no limit)
`max_age_days`	`number`	Delete log files older than this (`0` = no limit)

Set these with holm log set --max-files N --max-age-days N; a running daemon picks them up without a restart. Segment size is fixed at 10 MB.

Defaults

Setting	Value
Host	`127.0.0.1`
Port	`4767`
Audit log files kept	`5` (10 MB each, so a 50 MB ceiling)
Audit log max age	none

Getting Started

Guides

Concepts

Reference

Directory layout

File permissions

config.json

Top-level fields

Server fields

Agent fields

Audit fields

Defaults

​Directory layout

​File permissions

​config.json

​Top-level fields

​Server fields

​Agent fields

​Audit fields

​Defaults

Directory layout

File permissions

config.json

Top-level fields

Server fields

Agent fields

Audit fields

Defaults