Tor and the Relay
Overview
Every UnoLock node runs Tor for federation. One Tor process acts as the anonymous transport and hosts the node's v3 onion service. A second, separate process runs a non-exit Tor relay, which is enabled by default. Neither process can act as an exit node.
Application encryption, signatures, authentication and policy do not depend on Tor for their security. Tor is the transport between nodes.
The onion identity
The onion service private key is part of your node's persistent identity. In container deployments it is kept under the mounted node data volume, and once Tor has started successfully it is stored in the encrypted node database, so it travels with node backups.
Losing the onion identity changes your node's address
Receive Addresses are fixed to their original node's onion service. If the onion identity is lost and cannot be restored, issue new Receive Addresses and share them with senders through a trusted channel. Republishing cannot redirect existing verified pins.
Hardware replacement and standby failover keep addresses working by preserving the same onion identity, authorized publications and encrypted node state. Never run two active nodes with the same onion private key. See Backup and Recovery.
Why the node runs a relay
Self-hosted nodes use Tor's shared, volunteer-operated network for federation. The default follows a simple principle: if we use the network, we should contribute to it. A relay contributes capacity for general Tor traffic, supporting other Tor users as well as the infrastructure UnoLock depends on. Hosting an onion service alone does not provide that capacity.
The relay is non-exit. It contributes within the Tor network without making your server an exit point to ordinary internet destinations. Exit operation is not part of the bundled node's role.
Contributing is the default, not a requirement for using federation.
Relay settings
Open Settings → Node Configuration → Contribute to the Tor Network in the admin console:
| Setting | Default | Allowed values |
|---|---|---|
| Enable non-exit Tor relay | Enabled, including existing configs without an explicit setting | On or off. Off keeps federation Tor only. |
| Bandwidth per direction | 10 Mbps | Whole numbers from 10 to 10000 |
| Public relay TCP port | 9001 | Unprivileged ports 1024–65535, not conflicting with the node's other listeners |
After changing these settings, save the pending configuration, restart the node, then unlock it. Both Tor processes stay stopped while the node is locked. See Restarts and Unlocking.
Bandwidth budget
The 10 Mbps per-direction default matches the minimum in Tor's relay requirements, which recommend 16 Mbps. At the default the relay is limited to 1,250,000 bytes per second in each direction, with no extra burst allowance. The limit applies to the relay process only, not to the federation process.
- At continuous full use, 10 Mbps is about 3.24 TB uploaded plus 3.24 TB downloaded per 30 days, before protocol overhead.
- This is a speed limit, not a monthly quota. Actual usage depends on Tor network demand.
- The default is a bounded starting contribution, not a measurement of your spare capacity.
- Operators with capacity can raise it to 16 Mbps or higher, while reserving bandwidth for their Safes.
Check your hosting plan
If your connection or transfer allowance cannot support relaying, disable the relay. Federation keeps working without it.
Network and Docker port mapping
Allow inbound TCP 9001 through the host firewall, provider firewall and router.
- The standard launcher publishes
9001:9001for new containers. - Existing containers must be recreated with that mapping while preserving their data volume.
- For a custom relay port, publish the same host and container port and update the firewall.
- Saving admin settings cannot change Docker port mappings.
- The relay listens on IPv4 and needs a reachable public IPv4 address. CGNAT or other unreachable inbound networking prevents useful public relaying.
Checking the relay
The admin console reports the configured intent, not verified relay participation. A started relay still needs public reachability and acceptance by the Tor directory.
To check participation, look up your relay's fingerprint in Tor Relay Search. The fingerprint is in <node.dataDir>/tor-relay/fingerprint. Do not publish it in UnoLock diagnostics.
If the relay fails to start, the failure is logged and federation Tor keeps running.
Privacy implications
Public relays publish their IP addresses. Running the relay on your node publishes your server's IP as a Tor relay. Separate processes keep identities and bandwidth limits apart, but they do not hide that both run on the same host, and they do not prevent uptime and traffic correlation.
If you need to keep your node's location private, turn off the bundled relay and contribute on a separate host instead.
More generally, onion services do not guarantee that a host's network location or communication relationships stay undiscoverable. Malicious relays and network observers can attempt guard discovery and traffic correlation. An onion address, a successful circuit or a passing connectivity test is not proof of anonymity against those attackers. The node keeps Tor's entry-guard and Vanguards-lite defaults (Vanguards-lite set to auto); these are mitigations, not a guarantee against discovery.
How to disable the relay
- Turn off only the relay: disable Enable non-exit Tor relay in Settings → Node Configuration → Contribute to the Tor Network, save, restart, and unlock. Federation keeps using Tor.
- Turn off both Tor processes: set
UNOLOCK_START_TOR=false. This also stops federation Tor.
An externally managed Tor installation must configure its own relay; admin settings do not rewrite external Tor configurations.
Relay safeguards
The relay always runs with ExitRelay 0, ExitPolicy reject *:*, IPv6Exit 0 and SocksPort 0. No exit option or arbitrary torrc input is exposed. Federation Tor runs with ClientOnly 1, ORPort 0 and a reject-all exit policy.
The relay's identity is local to the host, under <node.dataDir>/tor-relay with private directory permissions. It is separate from the encrypted federation onion identity, is not replicated to standbys, and is not included in standard node recovery bundles. A replacement host gets a new relay identity. Never copy this directory to hosts that run at the same time.
Expected Tor behavior
Onion circuits can take seconds to establish and may fail transiently. Log lines about descriptor lookup, introduction, rendezvous, circuit retry or timeout are not, on their own, evidence of a problem. The node retries delivery with bounded backoff, and synchronous calls return temporary unavailability instead of waiting forever.
For temporary diagnostics, set UNOLOCK_NODE_LOG_LEVEL=debug to include node network summaries. UNOLOCK_DEBUG=true also enables filtered Tor daemon diagnostics and proxy informational logs. Remove these overrides after troubleshooting, and redact onion addresses before sharing diagnostics. See Troubleshooting.
Full reference
FAQs
Is my node an exit node?
No. The relay is non-exit and always runs with a reject-all exit policy. Neither Tor process can act as an exit node.
Do I have to run the relay to use federation?
No. Contributing is the default, not a requirement. Disable the relay and federation keeps working over Tor.
Why do I need to open TCP 9001?
The default non-exit relay listens on TCP 9001. If you change the relay port, publish and allow that port instead.
I changed the relay port in the admin console but nothing changed. Why?
Saving admin settings cannot change Docker port mappings. Recreate the container with the matching host and container port while preserving the data volume, update the firewall, then restart and unlock the node.
Will the relay reveal my server's IP address?
Yes. Public relays publish their IP addresses. If you need to keep your node's location private, turn off the bundled relay and contribute on a separate host.