Agent on Docker

Run

docker run -d --name towonel-agent \
  --network host \
  -e TOWONEL_INVITE_TOKEN=tt_inv_2_... \
  -e TOWONEL_AGENT_SERVICES='[
    {"hostname":"app.example.dev","origin":"127.0.0.1:8080"}
  ]' \
  codeberg.org/towonel/towonel-agent:latest

--network host lets the agent reach services on the host. Drop it when all origins live on a docker network.

TCP and UDP

-e TOWONEL_AGENT_TCP_SERVICES='[
  {"name":"ssh","origin":"127.0.0.1:22","listen_port":2222}
]'
-e TOWONEL_AGENT_UDP_SERVICES='[
  {"name":"wireguard","origin":"127.0.0.1:51820","listen_port":51820}
]'

docker-compose

services:
  towonel-agent:
    image: codeberg.org/towonel/towonel-agent:latest
    network_mode: host
    restart: unless-stopped
    environment:
      RUST_LOG: info
      TOWONEL_INVITE_TOKEN: ${TOWONEL_INVITE_TOKEN}
      TOWONEL_AGENT_SERVICES: |
        [{"hostname":"app.example.dev","origin":"127.0.0.1:8080"}]

Health and metrics

GET /healthz and GET /metrics on 127.0.0.1:9090. Set TOWONEL_AGENT_HEALTH_LISTEN_ADDR=0.0.0.0:9090 to expose externally.

Relay

--network host exposes the host’s iroh UDP socket, so direct paths usually work. The hub serves a relay URL via bootstrap; set TOWONEL_AGENT_RELAY_URL only to override it. See Relay.