Tunnel Monitor

The tunnel monitor tracks the Cloudflare Quick Tunnel sidecar that exposes LinkPeek to remote browsers and bots. It surfaces hostname status, restart controls, and logs so you can spot regressions quickly.

Understand the layout

Hostname banner: Displays the active .trycloudflare.com address or your custom domain if provided via environment variables.
Health chip: Signals the last heartbeat from the Cloudflared container with green/amber/red states based on uptime.
Log stream: Mirrors the sidecar logs to help you diagnose TLS handshakes, rate limits, or blocked origins.

Trigger a restart

Use the restart control when the tunnel hangs or when rotating credentials:

Open Tunnel → Restart tunnel.
Confirm the modal prompt. LinkPeek calls /api/tunnel/restart.
Watch the banner for the new hostname and verify that the health chip returns to green.

The command delegates to the Cloudflare container via Docker socket access. Ensure the Compose stack grants the sidecar permission to restart itself (/var/run/docker.sock mount).

Configure environment variables

Variable	Effect
`CLOUDFLARED_ENABLED`	Enables the sidecar and UI tile. Defaults to `1`.
`CLOUDFLARED_TOKEN`	Optional; use when binding the tunnel to a named route.
`PUBLIC_BASE_URL`	Overrides the hostname displayed in the dashboard banner

Set these values in your .env before booting the Compose stack so the restart API can resolve the correct container name.

Troubleshooting tips

If restarts fail, confirm the linkpeek container user has permission to access the Docker socket.
When the hostname field is blank, check that the sidecar emits your url is: in the logs—LinkPeek watches for this line.
For production tunnels, prefer named Cloudflare routes. Quick Tunnel hostnames may rotate unexpectedly during maintenance events.

Automation hooks

Subscribe to the tunnel.status realtime topic to stream tunnel heartbeats to your monitoring stack. The payload includes uptime seconds, the hostname, and the restart counter so you can alert on flapping tunnels.