How SeaWise Works

A technical overview of the SeaWise architecture for users who want to understand what's happening under the hood.

Architecture

┌─────────────────┐         ┌──────────────┐         ┌──────────┐
│  Your Server    │         │   SeaWise    │         │ Visitor  │
│                 │         │              │         │          │
│  ┌───────────┐  │ outbound│  ┌────────┐  │ HTTPS   │          │
│  │ SeaWise   │──┼────────>│  │ Relay  │<─┼─────────│ Browser  │
│  │ Client    │  │  TLS    │  │ Server │  │         │          │
│  └─────┬─────┘  │         │  └────────┘  │         └──────────┘
│        │        │         │              │
│  ┌─────▼─────┐  │         │  ┌────────┐  │
│  │ Your App  │  │         │  │ Web    │  │
│  │ (Plex,    │  │         │  │ Dash-  │  │
│  │  HA, etc) │  │         │  │ board  │  │
│  └───────────┘  │         │  └────────┘  │
└─────────────────┘         └──────────────┘

The Tunnel

The SeaWise client creates a persistent, encrypted tunnel from your server to SeaWise's relay servers. This tunnel is:

• Outbound-only — your server initiates the connection, not the other way around

• Encrypted — TLS protects all data in transit

• Persistent — the client maintains the connection and reconnects automatically if it drops

• Authenticated — each connection is verified with a cryptographic token

When a visitor accesses https://myapp.seawise.dev, the request flows:

1. Visitor's browser connects to SeaWise via HTTPS

2. SeaWise identifies the subdomain and finds the matching tunnel

3. The request is forwarded through the tunnel to your server

4. Your server responds through the same tunnel

5. SeaWise relays the response back to the visitor

Pairing

The pairing process uses the OAuth Device Authorization flow:

1. Client requests a pairing code from SeaWise

2. You enter the code on the SeaWise dashboard

3. Client polls for approval

4. Upon approval, the client receives authentication credentials

5. The client uses these credentials to establish the tunnel

Pairing codes expire after 10 minutes and can only be used once.

Heartbeat

The client sends a heartbeat to SeaWise every 30 seconds. This lets the dashboard show whether your server is online. If three consecutive heartbeats are missed (90 seconds), the server is marked offline.

Reconnection

If the connection drops (network change, server restart, etc.), the client automatically reconnects using exponential backoff — starting at 1 second and increasing to a maximum of 5 minutes between attempts.

Subdomains & DNS

Each service gets a subdomain on seawise.dev. DNS and TLS certificates are managed by SeaWise. You don't need to configure any DNS records.