Skip to main content

​
Overview

The http command creates a secure tunnel to expose a local HTTP server to the internet. This is the primary command for creating wormholes in Wormkey.

​
Usage

wormkey http <port> [options]

​
Arguments

​
port
number
required
The local port number to expose (1-65535)

​
Options

​
--auth
boolean
default:"false"
Enable basic HTTP authentication. When enabled, the CLI will generate and display a username and password that must be used to access the tunnel.
​
--expires
string
default:"24h"
Session expiration duration. Accepts time units like 30m, 1h, 24h.Examples:
  • 30m - 30 minutes
  • 1h - 1 hour
  • 24h - 24 hours (default)
​
--control-plane
string
Override the control plane URL. By default, uses https://wormkey-control-plane.onrender.com in production or http://localhost:3001 in local mode.
​
--edge
string
Override the edge tunnel URL. By default, uses wss://t.wormkey.run/tunnel in production or ws://localhost:3002/tunnel in local mode.
​
--local
boolean
default:"false"
Use localhost control plane and edge servers for local development. This sets the control plane to http://localhost:3001 and edge to ws://localhost:3002/tunnel.

​
Environment Variables

You can configure Wormkey using environment variables instead of command-line flags:
  • WORMKEY_ENV=local - Equivalent to --local flag
  • WORMKEY_CONTROL_PLANE_URL - Override control plane URL
  • WORMKEY_EDGE_URL - Override edge tunnel URL

​
Examples

wormkey http 3000

​
Output

When you run the http command, you’ll see output like this: 
$ wormkey http 3000
Control plane: https://wormkey-control-plane.onrender.com
Edge tunnel: wss://t.wormkey.run/tunnel

Wormhole open.
https://abc123.wormkey.run

Owner claim URL (open once):
https://wormkey.run/claim/xyz789

Path B integration (add in app layout):
<script defer src="https://wormkey.run/overlay/abc123.js"></script>

Press Ctrl+C to close.

​
With Authentication

When using --auth, you’ll see credentials displayed: 
$ wormkey http 3000 --auth
Control plane: https://wormkey-control-plane.onrender.com

Basic auth enabled:
  Username: user_abc123
  Password: pass_xyz789

Edge tunnel: wss://t.wormkey.run/tunnel

Wormhole open.
https://abc123.wormkey.run

Owner claim URL (open once):
https://wormkey.run/claim/xyz789

Path B integration (add in app layout):
<script defer src="https://wormkey.run/overlay/abc123.js"></script>

Press Ctrl+C to close.

​
Understanding the Output

​
Public URL
The public HTTPS URL where your local server is accessible. Share this URL with others.
​
Owner claim URL
A one-time URL to claim ownership of this tunnel. Open this link once to associate the tunnel with your account. After the first use, this URL becomes invalid.
​
Path B integration script
A script tag for Path B integration. Add this to your application layout to enable collaborative browsing features.

​
Validation

Port numbers must be between 1 and 65535. Invalid ports will result in an error:
Invalid port. Use 1-65535.

​
Closing the Tunnel

Press Ctrl+C to gracefully close the tunnel and terminate the wormhole connection.

​
Error Handling

If the tunnel fails to connect, you’ll see an error message: 
Error: [error message]
Common issues:
  • Local port is not accessible or not running
  • Network connectivity problems
  • Control plane or edge server unavailable
  • Invalid session parameters

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us