Configuration Overview
Decide which AGH file, overlay, or environment variable should change when you need to configure one machine, one workspace, one agent, or one skill.
- Audience
- Operators running durable agent work
- Focus
- Configuration guidance shaped for scanability, day-two clarity, and operator context.
Configuration is where AGH stops being generic and starts matching one machine, one workspace, one team default, or one agent role. The key to using this section well is choosing the right surface for the change you actually want.
Start with the decision table
| If you want to change... | Primary surface | Reach for this when... |
|---|---|---|
| Machine-wide defaults | ~/.agh/config.toml | The daemon, default provider, permissions mode, HTTP bind address, automation defaults, or marketplace trust should change for every workspace on one machine. |
| One workspace | <workspace>/.agh/config.toml | A repository needs different defaults, limits, or permissions than the rest of the machine. |
| One agent | AGENT.md | A specific agent needs a different prompt, provider, permission mode, or MCP attachment. |
| One agent's advertised capabilities | capability catalog next to AGENT.md | Other peers need outcome-oriented discovery metadata about what that agent can do. |
| One skill | SKILL.md | You are defining reusable instructions, optional MCP metadata, or skill-owned hooks. |
| MCP server configuration | mcp.json | MCP declarations are easier to manage as JSON sidecars than inline frontmatter. |
| Encrypted AGH-managed secrets | Vault | Store write-only vault:<namespace>/... values and inspect redacted metadata through CLI, HTTP, UDS, web, or session-scoped views. |
| Provider credentials | provider settings, credential_slots, or environment variables | Bind API-key providers to env: or encrypted vault:providers/<provider>/<slot> refs without exposing raw secrets in diagnostics. |
| Filesystem locations and precedence | file-locations reference | You need to know where AGH looks for agents, skills, sessions, memory, or overlays. |
Read in this order
- config.toml
- Vault
- File Locations
- AGENT.md
- Agent Capabilities
- SKILL.md
- mcp.json
- Environment Variables
That order mirrors how operators usually troubleshoot AGH: global defaults first, path resolution second, then file-format specifics and agent sidecars.
CLI Inspection and Mutation
Use agh config path before editing to confirm the selected global or workspace overlay. Prefer
agh config set <path> <value> for supported scalar and list settings because it writes through the
same validated persistence path as the settings API. Use agh config validate or its
agh config check alias after hand edits.
Inspection commands are redacted by default. agh config show, agh config list, and
agh config get <path> replace MCP and environment map values with [redacted] so copied
diagnostics do not leak runtime credentials.