Skip to main content

​
Session Configuration

Wormkey sessions control how long your wormhole stays open and who can access it. Configure expiry, viewer limits, and access policies.

​
Session Creation

Sessions are created when you run wormkey http <port>. The control plane returns: 
{
  "sessionId": "sess_a1b2c3d4...",
  "slug": "quiet-lime-42",
  "publicUrl": "https://wormkey.run/s/quiet-lime-42",
  "ownerUrl": "https://wormkey.run/.wormkey/owner?slug=quiet-lime-42&token=...",
  "overlayScriptUrl": "https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42",
  "edgeUrl": "wss://t.wormkey.run/tunnel",
  "sessionToken": "quiet-lime-42.ownertoken123",
  "expiresAt": "2026-03-04T12:00:00.000Z"
}

​
Expiry Configuration

Control how long your wormhole stays active using the --expires flag.

​
Syntax

wormkey http <port> --expires <duration>

​
Duration Formats

wormkey http 3000 --expires 30m
Session expires after 30 minutes.

​
Examples

# Quick demo (30 minutes)
wormkey http 3000 --expires 30m

# Client review (4 hours)
wormkey http 5173 --expires 4h

# All-day access (24 hours, default)
wormkey http 8080 --expires 24h

​
How Expiry Works

1

Parse duration

The control plane converts 30m → 30 * 60 * 1000 ms, or 2h → 2 * 60 * 60 * 1000 ms.
2

Calculate expiry timestamp

Sets expiresAt = Date.now() + expiresMs.
3

Store in session

Session object includes:
{
  "expiresAt": "2026-03-04T12:00:00.000Z",
  "createdAt": "2026-03-03T12:00:00.000Z"
}
4

Enforce at edge

The edge gateway rejects requests after expiresAt.

​
Session Policy

Sessions include a policy object that controls access and behavior: 
policy: {
  public: boolean;              // Allow public access
  maxConcurrentViewers: number; // Viewer limit (default: 20)
  blockPaths: string[];         // Blocked URL paths
  password: string;             // Password protection
}

​
Default Policy

{
  "public": true,
  "maxConcurrentViewers": 20,
  "blockPaths": [],
  "password": ""
}

​
Update Policy

Use the control plane API to modify session policy: 
POST /sessions/by-slug/:slug/policy
Request body: 
{
  "public": false,
  "maxConcurrentViewers": 5,
  "blockPaths": ["/admin", "/api/secret"],
  "password": "mysecret123"
}
Response: 
{
  "ok": true,
  "policy": {
    "public": false,
    "maxConcurrentViewers": 5,
    "blockPaths": ["/admin", "/api/secret"],
    "password": "mysecret123"
  }
}

​
Viewer Management

Sessions track active viewers in real-time.

​
Active Viewers

activeViewers: Array<{
  id: string;          // Unique viewer ID
  lastSeenAt: string;  // ISO timestamp
  requests: number;    // Request count
  ip?: string;         // Client IP (optional)
}>

​
Update Viewers

The edge gateway periodically reports active viewers: 
POST /sessions/by-slug/:slug/viewers
Request body: 
{
  "viewers": [
    {
      "id": "viewer_abc123",
      "lastSeenAt": "2026-03-03T12:30:00.000Z",
      "requests": 15,
      "ip": "203.0.113.42"
    }
  ]
}

​
Kick Viewer

Remove a specific viewer from the session: 
POST /sessions/by-slug/:slug/kick
Request body: 
{
  "viewerId": "viewer_abc123"
}
Response: 
{
  "ok": true,
  "kickedViewerIds": ["viewer_abc123"]
}
Kicked viewers are permanently blocked for the session duration.

​
Close Session

Manually close a session before expiry: 
POST /sessions/by-slug/:slug/close
Response: 
{
  "ok": true
}
Sets session.closed = true. The edge gateway rejects all future requests.

​
CLI Close

Press Ctrl+C in the terminal running wormkey http to close the tunnel and session.

​
Authentication Modes

Sessions support multiple authentication strategies.

​
None (Default)

wormkey http 3000
No authentication required. Anyone with the URL can access.

​
Basic Auth

wormkey http 3000 --auth
Generates username/password: 
{
  "authMode": "basic",
  "username": "worm",
  "password": "a1b2c3d4"
}
See Basic Authentication for details.

​
Environment Variables

Customize control plane and edge URLs:
VariableDefaultDescription
WORMKEY_CONTROL_PLANE_URLhttps://wormkey-control-plane.onrender.comControl plane API URL
WORMKEY_EDGE_URLwss://t.wormkey.run/tunnelEdge tunnel WebSocket URL
WORMKEY_PUBLIC_BASE_URLhttps://wormkey.runPublic gateway base URL

​
Local Development

Override for local testing: 
export WORMKEY_CONTROL_PLANE_URL=http://localhost:3001
export WORMKEY_EDGE_URL=ws://localhost:3002/tunnel
export WORMKEY_PUBLIC_BASE_URL=http://localhost:3002

wormkey http 3000
Or use the --local flag: 
wormkey http 3000 --local

​
Session Lifecycle

1

Create

Run wormkey http <port>. Control plane allocates slug, generates tokens, stores session.
2

Active

Edge gateway proxies requests to your localhost. Viewers tracked in real-time.
3

Expire or Close

Session ends when:
  • expiresAt timestamp reached
  • Owner closes via API or Ctrl+C
  • Control plane restarts (in-memory store)
4

Cleanup

Session removed from memory. Public URL returns 404.

​
Best Practices

Short-lived sessions

Use --expires 30m or --expires 1h for temporary demos to minimize exposure.

Combine auth + expiry

wormkey http 3000 --auth --expires 2h
Protect sensitive work with credentials and time limits.

Monitor active viewers

Check the owner overlay to see who’s connected and kick unauthorized viewers.

​
API Reference

​
Create Session

POST /sessions
Body: 
{
  "port": 3000,
  "authMode": "basic",
  "expiresIn": "2h"
}

​
Get Session by ID

GET /sessions/:id

​
Get Session by Slug

GET /sessions/by-slug/:slug

​
Delete Session

DELETE /sessions/:id

Build docs developers (and LLMs) love

Get started for freeTalk to us