Configuration Reference

Control every aspect of your agent through a single YAML file. Start with the minimal config and add sections as you need them.

Quick Reference

I want to...	Section
Set agent name and logging	Agent
Accept incoming connections	Listeners
Connect to other agents	Peers
Create a SOCKS5 proxy	SOCKS5
Route traffic to destinations	Exit
Publish mesh-local hostnames	Hosts
Set up port forwarding	Forward
Enable UDP relay	UDP
Enable ICMP ping	ICMP
Configure sleep mode	Sleep
Enable management commands	Management Commands
Enable file transfer	File Transfer
Configure HTTP API	HTTP
Tune route propagation	Routing
Persist runtime CLI changes	Dynamic Config Persistence
Encrypt mesh topology	Management
Set up TLS certificates	TLS Certificates
Use secrets from environment	Environment Variables

Configuration File

Muti Metroo uses YAML configuration files. The default location is ./config.yaml, but you can specify a different path:

muti-metroo run -c /path/to/config.yaml

Minimal Configuration

The simplest working configuration:

agent:
  data_dir: "./data"

listeners:
  - transport: quic
    address: ":4433"

socks5:
  enabled: true
  address: "127.0.0.1:1080"

exit:
  enabled: true
  routes:
    - "0.0.0.0/0"

http:
  enabled: true
  address: ":8080"

TLS certificates are auto-generated at startup. See TLS Certificates for custom certificate setup.

Full Example

See configs/example.yaml for a fully commented configuration file with all options.

Configuration Sections

Core

Section	Purpose	Documentation
agent	Agent identity, logging	Agent
tls	Global TLS settings	TLS Certificates
listeners	Accept peer connections	Listeners
peers	Connect to other agents	Peers

Ingress

Section	Purpose	Documentation
socks5	SOCKS5 proxy	SOCKS5
forward.listeners	Port forward listeners	Forward

Exit

Section	Purpose	Documentation
exit	CIDR and domain routes	Exit
mesh_hosts	Mesh-local hostname registry	Hosts
forward.endpoints	Port forward endpoints	Forward
udp	UDP relay	UDP
icmp	ICMP ping	ICMP

Remote Access

Section	Purpose	Documentation
shell	Remote command execution	Shell
file_transfer	File upload/download	File Transfer

HTTP API

Section	Purpose	Documentation
http	Health, dashboard, APIs	HTTP

Tuning

Section	Purpose	Documentation
routing	Route advertisement	Routing
connections	Keepalive, reconnection	Routing
limits	Stream limits, buffers	Routing

Sleep

Section	Purpose	Documentation
sleep	Mesh hibernation mode	Sleep

Runtime State

Section	Purpose	Documentation
agent.data_dir	Persist runtime peer/forward/route/display-name changes across restarts	Dynamic Config Persistence

Security

Section	Purpose	Documentation
management	Topology encryption	Management
protocol	Protocol identifiers	TLS Certificates

Environment Variables

All configuration values support environment variable substitution:

agent:
  data_dir: "${DATA_DIR:-./data}"
  log_level: "${LOG_LEVEL:-info}"

socks5:
  auth:
    users:
      - username: "${SOCKS_USER}"
        password_hash: "${SOCKS_PASS_HASH}"

Syntax:

• ${VAR} - Use environment variable (kept as literal if not set)
• ${VAR:-default} - Use default if variable not set

See Environment Variables for more details.

Validation

Configuration is validated on startup. Common errors:

ERROR  Invalid configuration: socks5.address: invalid address format
ERROR  Invalid configuration: listeners[0].tls.cert: file not found
ERROR  Invalid configuration: peers[0].id: invalid agent ID format

Reloading

Configuration cannot be reloaded without restart. To apply changes:

# Stop agent (Ctrl+C or SIGTERM)
# Edit config.yaml
# Start agent
muti-metroo run -c ./config.yaml

Best Practices

1. Use environment variables for secrets (passwords, keys)
2. Keep configs in version control (without secrets)
3. Use display_name for easier dashboard identification
4. Start minimal and add features as needed
5. Test configuration before production deployment

Embedded Configuration

For single-file deployments, configuration can be embedded in the binary:

# When running embedded binary without arguments
default_action: run # Auto-start agent
# default_action: help # Show help (default)

The setup wizard can create embedded binaries:

muti-metroo setup
# Choose "Embed in binary" for configuration delivery

See Embedded Configuration for details.

Next Steps

• Agent Configuration - Identity and logging
• Listeners - Transport setup
• Peers - Connecting to other agents
• Getting Started - First-time setup