Architecture

System Overview

When you run beam 3000, several components work together:

The CLI spawns the daemon as a child process, communicates via stdout/stderr, and handles user interaction. The daemon manages all network operations including Tor connections, DNS resolution, and HTTP proxying.

CLI Tool (Node.js)

The CLI is written in TypeScript and distributed via npm. It serves as the user-facing interface to Beam, handling argument parsing, configuration management, and process lifecycle.

The CLI is intentionally lightweight. All heavy lifting happens in the Rust daemon, keeping the Node.js process responsive to user input.

Tunnel Daemon (Rust)

The daemon is compiled to a native binary for each platform (macOS, Linux, Windows). It handles all performance-critical networking operations using Rust's async runtime.

Rust was chosen for the daemon because tunneling is inherently I/O-bound. Tokio's async model handles thousands of concurrent connections efficiently without the overhead of garbage collection pauses or thread-per-connection models.

The daemon binary is bundled with the npm package. When you install Beam, it includes pre-compiled binaries for your platform. No Rust toolchain is required on user machines.

Tor Integration

Beam uses the Tor network to provide global access without exposing your IP address. When you enable Tor mode, the daemon creates a hidden service (onion service) that routes traffic through the Tor network.

The .onion address is derived from your public key, providing cryptographic identity verification. Anyone connecting to your .onion address can be certain they're reaching your service and not an impostor.

Initial Tor connection takes 10-30 seconds while circuits are built. Subsequent requests have 100-300ms additional latency due to the multi-hop routing. This tradeoff provides strong privacy guarantees in exchange for some speed.

Local DNS Resolution

Beam runs a lightweight DNS server that resolves custom domains to localhost. This allows you to use memorable domain names instead of localhost:3000.

beam 3000 --domain myapp.local

When you specify a domain, the DNS server binds to port 5354 (configurable) and responds to queries for that domain with 127.0.0.1. Your system's resolver needs to be configured to use Beam's DNS server for local domains.

The DNS server only responds to queries for domains you've configured. All other queries are passed through to your system's default resolver.

Dual-Mode Operation

Beam supports running local and Tor access simultaneously. This is useful during development when you need fast local access for yourself but also want to share with teammates or test webhooks.

beam 3000 --domain myapp.local --dual

Request Flow

Understanding how requests flow through Beam helps with debugging and optimization. Here's what happens when a request arrives:

Security Architecture

Beam implements a zero-trust security model. Key security properties include:

• No central server: Traffic never passes through Beam-operated infrastructure
• End-to-end encryption: TLS 1.3 for local HTTPS, Tor encryption for remote access
• No data collection: Beam doesn't log requests, store analytics, or phone home
• Local key storage: Cryptographic keys stored in ~/.beam/ with filesystem permissions
• Perfect forward secrecy: Session keys are ephemeral; past traffic can't be decrypted if keys are later compromised

For a deeper dive into Beam's security model, see the Security documentation.

Related Documentation

• Tor Network — Detailed explanation of how Beam uses Tor hidden services
• Security Model — Encryption, privacy, and threat model
• P2P Networking — Upcoming decentralized discovery system
• CLI Reference — Complete command and flag documentation