Tuning tunnels

This guide covers the tunnel settings you'll want to adjust as you move toward production or debug specific connectivity scenarios. The defaults work well for getting started - tune these when you need more control.

Endpoint selection

The tunnel client chooses which Apoxy edge endpoint to connect to. Two strategies are available:

$terminalSH

apoxy tunnel run my-tunnel --endpoint-selection latency
apoxy tunnel run my-tunnel --endpoint-selection random

latency (default) - picks the endpoint with the lowest measured latency. Best for most workloads.
random - picks a random endpoint. Useful when you want to spread load or debug path diversity.

Start with latency. Switch to random only if you're investigating routing asymmetry or need to verify multiple edge paths.

Connection pooling

By default, the tunnel keeps one connection alive to the edge. Increase this for better resilience or higher throughput:

$terminalSH

apoxy tunnel run my-tunnel --min-conns 3

More connections means:

Faster failover if one connection drops.
Higher aggregate throughput for parallel requests.
More resources consumed on both ends.

Connections are spread across relay replicas automatically: a relay that already holds one of your agent's connections asks later connections to re-dial, so they land on a different replica behind the same address whenever one is available. This makes --min-conns 2+ resilient to a single relay restarting: traffic keeps flowing over the surviving connection while the dropped one reconnects. When only one replica is reachable, all connections still establish there after a few quick re-dials.

For production workloads, --min-conns 2 or 3 is a good starting point. For development or low-traffic scenarios, 1 is fine.

Kernel vs user mode

The tunnel client supports two modes:

$terminalSH

apoxy tunnel run my-tunnel --mode user    # default
apoxy tunnel run my-tunnel --mode kernel

user mode runs entirely in userspace using a SOCKS proxy and DNS proxy. No special privileges needed.
kernel mode creates a TUN device and routes traffic at the OS level. Requires NET_ADMIN capability and access to /dev/net/tun.

Use user mode unless you need transparent network-level tunneling (e.g., routing all traffic from a machine through the tunnel without application changes).

Every project includes a VPCNetwork named default. You can update its configuration, but the project API rejects deletion. Create additional networks when you need separate routing or key domains.

The VPC tunnel agent (alpha) attaches to that default network when you omit --vpc and generates a Docker-style tunnel name when you omit --name. It has the same mode split via --tun:

$terminalSH

apoxy alpha tunnel run                          # userspace + SOCKS (default)
apoxy alpha tunnel run --tun                    # kernel TUN device
apoxy alpha tunnel run --name branch --vpc corp # explicit tunnel and VPC

With --tun, any process in the same network namespace reaches overlay destinations by plain kernel route - no SOCKS configuration. Linux only; requires NET_ADMIN and /dev/net/tun. --tun-ifname overrides the interface name (default apoxy0).

In an interactive terminal, the alpha agent keeps one status line per requested connection. For example, apoxy alpha tunnel run --min-conns 2 displays:

$terminalTXT

✓ tunnel  focused-turing (generated)
✓ vpc     default

→ resolving nearest edges
Connections 0/2

As connections come up, that frame becomes:

$terminalTXT

✓ resolved nearest edges
Connections 2/2
  EDGE         STATUS       LATENCY UP        TX         RX
✓ us-west-2    connected    3 ms    00:18     12.0 KiB   84.0 KiB
✓ us-west-1    connected    9 ms    00:18     8.0 KiB    41.0 KiB

Connections have no primary or failover designation. The display updates latency, uptime, and traffic counters for each connection independently. Pass --no-tui to use transition-only text output; non-interactive output selects that format automatically.

DNS proxy

In user mode, the tunnel runs a DNS proxy that resolves tunnel-routed names:

$terminalSH

apoxy tunnel run my-tunnel --dns-addr 127.0.0.1:8053

The default is 127.0.0.1:8053. Make sure whatever consumes DNS in your setup (your application, a local resolver, or the backplane) points at this address.

SOCKS proxy

The tunnel also exposes a SOCKS5 proxy for application-level routing:

$terminalSH

apoxy tunnel run my-tunnel --socks-addr localhost:1080

Applications can use this to route specific traffic through the tunnel without kernel-level routing. The default is localhost:1080.

Health and metrics

The alpha VPC tunnel agent does not open an admin port by default. Enable one when your process manager or monitoring system needs it:

$terminalSH

apoxy alpha tunnel run \
  --min-conns 2 \
  --admin-addr 127.0.0.1:18080

The listener provides:

/livez - returns success while the agent process is running.
/readyz - returns success when the requested number of connections is active.
/metrics - exposes Prometheus metrics for the agent and its tunnel connections.

Choose an address and port that do not conflict with your application. Tunnel peers cannot reach the admin listener through the VPC overlay. Bind an underlay address instead of 127.0.0.1 only when a separate monitoring host must connect to it. Existing automation can still use the deprecated --health-addr alias while it moves to --admin-addr.

The original tunnel client uses separate health and metrics listeners:

$terminalSH

apoxy tunnel run my-tunnel \
  --health-addr :8080 \
  --metrics-addr :8081

Set different ports when these defaults conflict with your application.

Non-interactive mode

When running in CI, containers, or systemd units, disable the TUI:

$terminalSH

apoxy tunnel run my-tunnel --no-tui

The TUI is helpful for interactive debugging but unnecessary in automation.

Skipping TLS verification

For development environments with self-signed certificates:

$terminalSH

apoxy tunnel run my-tunnel --insecure-skip-verify

Never use this in production.

Putting it together

A production-ready tunnel invocation might look like:

$terminalSH

apoxy tunnel run my-tunnel \
  --mode user \
  --min-conns 2 \
  --endpoint-selection latency \
  --health-addr :8080 \
  --metrics-addr :8081 \
  --no-tui

For the full list of flags, see the CLI reference.