How Beam Works
A deep dive into P2P domain resolution, Tor hidden services, and how Beam connects your local machine to the world securely.
One Domain, Multi-Context Resolution
The core magic of Beam is its ability to make a single domain name, like project.local, resolve differently depending on who is asking.
We call this "Context-Aware Resolution." It eliminates the need to manage different URLs for local dev, staging, and public access.
On Your Machine
Resolves to 127.0.0.1. Zero latency, direct local access.
On the Internet
Resolves to a .onion address. Routes through Tor.
Local
127.0.0.1
Public
xyz.onion
The Architecture
Discovery & Registration
When you run beam dev, Beam generates a cryptographic key pair. It then announces your presence to the Beam Distributed Hash Table (DHT), a decentralized network of peers.
> Announcing to DHT...
> Registered: [Your-Key-ID]
Tor Circuit Establishment
Beam spins up an embedded Tor instance (so you don't need Tor installed). It establishes a Hidden Service Version 3, which creates a rendezvous point in the Tor network.
This rendezvous point allows inbound traffic without you ever needing to open a port on your router. No port forwarding. No firewall config.
Traffic Routing
When an external user accesses your Beam address:
- The request enters the Tor network.
- Tor routes it anonymously to your rendezvous point.
- Beam receives the stream, decrypts it, and proxies it to your local
localhost:3000. - The response follows the same path back, fully encrypted.
Frequently Asked Questions
Is it truly private?
Yes. Unlike other tunnel services that decrypt your traffic at their servers, Beam uses Tor's end-to-end encryption. The traffic is encrypted from the client all the way to your laptop. No one in the middle (not even us) can see the data.
Do I need Tor installed?
No. Beam comes with an embedded Tor daemon. It runs entirely in userspace and cleans up after itself when you exit.
What about performance?
Tor is slower than direct internet connections due to the 3-hop circuit. Expect latencies around 200ms-500ms. For purely local development (P2P mode), it's instant. For real-time apps requiring sub-100ms latency, we offer a "Fast Mode" that skips Tor but sacrifices some anonymity.
Support & Community
Open an issue on our GitHub repository to get help from the team and community.
Open GitHub IssueThis documentation is open source. Feel free to contribute updates or fixes.
Edit on GitHub