Beam

Tor Network

Beam uses the Tor network to provide global access to your local development server. This page explains how Tor works, how Beam integrates with it, and what security guarantees you get from using Tor-based tunneling.

What is Tor?

Tor (The Onion Router) is a decentralized network of volunteer-operated servers that enables anonymous communication. Originally developed by the U.S. Naval Research Laboratory, Tor is now maintained by the non-profit Tor Project and used by millions of people worldwide.

The network consists of approximately 7,000 relay nodes spread across the globe. When you send traffic through Tor, it's encrypted in multiple layers (like an onion) and routed through three randomly selected relays. Each relay only knows the previous and next hop, never the full path—so no single point can see both where traffic came from and where it's going.

Tor has been battle-tested for over 20 years and is trusted by journalists, activists, researchers, and security professionals. It's one of the most studied anonymity networks in existence.

How Tor Routing Works

Tor uses onion routing, where each layer of encryption is peeled off by successive relays. Here's how a typical connection flows:

Tor Onion Routing

Your
Request
Guard
Layer 3
Knows your IP
Encrypted
Middle
Layer 2
Knows nothing
Encrypted
Exit
Layer 1
Knows destination
Hidden
Service
(Beam)

The Three Relay Types

  • Guard Relay: The first hop that knows your IP address. Selected from high-uptime, trusted relays. Your guard stays the same for weeks to prevent certain attacks.
  • Middle Relay: The intermediate hop that knows neither source nor destination. Adds an extra layer of anonymity and makes traffic analysis harder.
  • Exit/Rendezvous: For hidden services, a rendezvous point where client and server meet without either knowing the other's IP address.

Each relay can only decrypt one layer of encryption, revealing only the next hop. This design ensures that compromising any single relay doesn't compromise the entire circuit.

Hidden Services (.onion)

Hidden services (also called onion services) are a special Tor feature that allows you to host services without revealing your IP address. Unlike regular Tor usage where traffic eventually exits to the public internet, hidden services keep all communication entirely within the Tor network.

Key Properties

  • Your server's IP address remains completely hidden from clients
  • Client IP addresses are hidden from your server
  • End-to-end encryption is automatic—no TLS certificates needed
  • Works behind any NAT or firewall without port forwarding
  • The .onion address is derived from your public key, providing cryptographic identity

.onion Address Format

Version 3 onion addresses are 56 characters long, derived from an Ed25519 public key:

abc123def456ghi789jkl012mno345pqr678stu901vwx234yz.onion

The address itself is a cryptographic commitment to your public key. Anyone connecting to your .onion address can verify they're reaching the legitimate service and not an impostor—even without a certificate authority.

How Beam Creates Hidden Services

When you run beam 3000 --tor, the daemon performs several steps to set up your hidden service:

  1. Key Generation: Beam generates a unique Ed25519 keypair for your service. The public key determines your .onion address. Keys are stored in~/.beam/keys/ so you get the same address on subsequent runs.
  2. Circuit Building: The daemon connects to the Tor network and builds circuits to multiple introduction points—relays that will accept initial contact from clients.
  3. Descriptor Publication: Your service descriptor is encrypted and published to the Tor distributed hash table (DHT). This allows clients to discover your introduction points by looking up your .onion address.
  4. Rendezvous Protocol: When a client connects, both parties independently build circuits to a rendezvous point. They meet there without either learning the other's IP address.
  5. Traffic Forwarding: Once the rendezvous is established, HTTP traffic flows through the circuits to Beam, which forwards it to your local server.

The entire setup process takes 10-30 seconds on first run while Tor builds circuits. Subsequent connections reuse existing circuits and are much faster.

Using Tor with Beam

Basic Tor Tunnel

Terminal
beam 3000 --tor

Creates a Tor hidden service for your local port 3000. You'll receive a .onion address accessible from any Tor Browser or Tor-enabled client.

Dual Mode (Local + Tor)

Terminal
beam 3000 --domain myapp.local --dual

Enables both local access via custom domain and global access via Tor simultaneously.

  • Local: http://myapp.local — fast, zero latency
  • Global: http://xyz...abc.onion — accessible worldwide

Tor with HTTPS

Terminal
beam 3000 --tor --https

Adds a TLS layer on top of Tor's encryption. Useful when your application requires HTTPS (e.g., for service workers or secure cookies). Note that Tor already provides end-to-end encryption, so this is primarily for application-level requirements.

Performance Considerations

Tor adds latency compared to direct connections. This is the tradeoff for privacy. Understanding the latency characteristics helps you decide when to use Tor mode.

Expected Latency

  • Initial connection: 2-5 seconds (circuit building)
  • Request latency: 100-300ms additional per request
  • Circuit rebuild: ~3 seconds (happens periodically for security)

Why the Latency?

  • Traffic passes through 6 relays (3 on your side, 3 on client side)
  • Each hop adds geographic latency—relays may be on different continents
  • Cryptographic operations at each relay for encryption/decryption
  • Relay bandwidth varies—some relays are faster than others

For rapid local development, use beam 3000 without the --tor flag. Enable Tor only when you need external access for webhook testing, sharing with remote collaborators, or testing from mobile devices.

Security Benefits

Using Tor mode provides several security advantages over traditional tunneling services:

  • IP Anonymization: Neither clients nor network observers can determine your real IP address. Your development machine's location remains hidden.
  • End-to-End Encryption: All traffic is encrypted from client to your server. Not even Tor relays can read your data—they only pass encrypted packets.
  • No Port Forwarding: Works behind any NAT or firewall. No router configuration needed. Tor punches through network restrictions automatically.
  • Censorship Resistance: Accessible from anywhere in the world, including countries that block traditional tunneling services like ngrok.
  • No Third-Party Trust: Unlike centralized services, there's no company that can log your traffic, comply with subpoenas, or shut down your tunnel.

When to Use Tor Mode

Ideal Use Cases

  • Webhook testing with external services (Stripe, GitHub, Twilio)
  • Sharing development previews with remote team members
  • Testing from mobile devices without local network access
  • Development in restrictive network environments
  • Privacy-sensitive projects where you don't want third parties seeing your traffic

Consider Alternatives When

  • Sub-50ms latency is critical for your testing
  • You need to test with services that actively block Tor exit nodes
  • Your organization's security policy prohibits Tor usage
  • You're doing pure local development without external access needs

Tor Installation

Beam includes an embedded Tor client, so you typically don't need to install Tor separately. However, if you prefer to use a system Tor installation, here's how:

macOS (Homebrew)

Terminal
brew install tor

Ubuntu/Debian

Terminal
sudo apt install tor

Fedora/RHEL

Terminal
sudo dnf install tor

Verify installation with tor --version. Beam will automatically detect and use your system Tor if available.

Related Documentation