Beam

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:

Terminal
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 peer
balanced~80-150ms latency, single-hop Tor, server exposed
private~200-500ms latency, full 3-hop Tor, full anonymity
Terminal
1
2
3
4
5
6
7
8
# Maximum speed
beam 3000 --mode=fast
# Good balance (default)
beam 3000 --mode=balanced
# Maximum privacy
beam 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.

Terminal
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.

Terminal
beam 3000 --mode=private # Preferred

--dual (deprecated)

Enable dual-mode. Deprecated: Use --mode=balanced instead.

Terminal
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/.

Terminal
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.

Terminal
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.

Terminal
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.

Terminal
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.

Terminal
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.

Terminal
beam 3000 --no-cache

--cache-size <mb>

Set the maximum cache size in megabytes. Default: 100MB.

Terminal
beam 3000 --cache-size=200

--cache-ttl <seconds>

Set the cache time-to-live in seconds. Default: 300 (5 minutes).

Terminal
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.

Terminal
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.

Terminal
beam 3000 --prebuild-circuits=5

--no-prebuild

Disable circuit prebuilding. Saves resources but increases latency on first connection.

Terminal
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.

Terminal
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_MODE

    Default tunnel mode: "fast", "balanced", or "private" (default: balanced)

  • BEAM_TOR_SOCKS_PORT

    Override the default Tor SOCKS port (default: 9050)

  • BEAM_DNS_PORT

    Override the default DNS server port (default: 5354)

  • BEAM_CACHE_SIZE

    Default cache size in MB (default: 100)

  • BEAM_CACHE_TTL

    Default cache TTL in seconds (default: 300)

  • BEAM_PREBUILD_CIRCUITS

    Number of circuits to prebuild (default: 3)

  • BEAM_GEO_PREFER

    Comma-separated ISO country codes for relay preference

  • BEAM_VERBOSE

    Set to "1" or "true" to enable verbose logging by default

  • RUST_LOG

    Control Rust daemon logging level (debug, info, warn, error)

Exit Codes

Beam uses standard exit codes:

  • 0 — Success (tunnel stopped gracefully)
  • 1 — General error
  • 2 — Invalid arguments
  • 130 — Interrupted (Ctrl+C)

Examples

Basic tunnel (balanced mode)

Terminal
beam 3000

Creates a tunnel in balanced mode (~80-150ms) forwarding to localhost:3000

Fast mode for local development

Terminal
beam 3000 --mode=fast --domain api.local

Direct P2P connection with ~30-50ms latency

Balanced mode with custom domain

Terminal
beam 3000 --mode=balanced --domain myapp.local

Single-hop Tor with ~80-150ms latency, local access at myapp.local

Private mode for maximum anonymity

Terminal
beam 3000 --mode=private

Full 3-hop Tor onion routing with ~200-500ms latency

HTTPS with balanced mode

Terminal
beam 3000 --mode=balanced --domain myapp.local --https

HTTPS locally and via Tor, with custom domain

Optimized for speed with caching

Terminal
beam 3000 --mode=balanced --cache-size=200 --prebuild-circuits=5

Larger cache and more prebuilt circuits for better performance

Geographic optimization

Terminal
beam 3000 --mode=balanced --geo-prefer=US,CA,UK

Prefer relays in US, Canada, and UK for lower latency

Real-time data (no caching)

Terminal
beam 3000 --mode=balanced --no-cache

Disable caching for real-time or frequently changing data

See Also