Running Route6 in a Container

The container runs the same daemon as the bare-binary install: same MCP endpoint, same identity, same tools. Docker here is an install environment, not a connection method — most people take the binary, and this page is for environments that require a container.

The base compose file

services:
  r6me:
    image: route6me/netid:1.2.4
    container_name: r6me
    restart: unless-stopped
 
    environment:
      ROUTE6_API_KEY: "${ROUTE6_API_KEY:?set ROUTE6_API_KEY in .env}"
 
    ports:
      - "127.0.0.1:3000:3000"   # MCP        — point your agent here
      - "127.0.0.1:3001:3001"   # status API — `curl localhost:3001/status`
      - "127.0.0.1:1080:1080"   # egress proxy — SOCKS5 + HTTP CONNECT + plain HTTP
 
    extra_hosts:
      - "host.docker.internal:host-gateway"
 
    volumes:
      - r6me-state:/var/lib/r6me
 
volumes:
  r6me-state:

echo 'ROUTE6_API_KEY=sk_a6_your_key_here' > .env

docker compose up -d
curl -s localhost:3001/status

The volumes: entry is not optional either. It persists the agent's WireGuard key and applied config generation, so a restart resumes. Without it the agent re-registers every time the container restarts.

Connect your agent to MCP

Point any MCP client at http://localhost:3000/mcp. For example, Claude Desktop:

{
  "mcpServers": {
    "route6": { "url": "http://localhost:3000/mcp" }
  }
}

No API key here — the daemon already holds it.

Outbound: sending traffic from your agent's IP

Port 1080 is a proxy speaking SOCKS5, HTTP CONNECT and plain HTTP on one port. Anything you point at it leaves from your agent's own public address:

export http_proxy=http://127.0.0.1:1080
export https_proxy=http://127.0.0.1:1080
curl https://api64.ipify.org      # your agent's IPv6

IPv4-only destinations work too — the hub reaches them over NAT64.

For tools that speak SOCKS: ALL_PROXY=socks5h://127.0.0.1:1080.

Inbound: which machine answers a forward?

When you call port_forward { action: "create" }, Route6 accepts the connection on your public IPv6 at the gateway and relays it to your daemon. The daemon then has to connect to whatever is actually serving — and "localhost" inside a container means the container, where nothing is listening.

There are two topologies. They compose freely; you can use both at once.

Topology A — the service runs on your host

This is what extra_hosts: ["host.docker.internal:host-gateway"] is for. With it present, the daemon rewrites loopback forward targets to the host gateway address, so a forward whose target is localhost reaches your host.

# your service, on the host
python3 -m http.server 8080 --bind 0.0.0.0

Then, from your agent:

port_forward (action: create) { external_port: 28080, internal_port: 8080 }

forwards: dial target host.docker.internal:8600 failed:
  dial tcp 172.17.0.1:8600: connect: connection refused (hub will RST the visitor)

If extra_hosts is missing, the daemon says so at startup and leaves targets untranslated — your forwards then resolve inside the container, where nothing is listening:

container mode: no host gateway discoverable — loopback forward targets will NOT be
translated. Add extra_hosts: ["host.docker.internal:host-gateway"] to your compose,
or set R6ME_HOST_GATEWAY.

Topology B — the service runs in a sibling container

Use R6ME_FORWARD_TARGETS to say which container answers which forward. Each service keeps its own network — nothing gives up its network namespace, and nothing is published to the host.

services:
  r6me:
    image: route6me/netid:1.2.4
    container_name: r6me
    restart: unless-stopped
    environment:
      ROUTE6_API_KEY: "${ROUTE6_API_KEY:?}"
      # forward target port  ->  the container that answers it
      R6ME_FORWARD_TARGETS: "8080=api,9000=worker:3000"
    extra_hosts:
      - "host.docker.internal:host-gateway"   # any UNLISTED port still goes to the host
    volumes:
      - r6me-state:/var/lib/r6me
    ports:
      - "127.0.0.1:3000:3000"
    networks: [appnet]
 
  api:
    image: your/api          # listening on 8080
    networks: [appnet]
    environment:             # and its egress leaves from the agent's own address too
      http_proxy: "http://r6me:1080"
      https_proxy: "http://r6me:1080"
 
  worker:
    image: your/worker       # listening on 3000, reached as forward port 9000
    networks: [appnet]
 
networks:
  appnet:
 
volumes:
  r6me-state:

The syntax is "<port>=<host>[:<port>]", comma-separated:

Ports you do not list still resolve to the host, so host and sibling services mix freely. An IPv6 literal must be bracketed (8080=[fd00::2]:8080), the same rule URLs use.

A malformed entry is refused and logged at startup rather than guessed at — a wrong target is worse than a missing one, because it connects to the wrong service. Valid entries are echoed too, so docker logs r6me tells you exactly what the daemon believes:

R6ME_FORWARD_TARGETS: ignoring entry "notaport=x": "notaport" is not a port in 1-65535
forward target: port 8080 -> api
forward target: port 9000 -> worker:3000

Troubleshooting forwards

The failure mode worth naming: the forward is created and looks healthy, but every visitor hangs for about ten seconds and gets nothing. Nothing is wrong on the Route6 side — the daemon tried to reach a target that does not exist from inside the container.

docker logs r6me 2>&1 | grep 'forwards: dial target'

forwards: dial target host.docker.internal:8600 failed:
  dial tcp 172.17.0.1:8600: connect: connection refused (hub will RST the visitor)

curl -s localhost:3001/status | grep -A6 forwards

# Topology A — the host
docker run --rm --add-host host.docker.internal:host-gateway curlimages/curl \
  -sS -m 5 http://host.docker.internal:8080/
 
# Topology B — a sibling
docker run --rm --network <your_compose>_appnet curlimages/curl \
  -sS -m 5 http://api:8080/

ss -ltn | grep 8080

docker logs r6me 2>&1 | grep -E 'forward target|FORWARD_TARGETS'

forward target: port 8080 -> api
forward target: port 9000 -> worker:3000
R6ME_FORWARD_TARGETS: ignoring entry "notaport=x": "notaport" is not a port in 1-65535

Other things worth knowing

There is no shell in the image. docker exec has nothing to run. Inspect the agent from the host instead:

curl -s localhost:3001/status     # config generation, wg health, forwards, transport
docker logs r6me

Nothing listens on your public address. The container binds only container-local addresses; MCP, the status API and the proxy are reachable solely through the port mappings above. A port scan of your agent's public address shows only the forwards you deliberately created.

Upgrading. Bump the tag, then:

docker compose pull && docker compose up -d

The state volume means the agent resumes on the same identity — same WireGuard key, same config generation, no re-registration.