Skip to main content

​
Requirements

  • Node.js 18 or higher
  • npm, yarn, or pnpm package manager
Check your Node.js version with node --version. If you need to upgrade, visit nodejs.org.

​
Installation methods

Choose the installation method that works best for your workflow.

​
Global installation

Install Wormkey globally to use the wormkey command from anywhere: 
npm install -g wormkey
Verify the installation: 
wormkey --version
# Output: 0.1.5
Now you can run wormkey from any directory: 
wormkey http 3000
Global installation is recommended if you use Wormkey frequently across multiple projects.

​
Run without installing (npx)

Use npx to run Wormkey without installing it globally: 
npx wormkey http 3000
This downloads and runs the latest version of Wormkey each time. Perfect for:
  • One-off tunnels
  • CI/CD environments
  • Testing before installing globally
  • Always using the latest version
The first run with npx may take a few seconds to download the package. Subsequent runs are faster if the package is cached.

​
Local installation (project-specific)

Install Wormkey as a project dependency: 
npm install wormkey
Add a script to your package.json:
package.json
{
  "scripts": {
    "tunnel": "wormkey http 3000"
  }
}
Run the tunnel: 
npm run tunnel
Local installation is useful when you want to lock Wormkey to a specific version for your project or include it in your project’s dependencies.

​
Verify installation

Check that Wormkey is installed correctly:
1

Check version

wormkey --version
You should see the version number (e.g., 0.1.5).
2

View help

wormkey --help
This displays all available commands and options:
Usage: wormkey [options] [command]

Open a wormhole to your localhost

Options:
  -V, --version          output the version number
  -h, --help             display help for command

Commands:
  http <port>            Expose local port via wormhole
  login                  Authenticate with Wormkey (device flow)
  status                 Show active tunnel status
  close                  Close active tunnel
  help [command]         display help for command
3

Test a tunnel

Start a simple server and create a tunnel:
# Terminal 1: Start a test server
python3 -m http.server 8000

# Terminal 2: Open a wormhole
wormkey http 8000

​
Update Wormkey

Keep Wormkey up to date to get the latest features and fixes.

​
Update global installation

npm update -g wormkey

​
Update local installation

npm update wormkey

​
Check for updates

See if a newer version is available: 
npm outdated -g wormkey

​
Uninstall Wormkey

​
Remove global installation

npm uninstall -g wormkey

​
Remove local installation

npm uninstall wormkey

​
Installing additional packages

Wormkey provides additional packages for enhanced functionality.

​
Overlay helpers

For automatic overlay integration: 
npm install @wormkey/overlay
Use in your app: 
import "@wormkey/overlay/auto";

​
React component

The main wormkey package includes the React component: 
npm install wormkey
Import in your React app: 
import { WormkeyOverlay } from "wormkey";
The wormkey package has React 18+ as a peer dependency. Make sure React is installed in your project.

​
Troubleshooting

​
Command not found

If you see wormkey: command not found after global installation:
  1. Check that your npm global bin directory is in your PATH: 
    npm config get prefix
  2. Add the bin directory to your PATH: 
    # Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
  3. Restart your terminal or run: 
    source ~/.bashrc  # or ~/.zshrc

​
Permission errors on macOS/Linux

If you get permission errors during global installation: 
sudo npm install -g wormkey
Or configure npm to use a different directory: 
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

​
Version mismatch

If you have multiple versions installed, check which one is being used: 
which wormkey
wormkey --version

​
Next steps

Quickstart

Create your first wormhole tunnel

CLI commands

Learn about all available commands

Configuration

Configure authentication and session options

React integration

Add Wormkey to your React or Next.js app

Build docs developers (and LLMs) love

Get started for freeTalk to us