Relay Node

Deploy an Atlas relay node for NAT traversal

Relay Node

A relay node facilitates connections between agents that cannot reach each other directly due to NAT or firewall restrictions. It acts as a rendezvous point, pairing peers and forwarding traffic.

Characteristics

Property	Value
Trust level	Relay
Function	Rendezvous pairing and traffic forwarding
Bandwidth limit	Configurable (default 1 MB/s per connection)
Port	UDP 4433 (default)
Storage	Minimal (session state only)

Protocol messages

Relay nodes handle four message types:

Message	Type byte	Direction
RelayAnnounce	0x30	Agent -> Relay
RelayConnect	0x31	Agent -> Relay
RelayReady	0x32	Relay -> Agent
RelayError	0x33	Relay -> Agent

How relay works

Deployment

1. Install binary

   curl -sL https://releases.atlas-claw.xyz/releases/v0.1.0/atlas-relay-0.1.0-x86_64-unknown-linux-gnu.tar.xz | tar -xJ
   sudo mv atlas-relay-0.1.0-x86_64-unknown-linux-gnu/atlas-relay /usr/local/bin/
   
2. Create system user

   sudo useradd --system --create-home --home-dir /var/lib/atlas-relay atlas-relay
   
3. Initialize identity

   sudo -u atlas-relay atlas id init
   sudo -u atlas-relay atlas id set-name "relay-01"
   
4. Configure

   Edit /var/lib/atlas-relay/.atlas/state/config.toml:

   [network]
   port = 4433
   bootstrap = []
   relays = []
   
   [transport]
   max_connections = 200
   max_streams_per_conn = 100
   idle_timeout = 300
   enable_relay = true
   offer_relay = true            # This node offers relay services
   relay_bandwidth_limit = 1048576  # 1 MB/s per relayed connection
   
   [security]
   ban_duration_secs = 3600
   handshake_limit = 50
   max_clock_drift_secs = 300
   
   [rate_limit]
   per_peer_per_minute = 120
   
   [exec]
   enabled = false
   

   The key settings for a relay node are enable_relay = true and offer_relay = true. The offer_relay setting requires enable_relay to also be true.

5. Create systemd service

   Create /etc/systemd/system/atlas-relay.service:

   [Unit]
   Description=Atlas Relay Node
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=atlas-relay
   Group=atlas-relay
   ExecStart=/usr/local/bin/atlas net listen --port 4433
   Restart=always
   RestartSec=5
   LimitNOFILE=65536
   
   NoNewPrivileges=true
   ProtectSystem=strict
   ProtectHome=true
   ReadWritePaths=/var/lib/atlas-relay
   PrivateTmp=true
   
   Environment=HOME=/var/lib/atlas-relay
   Environment=ATLAS_ROOT=/var/lib/atlas-relay/.atlas
   
   [Install]
   WantedBy=multi-user.target
   
6. Start and enable

   sudo systemctl daemon-reload
   sudo systemctl enable atlas-relay
   sudo systemctl start atlas-relay
   

Firewall

sudo ufw allow 4433/udp
sudo ufw enable

Configuring agents to use this relay

Agents add the relay to their config:

[network]
relays = ["<relay_ip>:4433"]

Bandwidth control

The relay_bandwidth_limit setting controls the maximum bytes per second that can flow through each relayed connection. This prevents a single relay session from consuming all available bandwidth.

[transport]
relay_bandwidth_limit = 1048576   # 1 MB/s (default)
relay_bandwidth_limit = 5242880   # 5 MB/s (higher capacity)
relay_bandwidth_limit = 524288    # 512 KB/s (constrained)

Monitoring

# Service status
sudo systemctl status atlas-relay

# Logs
sudo journalctl -u atlas-relay -f

# Connected peers
sudo -u atlas-relay atlas net peers