CLI Reference
Complete reference for the Beam command-line interface. This page documents all available commands, options, and configuration settings.
Basic Usage
The simplest way to use Beam is to specify a port number:
beam <port>
This creates a tunnel that forwards traffic from a Tor hidden service to the specified local port. For example, beam 3000 exposes whatever is running on localhost:3000.
beam <port>
Start a tunnel to expose a local port. This is the primary command you'll use.
Options
--mode <mode>, -m
Select the tunnel mode. This determines the balance between speed and privacy. Default: balanced
fast~30-50ms latency, direct P2P, IP visible to peerbalanced~80-150ms latency, single-hop Tor, server exposedprivate~200-500ms latency, full 3-hop Tor, full anonymity12345678# Maximum speedbeam 3000 --mode=fast# Good balance (default)beam 3000 --mode=balanced# Maximum privacybeam 3000 --mode=private
See the Performance Guide for detailed mode comparison.
--domain <name>, -d
Set a custom local domain name instead of using localhost. Beam runs a DNS server that resolves this domain to 127.0.0.1.
beam 3000 --domain myapp.local
Domain names should use .local suffix to avoid conflicts with real domains.
--tor (deprecated)
Enable Tor hidden service. Deprecated: Use --mode=private instead.
beam 3000 --mode=private # Preferred
--dual (deprecated)
Enable dual-mode. Deprecated: Use --mode=balanced instead.
beam 3000 --mode=balanced # Preferred
--https
Generate a self-signed TLS certificate and serve over HTTPS. The certificate is created automatically and stored in ~/.beam/certs/.
beam 3000 --https --domain myapp.local
Your browser will show a security warning for the self-signed certificate.
--https-port <port>
Specify the port for the HTTPS server. Defaults to 443 if running with elevated privileges, otherwise 8443.
beam 3000 --https --https-port 9443
--dns-port <port>
Port for the local DNS server. Defaults to 5354. You may need to configure your system's resolver to use this port for .local domains.
beam 3000 --domain myapp.local --dns-port 5353
--tor-port <port>
Port for the Tor SOCKS proxy. Defaults to 9050. Change this if you have an existing Tor installation using that port.
beam 3000 --tor --tor-port 9150
--verbose, -v
Enable verbose logging. Shows detailed information about Tor connection status, DNS queries, HTTP requests, and internal state changes.
beam 3000 --verbose
Useful for debugging connection issues or understanding Beam's behavior.
Performance Options
--no-cache
Disable response caching. By default, Beam caches static assets (JS, CSS, images, fonts) to reduce round-trips, especially helpful in Tor modes.
beam 3000 --no-cache
--cache-size <mb>
Set the maximum cache size in megabytes. Default: 100MB.
beam 3000 --cache-size=200
--cache-ttl <seconds>
Set the cache time-to-live in seconds. Default: 300 (5 minutes).
beam 3000 --cache-ttl=600
--geo-prefer <countries>
Specify preferred countries for Tor relay selection using ISO 3166-1 alpha-2 codes. Reduces latency by selecting geographically closer relays.
beam 3000 --mode=balanced --geo-prefer=US,CA,MX
Warning: Not recommended for private mode as it reduces anonymity.
--prebuild-circuits <count>
Number of Tor circuits to prebuild for faster initial connections. Default: 3.
beam 3000 --prebuild-circuits=5
--no-prebuild
Disable circuit prebuilding. Saves resources but increases latency on first connection.
beam 3000 --no-prebuild
beam start <port>
Explicit form of the default command. Identical to beam <port>. Use this when you want to be explicit about starting a tunnel.
beam start 3000 --domain myapp.local --mode=balanced
Accepts all the same options as the default port command.
Planned Commands
The following commands are planned for future releases as part of the P2P networking and advanced management features:
beam register <domain>
Register a domain in the P2P network's distributed hash table. Will allow persistent, human-readable names that resolve across the Beam network.
beam list
List all active tunnels. Will show tunnel status, addresses, and traffic statistics.
beam stop <name>
Stop a specific tunnel by name or ID. Currently, tunnels are stopped with Ctrl+C.
beam status
Show comprehensive system status including Tor connectivity, P2P network health, and active tunnel information.
beam config
Manage Beam configuration. Will support setting defaults, viewing current config, and managing persistent settings.
Configuration Files
Beam stores configuration and data in the ~/.beam/ directory:
~/.beam/certs/Generated TLS certificates for HTTPS mode
~/.beam/tor/Tor data directory including hidden service keys
~/.beam/cache/Response cache for static assets (when caching enabled)
Environment Variables
Beam recognizes the following environment variables:
BEAM_MODEDefault tunnel mode: "fast", "balanced", or "private" (default: balanced)
BEAM_TOR_SOCKS_PORTOverride the default Tor SOCKS port (default: 9050)
BEAM_DNS_PORTOverride the default DNS server port (default: 5354)
BEAM_CACHE_SIZEDefault cache size in MB (default: 100)
BEAM_CACHE_TTLDefault cache TTL in seconds (default: 300)
BEAM_PREBUILD_CIRCUITSNumber of circuits to prebuild (default: 3)
BEAM_GEO_PREFERComma-separated ISO country codes for relay preference
BEAM_VERBOSESet to "1" or "true" to enable verbose logging by default
RUST_LOGControl Rust daemon logging level (debug, info, warn, error)
Exit Codes
Beam uses standard exit codes:
0— Success (tunnel stopped gracefully)1— General error2— Invalid arguments130— Interrupted (Ctrl+C)
Examples
Basic tunnel (balanced mode)
beam 3000
Creates a tunnel in balanced mode (~80-150ms) forwarding to localhost:3000
Fast mode for local development
beam 3000 --mode=fast --domain api.local
Direct P2P connection with ~30-50ms latency
Balanced mode with custom domain
beam 3000 --mode=balanced --domain myapp.local
Single-hop Tor with ~80-150ms latency, local access at myapp.local
Private mode for maximum anonymity
beam 3000 --mode=private
Full 3-hop Tor onion routing with ~200-500ms latency
HTTPS with balanced mode
beam 3000 --mode=balanced --domain myapp.local --https
HTTPS locally and via Tor, with custom domain
Optimized for speed with caching
beam 3000 --mode=balanced --cache-size=200 --prebuild-circuits=5
Larger cache and more prebuilt circuits for better performance
Geographic optimization
beam 3000 --mode=balanced --geo-prefer=US,CA,UK
Prefer relays in US, Canada, and UK for lower latency
Real-time data (no caching)
beam 3000 --mode=balanced --no-cache
Disable caching for real-time or frequently changing data
See Also
- Getting Started — Step-by-step guide to your first tunnel
- Performance Guide — Optimize latency with modes, caching, and circuit prebuilding
- Examples — Real-world usage patterns and workflows
- Troubleshooting — Common issues and solutions