Getting Started

System Requirements

Beam runs on macOS, Linux, and Windows (via WSL). You'll need:

• Node.js 18 or higher — Beam's CLI is written in TypeScript and runs on Node
• npm — Comes bundled with Node.js
• Tor — Optional but recommended; Beam can use an embedded Tor client or connect to an existing Tor installation

To check your Node version, run node --version in your terminal. If you need to install or update Node, visit nodejs.org.

Installation

Install Beam globally using npm:

npm install -g @byronwade/beam

This installs the beam command globally. The package includes both the Node.js CLI and the compiled Rust tunnel daemon for your platform.

If you prefer not to install globally, you can use npx to run Beam directly:

npx @byronwade/beam 3000

Creating Your First Tunnel

Let's expose a local development server running on port 3000. If you don't have a server running, you can start a simple one with Python or Node:

python3 -m http.server 3000

Now, in a new terminal window, create a tunnel:

beam 3000

Beam will start the tunnel daemon in balanced mode (the default), connect to Tor, and generate a .onion address. This takes 10-30 seconds on first run while Tor builds circuits. You'll see output like:

1
2
3
4
5
6
7
8
9
10
11
12
🚀 Starting tunnel daemon...
   Mode: balanced (Single-hop Tor for good balance of speed and privacy)
⚖️  Balanced mode tunnel active!
   Local:  http://127.0.0.1:4000 → localhost:3000
   Global: http://abc123xyz789def456.onion
   Expected latency: ~80-150ms
   Privacy: Medium (server exposed, clients hidden)
   Circuits prebuilt: 3
Press Ctrl+C to stop the tunnel

The .onion address is now accessible from any Tor-enabled browser or client. You can test it using the Tor Browser, or with curl through a Tor proxy.

Choosing a Tunnel Mode

Beam offers three tunnel modes, each optimized for different use cases. Use the --mode flag to select:

beam 3000 --mode=fast

beam 3000 --mode=balanced

beam 3000 --mode=private

For detailed performance tuning options, see the Performance Guide.

Using Custom Local Domains

Instead of using localhost:3000, you can assign a custom domain like myapp.local. This is useful when your application requires a specific hostname, or when you want cleaner URLs.

beam 3000 --domain myapp.local

Beam runs a local DNS server that resolves myapp.local to 127.0.0.1. You may need to configure your system to use Beam's DNS server (typically running on port 5354).

On macOS, Beam can automatically configure DNS resolution. On Linux, you may need to add Beam's DNS server to your resolver configuration manually.

Balanced Mode: Speed + Privacy

For development, you often want both fast local access and the ability to share with others. The default balanced mode gives you both with optimized latency:

beam 3000 --domain myapp.local --mode=balanced

With balanced mode, you get:

• http://myapp.local — Fast local access with minimal latency
• http://xyz.onion — Global access via single-hop Tor (~80-150ms)

Note: The --dual flag is deprecated. Use --mode=balanced instead for the same functionality with better performance.

Enabling HTTPS

Some applications require HTTPS, especially when testing features like service workers, secure cookies, or WebRTC. Beam can generate self-signed certificates automatically:

beam 3000 --https --domain myapp.local

Your browser will show a certificate warning since the certificate is self-signed. You can safely proceed for development purposes. For production use, you'd want to use proper certificates.

Traffic over Tor is already encrypted end-to-end by the Tor protocol, regardless of whether you enable HTTPS. The --https flag is primarily useful for local development requirements.

Debugging with Verbose Mode

If something isn't working, enable verbose logging to see what's happening:

beam 3000 --verbose

This shows detailed output including Tor connection status, DNS resolution, and HTTP request handling. Useful for diagnosing connection issues or understanding how Beam processes requests.

Stopping the Tunnel

Press Ctrl+C in the terminal where Beam is running. This gracefully shuts down the tunnel daemon and disconnects from Tor.

Your .onion address will become inactive immediately. The next time you start a tunnel, you'll get a new .onion address unless you configure persistent keys (covered in advanced usage).

Next Steps

Now that you have Beam running, explore these resources to get the most out of it:

• CLI Reference — Complete documentation of all commands, flags, and configuration options
• Performance Guide — Optimize latency with caching, circuit prebuilding, and geographic relay selection
• Examples — Practical examples for webhook testing, API development, and team collaboration
• Architecture — Technical details on how the CLI, daemon, and Tor integration work together
• Troubleshooting — Solutions to common issues and debugging techniques