Skip to content

tor_support: Added documentation for torPrivacyLevel as well as a few other critical things that relate to user privacy and safety like Tor, Whonix, etc. #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
scramblr wants to merge 2 commits into
base: master
Choose a base branch
from
Open

tor_support: Added documentation for torPrivacyLevel as well as a few other critical things that relate to user privacy and safety like Tor, Whonix, etc. #18

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e126f0
tor_support: add configuration reference for torPrivacyLevel
scramblr Mar 1, 2026
a30832e
tor_support: document torOnlyAllowOnion override and OS-specific beha…
scramblr Mar 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions content/_guides/tor_support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,27 @@ You have the option to select the desired mode when Feather is started for the f
By default, Feather routes all network traffic over Tor, except for wallet synchronization. Synchronization requires a lot of data transfer and is therefore very slow over Tor. A remote node does not learn much about your wallet during synchronization (for more information see [Nodes](nodes)). We believe this is a reasonable privacy / convenience trade-off.

On Tails, Whonix, or when Feather is started with `torsocks`, all traffic is routed through Tor regardless of application configuration. Traffic to a [local node](local-node) is never routed over Tor.

### Configuration reference

This setting is stored as `torPrivacyLevel` in [`settings.json`](paths):

| Value | Mode | Description |
|-------|------|-------------|
| `0` | Never over Tor | Node traffic uses clearnet. Other traffic is still routed through Tor. A remote node can see your IP address. |
| `1` | Switch to Tor after sync (**default**) | Clearnet nodes are allowed during initial sync. Once the wallet is within `initSyncThreshold` blocks (default: 360) of the network height, only .onion nodes are used. |
| `2` | Always over Tor | All node traffic uses .onion nodes exclusively. Maximum privacy, but initial sync may be significantly slower. |

The related setting `initSyncThreshold` (default: `360`) controls how many blocks from the network tip the wallet must reach before switching to .onion-only nodes when `torPrivacyLevel` is set to `1`.

The **"Only allow connections to onion services"** checkbox (`torOnlyAllowOnion` in `settings.json`) is a separate override. When enabled, it forces .onion-only connections **regardless** of the `torPrivacyLevel` setting. For example, setting `torPrivacyLevel` to `0` (Never over Tor) while `torOnlyAllowOnion` is `true` will still restrict connections to .onion nodes only. Local nodes are always exempt from this restriction.

### Tails, Whonix and torsocks

On Tails, Whonix, or when Feather is started with `torsocks`, Feather will not start its own Tor daemon and assumes Tor is already running:

- **Tails**: Tor status is checked via the `tails-tor-has-bootstrapped.target` systemd unit.
- **Whonix**: Tor is assumed to be connected (Whonix routes all traffic through Tor at the OS level).
- **torsocks**: Tor is assumed to be connected (torsocks intercepts network calls transparently).

In all three cases, `torPrivacyLevel` still controls which nodes Feather will connect to. The proxy settings in the UI do not affect these environments.