Beam

Deployment

This guide covers deploying Beam in various environments, from simple single-machine setups to distributed production deployments. Beam's architecture is designed for resilience — most configurations require minimal setup.

Quick Start

For most users, Beam runs directly from npm with no additional deployment needed:

Terminal
# Install globally
npm install -g @byronwade/beam
# Run a tunnel
beam 3000

The CLI handles everything: spawning the tunnel daemon, connecting to Tor, and creating your hidden service. For personal development use, this is all you need.

Docker Deployment

For containerized environments, Beam provides Docker images that include all dependencies.

Basic Docker Run

Terminal
1
2
3
4
5
6
7
# Run Beam in a container
docker run -d \
  --name beam \
  -p 3000:3000 \
  -v beam-data:/app/data \
  byronwade/beam:latest \
  beam 3000

The volume mount persists your .onion address between container restarts.

Docker Compose

For running Beam alongside your application:

docker-compose.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
  beam:
    image: byronwade/beam:latest
    command: beam 3000 --target app:3000
    volumes:
      - beam-data:/app/data
    depends_on:
      - app
volumes:
  beam-data:

The --target flag tells Beam to forward traffic to the app container instead of localhost.

Self-Hosting on a Server

Running Beam on a VPS or dedicated server gives you a persistent tunnel that stays up even when your local machine is off.

Prerequisites

  • A Linux server (Ubuntu/Debian recommended)
  • Node.js 18+ installed
  • At least 512MB RAM
  • Outbound network access (Beam doesn't require open inbound ports)

Installation

Terminal
1
2
3
4
5
6
7
8
9
# Install Node.js (if not already installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install Beam
npm install -g @byronwade/beam
# Verify installation
beam --version

Running as a Systemd Service

Create a systemd service for automatic startup and restart:

/etc/systemd/system/beam.service
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# /etc/systemd/system/beam.service
[Unit]
Description=Beam Tunnel
After=network.target
[Service]
Type=simple
User=beam
WorkingDirectory=/home/beam
ExecStart=/usr/bin/beam 3000
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
Terminal
1
2
3
4
5
6
7
8
9
10
11
12
# Create a dedicated user
sudo useradd -r -s /bin/false beam
sudo mkdir -p /home/beam
sudo chown beam:beam /home/beam
# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable beam
sudo systemctl start beam
# Check status
sudo systemctl status beam

Kubernetes Deployment

For Kubernetes environments, deploy Beam as a sidecar or standalone pod.

Sidecar Pattern

Run Beam alongside your application pod:

deployment.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: myapp:latest
        ports:
        - containerPort: 3000
      - name: beam
        image: byronwade/beam:latest
        command: ["beam", "3000", "--target", "localhost:3000"]
        volumeMounts:
        - name: beam-data
          mountPath: /app/data
      volumes:
      - name: beam-data
        persistentVolumeClaim:
          claimName: beam-pvc

Persistent Volume

To keep the same .onion address across pod restarts:

pvc.yaml
1
2
3
4
5
6
7
8
9
10
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: beam-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 100Mi

The persistent volume stores your hidden service keys, ensuring your .onion address remains stable.

Configuration

Beam can be configured via command-line flags or environment variables.

Environment Variables

Environment variables
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Target port
BEAM_PORT=3000
# Target host (for forwarding to another service)
BEAM_TARGET=localhost:3000
# Data directory (where keys are stored)
BEAM_DATA_DIR=/var/lib/beam
# Enable verbose logging
BEAM_VERBOSE=true
# Custom domain (for local DNS)
BEAM_DOMAIN=myapp.local

Data Directory

By default, Beam stores data in ~/.beam/. This includes:

  • keys/ — Hidden service private keys (keep these safe!)
  • certs/ — Generated TLS certificates for HTTPS
  • tor/ — Tor data directory

Back up the keys/ directory if you need to preserve your .onion address when migrating to a new server.

Production Considerations

Resource Requirements

Beam is lightweight, but Tor circuit building and traffic forwarding do consume resources:

  • Memory: ~100-200MB under normal load
  • CPU: Minimal, mostly idle. Spikes during circuit building
  • Disk: ~50MB for Tor data, plus your key storage
  • Network: All traffic goes through Tor, so no inbound ports needed

Security

In production deployments:

  • Run Beam as a non-root user
  • Protect the keys/ directory — these are your hidden service private keys
  • Use firewall rules to restrict which services Beam can forward to
  • Consider using read-only root filesystem in containers

Monitoring

Monitor your Beam deployment:

Terminal
1
2
3
4
5
6
7
8
# Check if the process is running
pgrep -f beam-tunnel-daemon
# View logs (when running as systemd service)
journalctl -u beam -f
# Check Tor circuit status (verbose mode)
beam 3000 --verbose

High Availability

Each Beam instance gets its own .onion address. For high availability, you can run multiple instances behind a load balancer on the regular network, then expose that load balancer through Beam. Alternatively, use DNS-based failover at the application level if your clients can handle multiple .onion addresses.

Deployment Troubleshooting

Container Networking Issues

If Beam can't reach your application in Docker:

Terminal
1
2
3
4
5
6
7
8
9
# Make sure containers are on the same network
docker network ls
docker network inspect bridge
# Use service names instead of localhost
beam 3000 --target myapp:3000
# Or use host networking (less isolated)
docker run --network host byronwade/beam:latest beam 3000

Tor Connection Fails in Container

Some container environments block Tor traffic or don't allow the embedded Tor client to function properly:

  • Verify outbound network access from the container
  • Check if your cloud provider blocks Tor exit nodes
  • Try a different region if running in cloud infrastructure

Permission Denied

If you see permission errors:

Terminal
# Make sure the data directory is writable
chown -R beam:beam /var/lib/beam
# In Docker, check volume permissions
docker run -v beam-data:/app/data --user 1000:1000 ...

Related Documentation