Beam Documentation
Beam is a decentralized tunneling tool that exposes local development servers to the internet through the Tor network. Unlike centralized services like ngrok, Beam operates without intermediary servers—your traffic flows directly through Tor's onion routing, providing end-to-end encryption and IP anonymity by default.
Quick Start
Install Beam globally using npm, then start a tunnel to any local port:
npm install -g @byronwade/beam
beam 3000
This creates a Tor hidden service that forwards traffic to localhost:3000. You'll receive a .onion address accessible from any Tor-enabled browser or client worldwide.
For local development with custom domains, add the --domain flag:
beam 3000 --domain myapp.local --tor
How Beam Works
Beam consists of two components: a Node.js CLI that handles user interaction, and a Rust daemon that manages the actual tunneling. When you run beam 3000, the following happens:
- The CLI spawns the Rust tunnel daemon as a background process
- The daemon starts an embedded Tor client and creates a hidden service
- A local DNS server resolves custom domains (like
myapp.local) to127.0.0.1 - An HTTP proxy intercepts requests and forwards them to your local server
- Traffic from the Tor network is routed to the same local port
The result is dual-access: you can reach your app via http://myapp.local on your machine, and via the .onion address from anywhere in the world.
Why Decentralized Tunneling?
Traditional tunneling services route all traffic through their servers. This creates several problems:
- Privacy: The provider can inspect, log, and analyze your traffic
- Availability: If their servers go down, your tunnels stop working
- Censorship: Governments can block the provider's domains
- Cost: Premium features require paid subscriptions
Beam eliminates these concerns by using Tor as the transport layer. Your traffic never touches a centralized server—it flows through the distributed Tor network, encrypted at every hop. There's no company that can read your data, shut down your tunnel, or comply with takedown requests.
The tradeoff is latency. Tor adds approximately 200-500ms of round-trip time due to its multi-hop routing. For development and testing, this is usually acceptable. For production use cases requiring low latency, consider Beam's upcoming P2P mode.
Current Status
Beam is in active development. The core tunneling functionality is stable and usable:
Working Features
- HTTP/HTTPS tunneling to any local port
- Tor hidden service creation with persistent .onion addresses
- Custom local domains via built-in DNS server
- Dual-mode operation (local + Tor simultaneously)
- TLS certificate generation for HTTPS
- WebSocket support
In Development
- P2P domain registry using Kademlia DHT
- Nym mixnet integration for enhanced privacy
- Veilid framework support
- I2P garlic routing option
- Multi-tunnel management
- Traffic analytics and request inspection
This is a solo developer project. Development pace depends on community interest andsponsorship support.
Use Cases
Webhook Development
Test webhooks from services like Stripe, GitHub, or Twilio without deploying to a server. Create a tunnel to your local webhook handler, configure the service with your .onion URL, and receive real webhook payloads during development.
Mobile App Testing
Test your mobile app against a local API server. Run your backend locally, create a tunnel, and point your mobile app at the .onion address. No need to deploy to staging environments for each change.
Team Collaboration
Share your work-in-progress with teammates or clients. Create a tunnel to your local development server and send them the .onion link. They can view your changes in real-time without you pushing to a shared environment.
Privacy-Sensitive Development
When working on sensitive projects, Beam ensures your development traffic remains private. Unlike centralized services, no third party can inspect what you're building or who's accessing your development server.
Next Steps
- Getting Started Guide — Detailed installation instructions and system requirements
- CLI Reference — Complete documentation of all commands and options
- Examples — Practical code examples for common scenarios
- Architecture — Technical deep-dive into how Beam works
- Tor Network — Understanding Tor integration and hidden services
- Tor Network — Understanding Tor integration and hidden services
- Project Roadmap — Future plans for I2P, Nym, WebRTC, and detailed expanding research