Tunnel Control API

The tunnel control API exposes simple endpoints to manage the Cloudflare Quick Tunnel sidecar. All routes require an authenticated session or bearer token.

Endpoints

Method	Path	Description
GET	/api/tunnel/status	Returns current hostname, uptime, and version
POST	/api/tunnel/restart	Requests a container restart

Example response

GET /api/tunnel/status

{
  "hostname": "https://example.trycloudflare.com",
  "uptime_seconds": 864,
  "restart_count": 3,
  "updated_at": "2025-03-20T09:42:16Z"
}

A restart returns HTTP 202 and enqueues the operation. Check status again to confirm the new hostname.

Permissions

LinkPeek verifies the caller against the admin session and ensures CLOUDFLARED_ENABLED=1. If the sidecar is disabled, both routes return HTTP 503.

Failure modes

• 409 Conflict: A restart is already in progress.
• 500 Internal Server Error: Docker socket access failed. Confirm the compose service mounts /var/run/docker.sock.
• 504 Gateway Timeout: Cloudflared did not report a new hostname within the configured window.

Log entries for each API call appear in log.event. Combine these endpoints with the Tunnel Monitor guide for a full operational view.