Configuration

Directory layout

~/.steerholm/
├── config.json
└── policies/
    ├── coding-agent.json
    └── research-agent.json

%APPDATA%\steerholm\
├── config.json
└── policies\
    ├── coding-agent.json
    └── research-agent.json

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:

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

{
  "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`)

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
`key_prefix`	`string`	First 15 chars of the access key (display only)

Defaults

Setting	Value
Host	`127.0.0.1`
Port	`4767`

Getting Started

Guides

Concepts

Reference

Directory layout

File permissions

config.json

Server fields

Agent fields

Defaults

​Directory layout

​File permissions

​config.json

​Server fields

​Agent fields

​Defaults

Directory layout

File permissions

config.json

Server fields

Agent fields

Defaults