Configuration Basics

This page lists all available configuration options for AgentHub.

Configuration File

AgentHub reads configuration from ~/.agenthub/config.toml by default.

Minimal Configuration

Start with this baseline for single-node usage:

safe_paths = [
  "/home/you/projects",
  "/home/you/sandboxes",
]

[server]
listen = "127.0.0.1:8080"

[worktree]
default_root = "/home/you/.agenthub/worktrees"

[history]
event_retention_days = 5
vacuum_on_cleanup = false

Complete Configuration Reference

Top-Level Options

Option	Type	Default	Description
`safe_paths`	array of strings	`["~/.agenthub/worktrees"]`	Allowed workdir roots
`web_dir`	string	`web/dist` (dev only)	Path to web assets
`log_path`	string	none	Log file path (default: stdout)

`[server]` Section

HTTP server configuration.

Option	Type	Default	Description
`listen`	string	`"127.0.0.1:8080"`	Bind address and port
`role`	string	`"main"`	Runtime role: `main` or `node`
`node_id`	string	`"main"` in `main` mode	Required non-`main` node identity when `role = "node"`

Distributed Node Example:

[server]
role = "node"
node_id = "gpu-01"

When role = "node", AgentHub starts only the node runtime surface. Public HTTP/UI routes are disabled, and internal_grpc.enabled must be true.

`[web]` Section

WebAuthn/Passkey configuration.

Option	Type	Default	Description
`rp_id`	string	`"localhost"`	Relying party ID for WebAuthn
`rp_origin`	string	`"http://localhost:8080"`	Origin for WebAuthn
`rp_name`	string	`"AgentHub"`	Display name for WebAuthn

Production WebAuthn Setup:

WebAuthn requires HTTPS and a valid origin:

[web]
rp_id = "agenthub.example.com"
rp_origin = "https://agenthub.example.com"
rp_name = "AgentHub Production"

`[worktree]` Section

Worktree creation settings.

Option	Type	Default	Description
`default_root`	string	`"~/.agenthub/worktrees"`	Base directory for new worktrees

`[codex_acp]` Section

ACP (Agent Control Protocol) provider settings.

Option	Type	Default	Description
`binary`	string	`"agenthub-codex-acp"`	ACP binary name or path
`default_mode`	string	`"auto"`	Default ACP mode (`auto`, `full`, `suggest`)
`multi_agent_enabled`	boolean	`true`	Force Codex ACP `Feature::Collab` on AgentHub-managed sessions

The built-in adapter path assumes the repository's current ACP baseline:

agenthub-codex-acp
official Codex 0.121.x

If you point codex_acp.binary at a custom binary, keep it compatible with the same ACP protocol surface before mixing it into a shared deployment.

`[history]` Section

Event history retention settings.

Option	Type	Default	Description
`event_retention_days`	integer	`5`	Days to keep events (0 = unlimited)
`vacuum_on_cleanup`	boolean	`false`	Run VACUUM after cleanup
`delete_batch_size`	integer	`10000`	Rows per cleanup batch (100-200000)

Retention Example:

[history]
# Keep events for 30 days
event_retention_days = 30
# Reclaim disk space after cleanup
vacuum_on_cleanup = true
# Smaller batches for lower I/O impact
delete_batch_size = 5000

`[push]` Section

Web Push notification settings.

Option	Type	Default	Description
`subject`	string	`"mailto:admin@example.com"`	VAPID contact email
`keys_path`	string	`"~/.agenthub/vapid.json"`	Path to VAPID keys

Push Configuration:

[push]
subject = "mailto:ops@company.com"
keys_path = "/etc/agenthub/vapid.json"

Push delivery still depends on a browser that supports service workers and the Push API. Outside localhost, use HTTPS.

`[internal_grpc]` Section

Internal gRPC control plane for remote nodes and actor CLI.

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable internal gRPC server
`listen`	string	`"127.0.0.1:50051"`	gRPC bind address

`[internal_grpc.security]` Subsection

Option	Type	Default	Description
`mode`	string	`"tls"`	Security mode: `tls`, `mtls`, or `disabled`
`cert_dir`	string	`"~/.agenthub/internal-grpc"`	TLS certificate directory

`[internal_grpc.auth]` Subsection

Option	Type	Default	Description
`shared_secret`	string	none	JWT signing secret
`issuer`	string	none	JWT issuer claim
`audience`	string	none	JWT audience claim

`[internal_grpc.bootstrap]` Subsection

Option	Type	Default	Description
`token`	string	none	Bootstrap token for token-based Agent Node join

This token is the primary Agent Node onboarding path. Operators copy it from the Agents page, configure it on the remote node, and then register the node's reachable grpc_target in the UI. QR onboarding is not used for Agent Nodes.

Complete Internal gRPC Example:

[server]
role = "node"
node_id = "node-east"

[internal_grpc]
enabled = true
listen = "0.0.0.0:50051"

[internal_grpc.security]
mode = "tls"
cert_dir = "/etc/agenthub/internal-grpc"

[internal_grpc.auth]
shared_secret = "your-256-bit-secret-here-minimum-32-chars"
issuer = "agenthub"
audience = "agenthub-internal"

[internal_grpc.bootstrap]
token = "bootstrap-token-for-remote-nodes"

`[proxy]` Section

HTTP proxy configuration.

Option	Type	Default	Description
`http`	string	none	HTTP proxy URL
`https`	string	none	HTTPS proxy URL
`all`	string	none	Proxy for all protocols

Proxy Example:

[proxy]
http = "http://proxy.company.com:8080"
https = "http://proxy.company.com:8080"

Environment Variables

All configuration options can be overridden via environment variables:

