Skip to main content
Mole on the move

Quick Start

This guide walks you through manually setting up a Muti Metroo agent with full control over the configuration.

Step 1: Initialize Agent Identity​

Each agent needs a unique identity. Create one:

muti-metroo init -d ./data

This generates a 128-bit Agent ID stored in ./data/agent_id:

Agent ID: a1b2c3d4e5f6789012345678901234ab
tip

Save this Agent ID - you will need it when connecting other agents to this one.

Step 2: Generate TLS Certificates​

All peer connections require TLS. Generate a Certificate Authority and agent certificates:

# Create Certificate Authority
muti-metroo cert ca -n "My Mesh CA" -o ./certs

# Generate agent certificate
muti-metroo cert agent -n "agent-1" \
  --dns "agent1.example.com" \
  --ip "192.168.1.10" \
  -o ./certs

# Verify the certificate
muti-metroo cert info ./certs/agent.crt

Output files:

  • ./certs/ca.crt - CA certificate (share with peers)
  • ./certs/ca.key - CA private key (keep secure!)
  • ./certs/agent.crt - Agent certificate
  • ./certs/agent.key - Agent private key
warning

Keep ca.key secure. Anyone with access to it can create valid certificates for your mesh.

Step 3: Create Configuration File​

Create config.yaml with your agent settings:

# Agent identity
agent:
  id: "auto"                    # Uses ID from data directory
  display_name: "My First Agent"
  data_dir: "./data"
  log_level: "info"
  log_format: "text"

# Listen for peer connections
listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

# SOCKS5 proxy (ingress role)
socks5:
  enabled: true
  address: "127.0.0.1:1080"

# HTTP API (health checks, metrics)
http:
  enabled: true
  address: ":8080"

# Control socket for CLI
control:
  enabled: true
  socket_path: "./data/control.sock"

Step 4: Run the Agent​

Start your agent:

muti-metroo run -c ./config.yaml

You should see output like:

INFO  Starting Muti Metroo agent
INFO  Agent ID: a1b2c3d4e5f6789012345678901234ab
INFO  QUIC listener started on 0.0.0.0:4433
INFO  SOCKS5 server started on 127.0.0.1:1080
INFO  HTTP server started on :8080
INFO  Agent ready

Step 5: Verify the Agent​

In another terminal, test your agent:

# Check health
curl http://localhost:8080/health
# Output: OK

# Get detailed status
curl http://localhost:8080/healthz
# Output: {"status":"healthy","agent_id":"a1b2c3d4...","peers":0,"streams":0,"routes":0}

# View metrics
curl http://localhost:8080/metrics | head -20

Step 6: Test SOCKS5 Proxy​

With no exit routes configured, SOCKS5 connections will fail with "no route". But you can verify the proxy is working:

# This will fail with "no route to host" - that is expected!
curl -x socks5://localhost:1080 https://example.com

# Error: Connection refused (no exit node configured)

To actually proxy traffic, you need to either:

  1. Enable exit on this agent (see Exit Routing)
  2. Connect to another agent that has exit enabled

Adding Exit Capability​

To make this agent also serve as an exit node, add to your config.yaml:

# Exit node configuration
exit:
  enabled: true
  routes:
    - "0.0.0.0/0"          # Advertise default route
  dns:
    servers:
      - "8.8.8.8:53"
      - "1.1.1.1:53"
    timeout: 5s

Restart the agent:

# Stop with Ctrl+C, then restart
muti-metroo run -c ./config.yaml

Now test the proxy:

# Should work now!
curl -x socks5://localhost:1080 https://example.com

Configuration Summary​

Here is the complete configuration for a single agent acting as both ingress and exit:

agent:
  id: "auto"
  display_name: "All-in-One Agent"
  data_dir: "./data"
  log_level: "info"
  log_format: "text"

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

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

exit:
  enabled: true
  routes:
    - "0.0.0.0/0"
  dns:
    servers:
      - "8.8.8.8:53"
    timeout: 5s

http:
  enabled: true
  address: ":8080"

control:
  enabled: true
  socket_path: "./data/control.sock"

Next Steps​

Troubleshooting​

Agent won't start​

Check for common issues:

# Check if port is already in use
lsof -i :4433
lsof -i :1080
lsof -i :8080

# Check file permissions
ls -la ./data/
ls -la ./certs/

# Run with debug logging
muti-metroo run -c ./config.yaml --log-level debug

Certificate errors​

# Verify certificate
muti-metroo cert info ./certs/agent.crt

# Check certificate expiration
openssl x509 -in ./certs/agent.crt -text -noout | grep -A2 "Validity"

SOCKS5 connection refused​

  • Ensure SOCKS5 is enabled in config
  • Check the bind address (use 127.0.0.1 for local-only, 0.0.0.0 for network access)
  • Verify firewall rules

See Troubleshooting for more help.