Skip to main content
The Lukan Relay enables secure remote access to your local Lukan agent from any browser, using end-to-end encryption with X25519 + AES-GCM.

​
Architecture

The relay acts as a message broker between:
  1. Browser client - Connects via WebSocket (/ws/client) with JWT cookie auth
  2. Local daemon - Connects via WebSocket (/ws/daemon) and registers the device
The relay cannot read the content of encrypted messages (E2E encryption).

​
Authentication

​
Login

lukan login                      # Authenticate with Relay (browser-based)
lukan login --remote             # Remote/headless authentication (device code flow)

​
Logout

lukan logout                     # Disconnect from Relay

​
Status

lukan relay status               # Show relay connection status
lukan relay disconnect           # Disconnect active relay session

​
Authentication Methods

​
Google OAuth

Browser-based OAuth flow with CSRF protection via single-use nonce state parameter.

​
Device Code Flow

For headless environments (Docker, servers, CI/CD):
  1. POST /auth/device - Start device code flow, get a user code
  2. User visits verification URL and enters the code
  3. POST /auth/device/poll - CLI polls until authorized
  4. JWT token issued on success

​
Dev Mode

For testing and development (requires RELAY_DEV_SECRET):
  • POST /auth/dev - Browser dev login (sets HttpOnly cookie)
  • POST /auth/dev/token - Raw JWT for daemon/CLI

​
E2E Encrypted REST Tunnel

The relay supports end-to-end encrypted REST requests where the relay cannot see the payload: 
POST /api/_e2e
Regular (non-encrypted) REST forwarding is also available: 
POST /api/{path}
Both route requests from the browser to the local daemon through the relay.

​
Security

  • Rate limiting - Per-IP sliding window for auth endpoints
  • CSRF protection - OAuth state parameter with single-use nonce
  • Boot ID - All tokens invalidated when relay restarts
  • Periodic pings - 30-second keepalive to prevent timeout
  • E2E encryption - X25519 key exchange + AES-GCM payload encryption

​
Connection Flow

  1. User logs in via browser (Google OAuth or device code)
  2. Local daemon connects to relay and registers device
  3. Browser opens WebSocket to relay, receives connection ID
  4. All subsequent messages route through relay
  5. E2E encrypted payloads are forwarded opaquely