OnionBalance v3 Setup Guide: Load Balance Your .onion Service in 2026

OnionBalance operates a master instance that controls the .onion address. Multiple backend servers each run a Tor hidden service (with their own ephemeral keys). OnionBalance periodically queries each backend's introduction points and publishes a merged descriptor under the master .onion key. Clients connecting to the master .onion address receive introduction points from multiple backends. Each connection goes to whichever backend served the introduction point that the client used. Load distribution: connections are distributed approximately proportionally to the number of introduction points each backend contributes. Typically 3 introduction points per backend means each backend gets roughly 1/N of traffic (where N is number of backends). High availability: if a backend goes offline, its introduction points time out and OnionBalance republishes the descriptor with only the remaining backends' introduction points. Clients automatically route to available backends.

OnionBalance requires: Python 3.8+, Tor (Tor must be installed and running on the OnionBalance manager node), and the onionbalance Python package (pip install onionbalance). System requirements for the manager: a small VPS or server with a stable internet connection, running Tor as a client (not bridge or relay). The manager does not need to be a powerful server - it performs only descriptor publication, not traffic routing. Backend requirements: each backend is a normal hidden service server (Tor running, application serving on a local port, HiddenServiceDir configured). Backend Tor instances do not need to be publicly reachable - they only need outbound Tor network access to build circuits.

Master configuration: generate the master Ed25519 key (this is your .onion address key): onionbalance-config --hs-version 3 --output config.yaml. This generates config.yaml and the master key. config.yaml structure: services: [{key: /path/to/master_key, instances: [{address: backend1.onion}, {address: backend2.onion}, {address: backend3.onion}]}]. The backend addresses are the .onion addresses of each backend's hidden service (from their hostname files). Backend configuration: each backend is a standard Tor hidden service. HiddenServiceDir /var/lib/tor/backend1/ in torrc. The backend .onion address (from hostname file) is added to the OnionBalance config.yaml. No special configuration on the backend is required - they do not know they are part of an OnionBalance group. Running OnionBalance: onionbalance -c config.yaml. The manager connects to the local Tor control port and begins publishing merged descriptors.

OnionBalance does not have built-in HTTP health checking (it only monitors whether backends publish valid Tor descriptors). For application-level health checking: implement an external health check that periodically connects to each backend .onion address and verifies the application responds correctly. Use nyx (Tor relay monitor) on the manager to monitor descriptor publication. Monitoring approach: set up a monitoring script (Python with stem library) that tests connectivity to each backend's .onion address every 5 minutes and alerts if any backend is unreachable. OnionBalance logs: monitor /var/log/onionbalance/onionbalance.log for descriptor publication errors and backend reachability events. Alerting: pipe OnionBalance logs to a alerting system or trigger notifications when backends fail.

Each backend runs the same application. Consistency is critical: backends must serve identical content (users may connect to different backends across requests if the circuit changes). Shared state: use a shared database (PostgreSQL accessible from all backends - either a dedicated DB server or a primary DB with replicas), shared Redis (Redis primary accessible from all backends, or per-backend Redis with replication for caches), and shared file storage (NFS, MinIO, or S3-compatible object storage for user uploads). Deployment: use a configuration management tool (Ansible, Salt) to deploy identical application configuration to all backends. Container orchestration (Docker Compose on each backend with the same compose.yml) ensures environment consistency. Application-specific considerations: any in-memory state (active websocket connections, non-Redis rate limiters) is per-backend and not shared. Design stateless application handlers that depend only on database/Redis state.