> ## Documentation Index > Fetch the complete documentation index at: https://docs.parallaxprotocol.org/llms.txt > Use this file to discover all available pages before exploring further. # Running over Tor > Connect through the Tor network, host an onion service, and run a fully dark node The Parallax client has first-class [Tor](https://www.torproject.org/) support, modeled closely on Bitcoin Core's: outbound connections can be routed through a SOCKS5 proxy, the node can host a Tor v3 onion service for inbound connections with no port forwarding, onion addresses are gossiped and stored like any other peer address, and a node can run entirely inside Tor with `--onlynet=onion`. See [Tor Integration](../../parallax-protocol/advanced/networking/tor) for the protocol-level design. ## Quick start Install Tor and enable its control port in `/etc/tor/torrc`: ``` ControlPort 9051 CookieAuthentication 1 CookieAuthFileGroupReadable 1 ``` restart Tor (`sudo systemctl restart tor`), add the user running `parallaxd` to the Tor group (`debian-tor` on Debian/Ubuntu, `tor` on Arch — on Arch also add `DataDirectoryGroupReadable 1` to torrc, since the auth cookie lives inside `/var/lib/tor` there), then simply start the node: ```sh theme={null} parallaxd ``` No Tor-specific flags are needed for the default experience. On startup the node connects to the control port, creates a v3 onion service pointing at its P2P listener, and — because `--onion` wasn't set — asks the Tor daemon for its SOCKS listener and configures it as the onion proxy automatically. Watch for: ``` torcontrol: onion proxy auto-configured proxy=127.0.0.1:9050 reachable=true torcontrol: onion service established service=xxxx….onion virtualPort=32110 ``` From that point the node is reachable at its onion address, advertises it to the network, and can dial other nodes' onion addresses. The `network reachability` line logged at startup summarizes what the resolved configuration allows. ## Flags | Flag | Default | Effect | | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--listenonion` | on | Create a v3 onion service for the P2P listener via the Tor control port. A no-op (with quiet periodic retries) until a control port answers. | | `--torcontrol` | `127.0.0.1:9051` | Tor control port address. | | `--torpassword` | unset | Control-port password (`HashedControlPassword` auth). Cookie auth is used automatically when unset. | | `--proxy` | unset | SOCKS5 proxy for **all** outbound connections, including clearnet ones. Also suppresses everything that would expose the node's real IP regardless of the proxy: DNS-seed bootstrapping moves off the system resolver, the discv4 UDP socket is not opened, enrtree resolution is skipped, and UPnP/NAT-PMP is disabled. | | `--onion` | auto-discovered | SOCKS5 proxy used only for `.onion` targets, overriding both `--proxy` and the auto-discovery. `--onion=0` disables onion outbound entirely. | | `--onlynet` | unset | Restrict **automatic** outbound connections to the named networks (`ipv4`, `ipv6`, `onion`, comma-separated). Manual dials (`addnode`, `addPeer`, `dialV2`) and static nodes are exempt, as in Core. | | `--proxyrandomize` | on | Fresh SOCKS5 credentials per connection, so Tor puts every peer on its own circuit (stream isolation). | ## The onion service identity The service key persists in `/onion_v3_private_key`, so the node keeps the same `.onion` address across restarts. Treat the file like the node key: back it up to keep the address, protect it because whoever holds it can impersonate the service. Deleting it yields a fresh address on next startup. The onion service always advertises the network default port (32110) regardless of the local `--port`, so nodes on non-standard ports are not decloaked by their port number. ## Verifying On the console: ```javascript theme={null} > admin.nodeInfo.onion "xxxx….onion:32110" > admin.nodeInfo.networks [{name: "ipv4", reachable: true, ...}, {name: "ipv6", reachable: true, ...}, {name: "onion", reachable: true, proxy: "127.0.0.1:9050", proxy_randomize_credentials: true}] ``` `admin.peers` shows each peer's transport and logical address. A proxied peer's `remoteAddress` is always the SOCKS5 proxy — the socket-level truth — while `network.address` names the actual target: ```javascript theme={null} network: { address: "yyyy….onion:32110", network: "onion", remoteAddress: "127.0.0.1:9050", inbound: false, ... } ``` An **inbound** onion peer shows an empty `address`: it reached us through a Tor rendezvous and is anonymous by design. To test reachability from another machine with Tor, dial the address directly: ```sh theme={null} parallax-cli dialv2 xxxx….onion:32110 # one-shot parallax-cli addnode xxxx….onion:32110 # persistent, survives restarts ``` `setban`/`listbanned` accept onion addresses the same way, and `removenode` accepts them too — outbound peers are matched by the address they were dialed at, so a peer reached through a proxy is addressed by its real address rather than the proxy's. ## Fully dark: `--onlynet=onion` ```sh theme={null} parallaxd --onlynet=onion ``` restricts outbound to onion peers. No discv4 UDP socket is opened, NAT traversal and DNS seeding are disabled, and the node bootstraps from the onion addresses in the hardcoded bootnode list, then from gossip. It is legal to start this way before the Tor daemon is up: the node begins with no reachable network and flips onion reachable the moment the control port answers. An onion-only node never reveals its IP address to any peer — the client refuses to advertise an IP over a Tor circuit even when it knows one. A dual-stack node (clearnet listener + onion service) advertises both addresses, which allows observers to link them. Operators who need unlinkability must run onion-only. ## Clearnet through Tor: expectations `--proxy=127.0.0.1:9050` routes clearnet connections through Tor exit relays. This works, but most exit policies do not carry non-standard ports, so only a fraction of circuits complete a connection to clearnet peers on 32110 — measured at roughly 1 in 6 on the live network (Bitcoin has the same property on 8333). Onion-to-onion connections use rendezvous circuits, never exits, and connect reliably in seconds. Treat exit-based clearnet dialing as a bootstrap fallback; onion peering is the real transport. ## Troubleshooting * **No `torcontrol:` lines at all** — the control port isn't answering, or the auth cookie is unreadable. The controller retries with backoff and logs failures only at debug level; run `debug.verbosity(4)` on the console to see the exact error (`connection refused` → torrc lacks `ControlPort`; `permission denied` → group membership or, on Arch, the missing `DataDirectoryGroupReadable 1`). * **Onion dial says `no route to network`** — the node has no onion proxy: no `--proxy`/`--onion`, and no control port for the auto-discovery. Onion entries are then neither stored nor dialed. * **First dial to a fresh onion address fails with `onion service descriptor can not be found`** — the descriptor hasn't propagated yet; retry after 30-60 seconds.