Skip to main content

​
Prerequisites

  • Node.js 18 or higher
  • A local server running on any port (or use the example below)

​
Create your first wormhole

Follow these steps to expose your localhost to a public URL.
1

Run Wormkey

You can run Wormkey without installing using npx:
npx wormkey http 3000
Or install globally first:
npm install -g wormkey
wormkey http 3000
Replace 3000 with your application’s port number.
2

View the output

Wormkey will display your tunnel information:
Control plane: https://wormkey-control-plane.onrender.com
Edge tunnel: wss://t.wormkey.run/tunnel

Wormhole open.
https://wormkey.run/s/quiet-lime-82

Owner claim URL (open once):
https://wormkey.run/.wormkey/owner?slug=quiet-lime-82&token=abc123...

Path B integration (add in app layout):
<script defer src="https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-82"></script>

Press Ctrl+C to close.
3

Open your public URL

Click the public URL (e.g., https://wormkey.run/s/quiet-lime-82) or share it with others.All requests to this URL are forwarded to your localhost.
4

Claim ownership (optional)

Open the owner claim URL once in your browser to enable owner controls:
  • View connection status
  • See active viewers
  • Manage access (future feature)
The owner claim URL contains a secret token. Only open it once and keep it private.

​
Test without a local server

Don’t have a server running? Start a quick test server: 
# Start a simple HTTP server on port 8000
python3 -m http.server 8000

# In another terminal
wormkey http 8000

​
Enable basic authentication

Protect your tunnel with a username and password: 
wormkey http 3000 --auth
You’ll see credentials in the output: 
Basic auth enabled:
  Username: wormkey_abc123
  Password: def456ghi789jkl

Wormhole open.
https://wormkey.run/s/quiet-lime-82
Visitors will need to enter these credentials to access your tunnel.

​
Set an expiration time

Control how long your tunnel stays active: 
# Expire after 30 minutes
wormkey http 3000 --expires 30m

# Expire after 1 hour
wormkey http 3000 --expires 1h

# Expire after 24 hours (default)
wormkey http 3000 --expires 24h
The tunnel closes automatically when the session expires or when you press Ctrl+C.

​
Add the overlay to your app

The Wormkey overlay provides an in-page control bar when viewing your app through the wormhole URL.

​
Option 1: Auto-mount helper

Install the overlay package: 
npm install @wormkey/overlay
Import the auto-mount script in your app entry point: 
import "@wormkey/overlay/auto";
Add the overlay script URL as a meta tag: 
<meta name="wormkey-overlay-url" content="https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-82" />

​
Option 2: React component

For Next.js or React apps: 
npm install wormkey
app/layout.tsx
import { WormkeyOverlay } from "wormkey";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <WormkeyOverlay
          gatewayUrl={process.env.NEXT_PUBLIC_WORMKEY_GATEWAY_URL ?? "https://wormkey.run"}
        />
      </body>
    </html>
  );
}

​
Option 3: Manual script tag

Add the script tag from the CLI output to your HTML: 
<script defer src="https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-82"></script>
The overlay automatically detects when your app is viewed through a wormhole URL and displays the control bar.

​
Close the wormhole

Press Ctrl+C in the terminal where Wormkey is running: 
^C
# Tunnel closed
The public URL will stop working immediately.

​
Next steps

Installation guide

Learn about global vs local installation and package manager options

CLI commands

Explore all available commands and options

React integration

Deep dive into React and Next.js integration

Session configuration

Configure authentication, expiration, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us