Configuration

Agent Harbor uses layered TOML configuration files with environment variable and CLI flag overrides. This provides flexibility for system-wide defaults, user preferences, and project-specific settings.

Configuration Precedence

Values are read in this order (highest to lowest priority):

CLI flags — --option value
CLI config file — --config <file>
Environment variables — AH_* prefix
Repo-user config — <repo>/.agents/config.user.toml
Repo config — <repo>/.agents/config.toml
User config — Platform-specific location
System config — Platform-specific location

File Locations

Linux

Scope	Path
System	`/etc/agent-harbor/config.toml`
User	`~/.config/agent-harbor/config.toml`
Repo	`<repo>/.agents/config.toml`
Repo-user	`<repo>/.agents/config.user.toml`

macOS

Scope	Path
System	`/Library/Application Support/agent-harbor/config.toml`
User	`~/Library/Application Support/agent-harbor/config.toml`
Repo	`<repo>/.agents/config.toml`
Repo-user	`<repo>/.agents/config.user.toml`

Windows

Scope	Path
System	`C:\ProgramData\agent-harbor\config.toml`
User	`%APPDATA%\agent-harbor\config.toml`
Repo	`<repo>\.agents\config.toml`
Repo-user	`<repo>\.agents\config.user.toml`

Example Configuration

User Configuration


# ~/.config/agent-harbor/config.toml
 
# Default agent for new tasks
default-agent = "claude"
 
# Preferred multiplexer
multiplexer = "tmux"
 
# TUI appearance
tui-font-style = "nerdfont"
 
# Logging
log-level = "info"
 
# Default snapshot provider
fs-snapshots = "auto"
 
# AgentFS settings (when using AgentFS)
overlay-materialization = "lazy"
 
# Default sandbox settings
[sandbox]
type = "local"
allow-network = false
allow-containers = false

Project Configuration

Create .agents/config.toml in your repository:


# .agents/config.toml (commit this)
 
# Project uses specific agent
default-agent = "claude"
 
# Use Git worktrees for this project
fs-snapshots = "git"
working-copy = "worktree"
 
# Sandbox settings for this project
[sandbox]
type = "local"
allow-network = true  # Project needs network for API calls
 
# Writable paths (package caches)
[sandbox.writable_paths]
paths = [
  "~/.cargo/registry",
  "~/.cache/pip",
  "node_modules"
]

Personal Project Overrides

Create .agents/config.user.toml for personal settings (add to .gitignore):


# .agents/config.user.toml (don't commit)
 
# Debug logging for development
log-level = "debug"
 
# Use my preferred model
claude-model = "sonnet"

Environment Variables

All configuration keys map to AH_ prefixed environment variables. Replace hyphens with underscores and use uppercase:


export AH_DEFAULT_AGENT="claude"
export AH_LOG_LEVEL="debug"
export AH_TUI_FONT_STYLE="nerdfont"
export AH_FS_SNAPSHOTS="zfs"
export AH_MULTIPLEXER="tmux"
export AH_SANDBOX_TYPE="local"
export AH_SANDBOX_ALLOW_NETWORK="true"

Common Options

General

Key	Description	Default
`default-agent`	Default agent type	—
`multiplexer`	Terminal multiplexer	auto
`ui`	Default UI (tui/webui)	tui
`log-level`	Log verbosity	info

Filesystem

Key	Description	Default
`fs-snapshots`	Snapshot provider	auto
`working-copy`	Workspace mode	auto
`overlay-materialization`	AgentFS mode	lazy

Sandbox

Key	Description	Default
`sandbox.type`	Sandbox type	disabled
`sandbox.allow-network`	Network access	false
`sandbox.allow-containers`	Container access	false
`sandbox.allow-kvm`	KVM access	false

TUI

Key	Description	Default
`tui-font-style`	Icon style	unicode

Options: unicode, nerdfont, ascii

CLI Commands

View Configuration


# Show all configuration
ah config show
 
# Show as JSON
ah config show --json
 
# Get specific value
ah config get default-agent

Set Configuration


# Set in user config
ah config set default-agent claude
 
# Set for current repo
ah config set --repo default-agent codex

Explain Value Source


ah config explain default-agent

Shows which file or environment variable provides the current value.

MCP Server Configuration

MCP servers can be configured in the config file or via a separate JSON file:

In config.toml


[[mcp-servers]]
name = "github"
transport = "stdio"
command = "mcp-server-github"
args = []
 
[[mcp-servers]]
name = "filesystem"
transport = "stdio"
command = "mcp-server-filesystem"
args = ["--root", "/path/to/project"]

Via Separate File


ah agent start --agent claude --mcp-config ~/.config/mcp-servers.json --prompt "Task"

See MCP Servers for detailed configuration.

Tips

Use Repo-User for Personal Preferences

Keep project config (config.toml) minimal and shareable. Put personal preferences in config.user.toml:


# Add to .gitignore
echo '.agents/config.user.toml' >> .gitignore

Debug Configuration Issues


# See where values come from
ah config explain fs-snapshots
 
# Show all with sources
ah config show --json | jq

Override for One Command


# Use different agent just for this run
ah agent start --agent codex --prompt "Task"
 
# Force specific snapshot provider
ah agent start --fs-snapshots git --prompt "Task"