Tunnel System

How Tunnels Work

Katachi uses Cloudflare Tunnel to create a secure connection between your machine and the Katachi backend — without opening any inbound ports.

sequenceDiagram
    participant M as Your Machine
    participant C as Cloudflare
    participant B as Katachi Backend

    M->>C: Outbound HTTPS (port 443)
    B->>C: Request for agent
    C->>M: Forward request via tunnel
    M->>C: Tunnel response
    C->>B: Forward to backend

Key Points

• No inbound ports — The agent initiates all connections outbound
• No static IP needed — Works behind NAT, firewalls, and dynamic IPs
• Cloudflare’s network — Traffic is routed through Cloudflare’s global edge for low latency
• Automatic reconnection — Handles connection drops and reconnects gracefully

Tunnel Lifecycle

Provisioning

When you run katachi start for the first time:

1. Agent authenticates with the backend via device flow
2. Backend provisions a secure tunnel via Cloudflare’s API
3. Encrypted tunnel credentials are returned and stored locally
4. The tunnel client starts and establishes the connection

Active Connection

While the agent is running:

• The tunnel client maintains a persistent connection to Cloudflare’s edge
• The backend periodically checks tunnel health via heartbeats
• The web UI shows the agent as “online” when the tunnel is active

Deregistration

When you run katachi unregister:

1. Agent sends an authenticated request to the backend
2. Backend cleans up the tunnel from its records and from Cloudflare
3. Agent removes local encrypted credentials

Included Binary

The Katachi agent ships with a pinned, integrity-verified cloudflared binary. This ensures:

• Version consistency — All agents use the same tested version
• Integrity — Checksum verification prevents tampered binaries
• Zero setup — No manual cloudflared installation needed

The binary is downloaded automatically during npm install.