Environment Variable	Config Path
`AGENTHUB_LISTEN`	`server.listen`
`AGENTHUB_SAFE_PATHS`	`safe_paths` (comma-separated)
`AGENTHUB_WEB_DIR`	`web_dir`
`AGENTHUB_LOG_PATH`	`log_path`
`AGENTHUB_RP_ID`	`web.rp_id`
`AGENTHUB_RP_ORIGIN`	`web.rp_origin`
`AGENTHUB_RP_NAME`	`web.rp_name`
`AGENTHUB_CODEX_ACP_BINARY`	`codex_acp.binary`
`AGENTHUB_CODEX_ACP_DEFAULT_MODE`	`codex_acp.default_mode`
`AGENTHUB_HISTORY_EVENT_RETENTION_DAYS`	`history.event_retention_days`
`AGENTHUB_HISTORY_VACUUM_ON_CLEANUP`	`history.vacuum_on_cleanup`
`AGENTHUB_INTERNAL_GRPC_ENABLED`	`internal_grpc.enabled`
`AGENTHUB_INTERNAL_GRPC_LISTEN`	`internal_grpc.listen`
`AGENTHUB_INTERNAL_GRPC_SECURITY_MODE`	`internal_grpc.security.mode`
`AGENTHUB_INTERNAL_GRPC_CERT_DIR`	`internal_grpc.security.cert_dir`
`AGENTHUB_INTERNAL_GRPC_AUTH_SHARED_SECRET`	`internal_grpc.auth.shared_secret`
`AGENTHUB_INTERNAL_GRPC_AUTH_ISSUER`	`internal_grpc.auth.issuer`
`AGENTHUB_INTERNAL_GRPC_AUTH_AUDIENCE`	`internal_grpc.auth.audience`
`AGENTHUB_INTERNAL_GRPC_BOOTSTRAP_TOKEN`	`internal_grpc.bootstrap.token`
`AGENTHUB_HTTP_PROXY`	`proxy.http`
`AGENTHUB_HTTPS_PROXY`	`proxy.https`
`AGENTHUB_ALL_PROXY`	`proxy.all`
`AGENTHUB_VAPID_SUBJECT`	`push.subject`

Pyroscope Profiling

Continuous profiling is an operational opt-in and currently uses environment variables instead of ~/.agenthub/config.toml.

AgentHub starts a process-wide Pyroscope profiler only when all three variables are present with non-empty values:

PYROSCOPE_SERVER_ADDRESS
PYROSCOPE_BASIC_AUTH_USER
PYROSCOPE_BASIC_AUTH_PASSWORD

If only part of the configuration is present, AgentHub logs a warning and continues without profiling.

Example:

export PYROSCOPE_SERVER_ADDRESS="https://pyroscope.example.com"
export PYROSCOPE_BASIC_AUTH_USER="agenthub"
export PYROSCOPE_BASIC_AUTH_PASSWORD="super-secret"
agenthub

The current bootstrap uses the fixed application name agenthub.server.

Safe Paths

The safe_paths array defines which directories agents can access:

safe_paths = [
  "/home/you/projects",
  "/home/you/experiments",
  "/data/shared",
]

Important Notes:

~/.agenthub/worktrees is automatically included
All configured safe_paths are expanded (~ → $HOME)
Duplicate paths are deduplicated
Paths are validated at agent creation time

Configuration Validation

After updating configuration:

Restart AgentHub:

# If running as service
systemctl restart agenthub

# If running directly
pkill agenthub && agenthub

Verify Server Startup:
```
curl http://localhost:8080/
```

Test Configuration:

# Create a test agent
# Verify workdir validation works
# Test internal gRPC (if enabled)
agenthub actor inbox --actor-id test --limit 1

Production Configuration Example

# Production AgentHub Configuration
safe_paths = [
  "/var/agenthub/workspaces",
  "/data/repos",
]

[server]
listen = "0.0.0.0:8080"

[web]
rp_id = "agenthub.company.com"
rp_origin = "https://agenthub.company.com"
rp_name = "Company AgentHub"

[worktree]
default_root = "/var/agenthub/worktrees"

[history]
event_retention_days = 30
vacuum_on_cleanup = true
delete_batch_size = 5000

[push]
subject = "mailto:ops@company.com"

[internal_grpc]
enabled = true
listen = "0.0.0.0:50051"

[internal_grpc.security]
mode = "tls"
cert_dir = "/etc/agenthub/certs"

[internal_grpc.auth]
shared_secret = "change-me-to-256-bit-random-secret"
issuer = "agenthub"
audience = "agenthub-internal"

[proxy]
http = "http://proxy.company.com:8080"
https = "http://proxy.company.com:8080"

# Log to file for log rotation
log_path = "/var/log/agenthub/agenthub.log"

Troubleshooting

Config Changes Not Applied

Configuration is loaded at startup; restart required
Check file permissions on ~/.agenthub/config.toml
Verify TOML syntax is valid

Internal gRPC Connection Failures

Ensure shared_secret is explicitly set (not auto-generated)
Verify firewall allows traffic on gRPC port
Check TLS certificates exist in cert_dir

Path Validation Errors

Ensure paths in safe_paths exist and are readable
Remember that ~ is expanded to $HOME
Verify worktree directories are writable

Configuration File​

Minimal Configuration​

Complete Configuration Reference​

Top-Level Options​

[server] Section​

[web] Section​

[worktree] Section​

[codex_acp] Section​

[history] Section​

[push] Section​

[internal_grpc] Section​

[internal_grpc.security] Subsection​

[internal_grpc.auth] Subsection​

[internal_grpc.bootstrap] Subsection​

[proxy] Section​

Environment Variables​

Pyroscope Profiling​

Safe Paths​

Configuration Validation​

Production Configuration Example​

Troubleshooting​

Config Changes Not Applied​

Internal gRPC Connection Failures​

Path Validation Errors​