tor-switch
Tor configuration and routing management for Kodachi OS
File Information
| Property | Value |
|---|---|
| Binary Name | tor-switch |
| Version | 10.0.3 |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 13.7MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Kodachi Binary |
| Description | Tor configuration and routing management for Kodachi OS |
| Git Commit | unknown |
| Metadata Generated | 2026-11-13T16:20:42Z |
| Binary Timestamp | Unknown |
| JSON Data | View Raw JSON |
SHA256 Checksum
a0bf6915f5c973d32c9d746040f34c34a29ff98beca73af78513b8bcdd05abf7
Features
| # | Feature |
|---|---|
| 1 | Tor network management and configuration |
| 2 | Multi-instance Tor support |
| 3 | Exit node rotation and control |
| 4 | DNS leak prevention integration |
| 5 | Firewall rule management |
| 6 | HAProxy configuration for load balancing |
| 7 | Authentication and security verification |
| 8 | Comprehensive logging and monitoring |
Security Features
| Feature | Description |
|---|---|
| Authentication | Not provided by cli-core (see online-auth) |
| Encryption | Not provided by cli-core |
| Input Validation | Argument parsing via clap; per-command validation is the consumer's responsibility |
| Rate Limiting | Not provided by cli-core |
System Requirements
| Requirement | Value |
|---|---|
| OS | Linux (Debian-based) |
| Privileges | root/sudo for system operations |
| Dependencies | OpenSSL, libcurl |
Global Options
| Flag | Description |
|---|---|
-h, --help |
Print help information |
-v, --version |
Print version information |
-n, --info |
Display detailed information |
-e, --examples |
Show usage examples |
--json |
Output in JSON format |
-o, --output-format <FORMAT> |
Force output format (text|json) |
--json-pretty |
Pretty-print JSON output with indentation |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--json-filter <FIELD1,FIELD2> |
Return only specified JSON fields (comma-separated) |
--fields <FIELD_LIST> |
Select specific fields to include in output (comma-separated) |
--limit <NUMBER> |
Limit number of results returned |
--offset <NUMBER> |
Skip first N results (for pagination) |
-d, --work-dir <PATH> |
Working directory (defaults to auto-detected base directory) |
--port <PORT> |
Set custom port number (1024-65535) |
--log-level <LEVEL> |
Set log level (error|warn|info|debug) |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--config <FILE> |
Use custom configuration file |
--timeout <SECS> |
Set operation timeout in seconds (optional; no default applied) |
Commands
Basic Operations
start-tor
Start Tor daemon
Usage:
tor-switch start-tor [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch start-tor
stop-tor
Stop Tor daemon
Usage:
tor-switch stop-tor [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch stop-tor
restart-tor
Restart Tor daemon
Usage:
tor-switch restart-tor [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch restart-tor
Bridge Management
set-bridges
Store bridge lines (obfs4, snowflake, meek_lite or webtunnel) and activate bridge mode for all instances. obfs4 and webtunnel lines: get them at https://bridges.torproject.org/. snowflake and meek_lite lines ship with Tor Browser's built-in bridges
Usage:
tor-switch set-bridges [OPTIONS]
Options:
-b, --bridge <LINE>: A bridge line for the chosen --transport, starting with its name (repeatable)--from-file <PATH>: Read bridge lines from a file (blank lines and # comments ignored)--stdin-bridges: Read bridge lines from bounded standard input--transport <TRANSPORT>: Pluggable transport: obfs4 (default), snowflake, meek_lite or webtunnel. Every bridge line must start with this name. snowflake needs snowflake-client, meek_lite needs obfs4proxy, webtunnel needs lyrebird--json: Output in JSON format
Examples:
sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'
sudo tor-switch set-bridges --from-file /tmp/bridges.txt
sudo tor-switch set-bridges --transport snowflake --bridge 'snowflake 192.0.2.3:80 <FINGERPRINT> fingerprint=<FINGERPRINT> url=https://<broker-front>/ fronts=<cdn-host> ice=stun:<stun-host>:3478'
sudo tor-switch set-bridges --transport meek_lite --bridge 'meek_lite 192.0.2.18:80 <FINGERPRINT> url=https://<meek-host>/ front=<front-host>'
sudo tor-switch set-bridges --transport webtunnel --from-file /tmp/webtunnel-bridges.txt
enable-bridges
Enable stored bridges for all instances and restart them
Usage:
tor-switch enable-bridges [OPTIONS]
Examples:
sudo tor-switch enable-bridges
disable-bridges
Disable bridges (revert to direct Tor) and restart all instances
Usage:
tor-switch disable-bridges [OPTIONS]
Examples:
sudo tor-switch disable-bridges
list-bridges
List stored bridge configuration, its transport and the plugin found for it
Usage:
tor-switch list-bridges [OPTIONS]
Examples:
tor-switch list-bridges --json
clear-bridges
Remove all stored bridges, disable bridge mode, and restart instances
Usage:
tor-switch clear-bridges [OPTIONS]
Examples:
sudo tor-switch clear-bridges
test-bridges
Validate stored bridge lines and report whether the transport's plugin is installed (read-only)
Usage:
tor-switch test-bridges [OPTIONS]
Examples:
tor-switch test-bridges --json
set-bridge-mode
Set bridge selection mode: 'all' uses every bridge, 'random' picks a random subset each rotation
Usage:
tor-switch set-bridge-mode [OPTIONS]
Options:
-m, --mode <MODE>: Selection mode: all or random--count <N>: Number of bridges to activate in random mode (>= 1)
Examples:
sudo tor-switch set-bridge-mode --mode all
sudo tor-switch set-bridge-mode --mode random --count 2
rotate-bridges
Re-apply bridge config to all instances (picks a fresh random subset in random mode)
Usage:
tor-switch rotate-bridges [OPTIONS]
Examples:
sudo tor-switch rotate-bridges
bridge-rotate-timer
Install a cron job that rotates bridges on the given interval (e.g. 15m, 1h)
Usage:
tor-switch bridge-rotate-timer [OPTIONS]
Options:
<INTERVAL>: Rotation interval (e.g. 15m, 1h, 30s)
Examples:
sudo tor-switch bridge-rotate-timer 15m
stop-bridge-rotate-timer
Remove the bridge rotation cron job
Usage:
tor-switch stop-bridge-rotate-timer [OPTIONS]
Examples:
sudo tor-switch stop-bridge-rotate-timer
Configuration
validate-torrc
Validate torrc configuration
Usage:
tor-switch validate-torrc [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
tor-switch validate-torrc
reload-tor-config
Reload Tor configuration
Usage:
tor-switch reload-tor-config [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch reload-tor-config
reload-tor-config-all
Reload config for all instances
Usage:
tor-switch reload-tor-config-all [OPTIONS]
Examples:
sudo tor-switch reload-tor-config-all
backup-config
Backup configuration
Usage:
tor-switch backup-config [OPTIONS]
Examples:
sudo tor-switch backup-config
backup-config-all
Backup all configurations
Usage:
tor-switch backup-config-all [OPTIONS]
Examples:
sudo tor-switch backup-config-all
restore-config
Restore configuration
Usage:
tor-switch restore-config [OPTIONS]
Options:
<BACKUP_NAME>: Backup name to restore (e.g., backup-2025-01-28)--instance <INSTANCE>: Target instance (optional)
Examples:
sudo tor-switch restore-config backup-2025-01-28
restore-config-all
Restore all configurations
Usage:
tor-switch restore-config-all [OPTIONS]
Options:
<BACKUP_NAME>: Backup name to restore (e.g., backup-2025-01-28)
Examples:
sudo tor-switch restore-config-all backup-2025-01-28
list-backups
List configuration backups
Usage:
tor-switch list-backups [OPTIONS]
Examples:
tor-switch list-backups
generate-new-tor-password
Generate new Tor control password
Usage:
tor-switch generate-new-tor-password [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch generate-new-tor-password
generate-new-tor-password-all
Generate password for all instances
Usage:
tor-switch generate-new-tor-password-all [OPTIONS]
Examples:
sudo tor-switch generate-new-tor-password-all
clean-torrc-custom
Clean custom torrc file
Usage:
tor-switch clean-torrc-custom [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
sudo tor-switch clean-torrc-custom
clean-torrc-custom-all
Clean custom torrc for all instances
Usage:
tor-switch clean-torrc-custom-all [OPTIONS]
Examples:
sudo tor-switch clean-torrc-custom-all
DNS Management
start-tor-dns-iptables
Start Tor DNS with iptables
Usage:
tor-switch start-tor-dns-iptables [OPTIONS]
Examples:
sudo tor-switch start-tor-dns-iptables
start-tor-dns-nftables
Start Tor DNS with nftables
Usage:
tor-switch start-tor-dns-nftables [OPTIONS]
Examples:
sudo tor-switch start-tor-dns-nftables
stop-tor-dns-iptables
Stop Tor DNS iptables
Usage:
tor-switch stop-tor-dns-iptables [OPTIONS]
Examples:
sudo tor-switch stop-tor-dns-iptables
stop-tor-dns-nftables
Stop Tor DNS nftables
Usage:
tor-switch stop-tor-dns-nftables [OPTIONS]
Examples:
sudo tor-switch stop-tor-dns-nftables
torrify-system-dns
Route DNS through Tor (auto-detects the active firewall). DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-dns [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-dns
torrify-system-iptables-dns
Route DNS through Tor with iptables. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-iptables-dns [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-iptables-dns
torrify-system-nftables-dns
Route DNS through Tor with nftables. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-nftables-dns [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-nftables-dns
verify-tor-dns
Verify Tor DNS resolution
Usage:
tor-switch verify-tor-dns [OPTIONS]
Examples:
tor-switch verify-tor-dns
tor-switch verify-tor-dns --json
verify-tor-dns-all
Verify DNS for all instances
Usage:
tor-switch verify-tor-dns-all [OPTIONS]
Examples:
tor-switch verify-tor-dns-all
verify-tor-dns-direct
Direct Tor DNS verification
Usage:
tor-switch verify-tor-dns-direct [OPTIONS]
Examples:
tor-switch verify-tor-dns-direct
verify-tor-dns-port
Verify Tor DNS port
Usage:
tor-switch verify-tor-dns-port [OPTIONS]
Examples:
tor-switch verify-tor-dns-port
Exit Node Control
set-exit-node
Set Tor exit node
Usage:
tor-switch set-exit-node [OPTIONS]
Options:
<NODE>: 2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random-<group> such as random-europe--instance <INSTANCE>: Target instance (optional)
Examples:
sudo tor-switch set-exit-node us
sudo tor-switch set-exit-node gb --instance secondary
sudo tor-switch set-exit-node de --instance streaming
sudo tor-switch set-exit-node ch --instance secure
sudo tor-switch set-exit-node random
sudo tor-switch set-exit-node all-world
sudo tor-switch set-exit-node random-europe
sudo tor-switch set-exit-node random-asia
sudo tor-switch set-exit-node random-africa
sudo tor-switch set-exit-node random-north-america
sudo tor-switch set-exit-node random-south-america
sudo tor-switch set-exit-node random-oceania
sudo tor-switch set-exit-node random-middle-east
sudo tor-switch set-exit-node random-5eyes
sudo tor-switch set-exit-node random-9eyes
sudo tor-switch set-exit-node random-14eyes
sudo tor-switch set-exit-node random-high-volume
sudo tor-switch set-exit-node random-low-volume
sudo tor-switch set-exit-node europe
sudo tor-switch set-exit-node asia
sudo tor-switch set-exit-node africa
sudo tor-switch set-exit-node north-america
sudo tor-switch set-exit-node south-america
sudo tor-switch set-exit-node oceania
sudo tor-switch set-exit-node middle-east
sudo tor-switch set-exit-node 5eyes
sudo tor-switch set-exit-node 9eyes
sudo tor-switch set-exit-node 14eyes
sudo tor-switch set-exit-node high-volume
sudo tor-switch set-exit-node low-volume
sudo tor-switch set-exit-node europe --instance europe
sudo tor-switch set-exit-node asia --instance asia
sudo tor-switch set-exit-node north-america --instance americas
sudo tor-switch set-exit-node random-low-volume --instance research
sudo tor-switch set-exit-node high-volume --instance testing
set-exit-node-all
Set exit node for all instances
Usage:
tor-switch set-exit-node-all [OPTIONS]
Options:
<NODE>: 2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random-<group> such as random-europe
Examples:
sudo tor-switch set-exit-node-all ca
set-exclude-node
Set excluded nodes
Usage:
tor-switch set-exclude-node [OPTIONS]
Options:
<NODE>: Comma-separated country codes to exclude (cn,ru,ir) or a group alias: adversarial, 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random-<group> such as random-14eyes--instance <INSTANCE>: Target instance (optional)
Examples:
sudo tor-switch set-exclude-node cn,ru,ir
sudo tor-switch set-exclude-node 5eyes
sudo tor-switch set-exclude-node 9eyes
sudo tor-switch set-exclude-node 14eyes
sudo tor-switch set-exclude-node europe
sudo tor-switch set-exclude-node asia
sudo tor-switch set-exclude-node north-america
sudo tor-switch set-exclude-node high-volume
sudo tor-switch set-exclude-node low-volume
sudo tor-switch set-exclude-node random-high-volume
sudo tor-switch set-exclude-node random-low-volume
sudo tor-switch set-exclude-node asia --instance secure
sudo tor-switch set-exclude-node 14eyes --instance privacy-1
sudo tor-switch set-exclude-node 5eyes --instance privacy-1
sudo tor-switch set-exclude-node 9eyes --instance privacy-2
sudo tor-switch set-exclude-node 14eyes --instance privacy-3
set-exclude-node-all
Set excluded nodes for all instances
Usage:
tor-switch set-exclude-node-all [OPTIONS]
Options:
<NODE>: Comma-separated country codes to exclude (cn,ru,ir) or a group alias: adversarial, 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random-<group> such as random-14eyes
Examples:
sudo tor-switch set-exclude-node-all fr
clear-exit-node
Clear exit node restrictions
Usage:
tor-switch clear-exit-node [OPTIONS]
Options:
--instance <INSTANCE>: Target instance (optional, defaults to default instance)
Examples:
sudo tor-switch clear-exit-node
clear-exit-node-all
Clear exit node for all instances
Usage:
tor-switch clear-exit-node-all [OPTIONS]
Examples:
sudo tor-switch clear-exit-node-all
clear-exclude-node-all
Clear excluded nodes for all instances
Usage:
tor-switch clear-exclude-node-all [OPTIONS]
Examples:
sudo tor-switch clear-exclude-node-all
new-tor-circuit
Create new Tor circuit
Usage:
tor-switch new-tor-circuit [OPTIONS]
Options:
--instance <INSTANCE>: Target instance (optional, defaults to default instance)
Examples:
sudo tor-switch new-tor-circuit
new-tor-circuit-all
New circuit for all instances
Usage:
tor-switch new-tor-circuit-all [OPTIONS]
Examples:
sudo tor-switch new-tor-circuit-all
Firewall
flush-iptables
Flush iptables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt
Usage:
tor-switch flush-iptables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch flush-iptables
flush-nftables
Flush nftables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt
Usage:
tor-switch flush-nftables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch flush-nftables
list-iptables
List iptables rules
Usage:
tor-switch list-iptables [OPTIONS]
Examples:
sudo tor-switch list-iptables
list-iptables-nat
List iptables NAT rules
Usage:
tor-switch list-iptables-nat [OPTIONS]
Examples:
sudo tor-switch list-iptables-nat
list-nftables
List nftables rules
Usage:
tor-switch list-nftables [OPTIONS]
Examples:
sudo tor-switch list-nftables
HAProxy
generate-haproxy-config
Generate HAProxy configuration
Usage:
tor-switch generate-haproxy-config [OPTIONS]
Options:
<MODE>: Load balancing mode (roundrobin, source, random, leastconn, first)<PORT>: Bind port (default: 9055)<OUTPUT>: Output file path (default: /etc/haproxy/tor-haproxy.cfg)<MAXCONN>: Maximum connections (default: 4096)
Examples:
sudo tor-switch generate-haproxy-config roundrobin 9055
sudo tor-switch generate-haproxy-config source 8080
sudo tor-switch generate-haproxy-config leastconn 9000
sudo tor-switch generate-haproxy-config random 8888
sudo tor-switch generate-haproxy-config
haproxy-start
Start HAProxy service
Usage:
tor-switch haproxy-start [OPTIONS]
Examples:
sudo tor-switch haproxy-start
haproxy-stop
Stop HAProxy service
Usage:
tor-switch haproxy-stop [OPTIONS]
Examples:
sudo tor-switch haproxy-stop
haproxy-status
Check HAProxy status
Usage:
tor-switch haproxy-status [OPTIONS]
Examples:
tor-switch haproxy-status
list-haproxy-modes
List HAProxy load balancing modes
Usage:
tor-switch list-haproxy-modes [OPTIONS]
Examples:
tor-switch list-haproxy-modes
display-load-balancing-config
Display load balancing configuration
Usage:
tor-switch display-load-balancing-config [OPTIONS]
Examples:
tor-switch display-load-balancing-config
Help
show-help
Show help information
Usage:
tor-switch show-help [OPTIONS]
Examples:
tor-switch show-help
show-examples
Show usage examples
Usage:
tor-switch show-examples [OPTIONS]
Examples:
tor-switch show-examples
Instance Management
create-instance
Create new Tor instance
Usage:
tor-switch create-instance [OPTIONS]
Options:
<NAME>: Instance name
Examples:
sudo tor-switch create-instance secondary
sudo tor-switch create-instance europe
sudo tor-switch create-instance asia
sudo tor-switch create-instance americas
sudo tor-switch create-instance research
sudo tor-switch create-instance testing
sudo tor-switch create-instance onionhost
delete-instance
Delete Tor instance
Usage:
tor-switch delete-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
sudo tor-switch delete-instance secondary
delete-all-instances
Delete all Tor instances
Usage:
tor-switch delete-all-instances [OPTIONS]
Examples:
sudo tor-switch delete-all-instances
delete-all-instances-with-default
Delete all instances including default
Usage:
tor-switch delete-all-instances-with-default [OPTIONS]
Examples:
sudo tor-switch delete-all-instances-with-default
start-instance
Start a Tor instance
Usage:
tor-switch start-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
sudo tor-switch start-instance secondary
stop-instance
Stop a Tor instance
Usage:
tor-switch stop-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
sudo tor-switch stop-instance secondary
restart-instance
Restart a Tor instance
Usage:
tor-switch restart-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
sudo tor-switch restart-instance secondary
start-all-instances
Start all Tor instances
Usage:
tor-switch start-all-instances [OPTIONS]
Examples:
sudo tor-switch start-all-instances
stop-all-instances
Stop all Tor instances
Usage:
tor-switch stop-all-instances [OPTIONS]
Examples:
sudo tor-switch stop-all-instances
restart-all-instances
Restart all Tor instances
Usage:
tor-switch restart-all-instances [OPTIONS]
Options:
--rolling: Restart one instance at a time, waiting for each to build circuits, so the pool stays usable during the restart
Examples:
sudo tor-switch restart-all-instances
show-instance
Show instance details
Usage:
tor-switch show-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
tor-switch show-instance streaming
set-default-instance
Set default Tor instance
Usage:
tor-switch set-default-instance [OPTIONS]
Options:
<TAG>: Instance tag/name
Examples:
sudo tor-switch set-default-instance performance-0
rename-instance
Rename a Tor instance
Usage:
tor-switch rename-instance [OPTIONS]
Options:
<OLD_TAG>: Current instance tag/name<NEW_TAG>: New instance tag/name
Examples:
sudo tor-switch rename-instance old-name new-name
clone-instance
Clone a Tor instance
Usage:
tor-switch clone-instance [OPTIONS]
Options:
<SOURCE_TAG>: Source instance tag/name<TARGET_TAG>: Target instance tag/name
Examples:
sudo tor-switch clone-instance main backup
create-multiple-instances
Create multiple Tor instances. If COUNT is omitted, picks the RAM-aware default from instance_sizing::recommended_instance_count (4 GB→3, 8 GB→5, 16 GB→7, 32 GB→10, 256 GB→20). Passing COUNT is an explicit user override and bypasses the model (still clamped to [floor, cap] for safety).
Usage:
tor-switch create-multiple-instances [OPTIONS]
Options:
<COUNT>: Number of instances to create (omit to use RAM-aware default)<PREFIX>: Optional prefix for instance names
Examples:
sudo tor-switch create-multiple-instances 5
sudo tor-switch create-multiple-instances 3 performance
sudo tor-switch create-multiple-instances 10 worker
sudo tor-switch create-multiple-instances 5 region
sudo tor-switch create-multiple-instances 3 node
sudo tor-switch create-multiple-instances 3 privacy
sudo tor-switch create-multiple-instances 5 ha
sudo tor-switch create-multiple-instances 10 perf
Load Balancing
set-load-balancing-mode
Set load balancing mode
Usage:
tor-switch set-load-balancing-mode [OPTIONS]
Options:
<MODE>: Load balancing mode: round-robin, weighted or consistent-hashing
Examples:
sudo tor-switch set-load-balancing-mode round-robin
sudo tor-switch set-load-balancing-mode weighted
sudo tor-switch set-load-balancing-mode consistent-hashing
set-instance-weight
Set instance weight for load balancing
Usage:
tor-switch set-instance-weight [OPTIONS]
Options:
<INSTANCE>: Instance name<WEIGHT>: Weight value (1-100)
Examples:
sudo tor-switch set-instance-weight secondary 50
sudo tor-switch set-instance-weight tor1 50
sudo tor-switch set-instance-weight tor1 10
sudo tor-switch set-instance-weight tor2 30
sudo tor-switch set-instance-weight tor3 60
sudo tor-switch set-instance-weight performance-0 75
sudo tor-switch set-instance-weight backup 5
sudo tor-switch set-instance-weight worker-1 25
sudo tor-switch set-instance-weight ha-1 30
sudo tor-switch set-instance-weight ha-2 25
sudo tor-switch set-instance-weight ha-3 20
sudo tor-switch set-instance-weight ha-4 15
sudo tor-switch set-instance-weight ha-5 10
torrify-system-iptables-load-balanced
Torrify with iptables load balancing. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-iptables-load-balanced [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-iptables-load-balanced
torrify-system-nftables-load-balanced
Torrify with nftables load balancing. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-nftables-load-balanced [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-nftables-load-balanced
prepare-tor
Pre-warm Tor instances and verify circuit readiness without applying firewall rules
Usage:
tor-switch prepare-tor [OPTIONS]
Examples:
sudo tor-switch prepare-tor
Main Tor Management
validate-torrc-main
Validate main Tor configuration
Usage:
tor-switch validate-torrc-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch validate-torrc-main --maintor
tor-switch validate-torrc-main --maintor --json
read-main-tor-config
Display main Tor settings (ports, exit/exclude nodes, security)
Usage:
tor-switch read-main-tor-config [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch read-main-tor-config
backup-main-tor-config
Backup main Tor configuration
Usage:
tor-switch backup-main-tor-config [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
sudo tor-switch backup-main-tor-config
restore-main-tor-config
Restore main Tor configuration from backup
Usage:
tor-switch restore-main-tor-config [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)<VALUE>: Backup file name to restore (under backups/main-tor)
Examples:
sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup
set-exit-node-main
Set exit node for main Tor
Usage:
tor-switch set-exit-node-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)<VALUE>: Exit node country code(s), e.g. US or {us},{de}
Examples:
sudo tor-switch set-exit-node-main US --maintor
clear-exit-node-main
Clear exit restrictions for main Tor
Usage:
tor-switch clear-exit-node-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
sudo tor-switch clear-exit-node-main --maintor
set-exclude-node-main
Set excluded countries for main Tor
Usage:
tor-switch set-exclude-node-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)<VALUE>: Country code(s) to exclude, e.g. CN,RU or {cn},{ru}
Examples:
sudo tor-switch set-exclude-node-main CN,RU --maintor
clear-exclude-node-main
Clear exclude restrictions for main Tor
Usage:
tor-switch clear-exclude-node-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
sudo tor-switch clear-exclude-node-main
sudo tor-switch clear-exclude-node-main --maintor
list-exit-exclude-main
Show current exit/exclude settings for main Tor
Usage:
tor-switch list-exit-exclude-main [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch list-exit-exclude-main
reload-main-tor
Reload main Tor configuration (SIGHUP)
Usage:
tor-switch reload-main-tor [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
sudo tor-switch reload-main-tor
status-main-tor
Detailed status of main Tor daemon
Usage:
tor-switch status-main-tor [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch status-main-tor
verify-main-tor-dns
Verify DNS routing through main Tor
Usage:
tor-switch verify-main-tor-dns [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch verify-main-tor-dns
new-circuit-main-tor
Request new circuit for main Tor
Usage:
tor-switch new-circuit-main-tor [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
sudo tor-switch new-circuit-main-tor
check-main-tor-security
Security audit of main Tor config
Usage:
tor-switch check-main-tor-security [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch check-main-tor-security
main-tor-bandwidth
Show bandwidth usage of main Tor
Usage:
tor-switch main-tor-bandwidth [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch main-tor-bandwidth
main-tor-connections
List active connections through main Tor
Usage:
tor-switch main-tor-connections [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch main-tor-connections
main-tor-logs
Display recent main Tor logs
Usage:
tor-switch main-tor-logs [OPTIONS]
Options:
--maintor: Operate on main/system Tor daemon-i, --instance <INSTANCE>: Specify instance name (mutually exclusive with --maintor)
Examples:
tor-switch main-tor-logs
Onion Services
onion-service-create
Host a service running on this machine (127.0.0.1 or ::1) as a v3 .onion address through a Tor instance; the instance is (re)started. Needs a login (the dashboard's login, or sudo online-auth authenticate).
Usage:
tor-switch onion-service-create [OPTIONS]
Options:
--name <NAME>: Service name: 1 to 32 of a-z, 0-9 and '-'--target <ADDR:PORT>: Where the service listens: 127.0.0.1:PORT or [::1]:PORT (Tor and Kodachi ports are refused)--port <PORT>: Port visitors use on the .onion address (default 80)--instance <INSTANCE>: Tor instance that hosts it (default: the configured default instance; a dedicated instance is better; the main system Tor, tor@default, is refused)--restart-ok: Accept restarting the instance when it is running (drops its connections for 10-30 s)
Examples:
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --instance onionhost
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --restart-ok
onion-service-remove
Stop hosting an onion service and wipe its keys (the address is gone for good unless --keep-keys); the instance is restarted when running. Needs a login (the dashboard's login, or sudo online-auth authenticate).
Usage:
tor-switch onion-service-remove [OPTIONS]
Options:
--name <NAME>: Service name: 1 to 32 of a-z, 0-9 and '-'--keep-keys: Keep the keys so the same address can be used again later--restart-ok: Accept restarting the instance when it is running (drops its connections for 10-30 s)
Examples:
sudo tor-switch onion-service-remove --name blog --restart-ok
onion-service-list
List the onion services this machine hosts: name, instance, address, target and port (read-only)
Usage:
tor-switch onion-service-list [OPTIONS]
Examples:
tor-switch onion-service-list --json
onion-service-status
Live status of a hosted onion service: instance running, address, descriptor built, local target up, reachable through Tor, visitors now (read-only)
Usage:
tor-switch onion-service-status [OPTIONS]
Options:
--name <NAME>: Service name: 1 to 32 of a-z, 0-9 and '-'--no-probe: Skip the reachability test through Tor (it can take up to a minute)
Examples:
sudo tor-switch onion-service-status --name blog
Status Operations
check-tor
Check if Tor service is running via systemctl
Usage:
tor-switch check-tor [OPTIONS]
Examples:
tor-switch check-tor
check-tor-all
Check systemctl status for all Tor instances
Usage:
tor-switch check-tor-all [OPTIONS]
Examples:
tor-switch check-tor-all
torverify
Verify Tor connectivity through network check
Usage:
tor-switch torverify [OPTIONS]
Examples:
tor-switch torverify
tor-switch torverify --json-pretty
tor-status
Get comprehensive Tor service status (PID, memory, uptime)
Usage:
tor-switch tor-status [OPTIONS]
Examples:
tor-switch tor-status
tor-switch tor-status --json
tor-status-all
Get comprehensive status for all Tor instances
Usage:
tor-switch tor-status-all [OPTIONS]
Examples:
tor-switch tor-status-all
get-tor-status
Get Tor status information
Usage:
tor-switch get-tor-status [OPTIONS]
Examples:
tor-switch get-tor-status
get-tor-custom-status
Get custom Tor status
Usage:
tor-switch get-tor-custom-status [OPTIONS]
Options:
-i, --instance <INSTANCE>: Specify instance name
Examples:
tor-switch get-tor-custom-status
list-instances
List all Tor instances
Usage:
tor-switch list-instances [OPTIONS]
Examples:
tor-switch list-instances
list-instances-with-ip
List all Tor instances with IP addresses
Usage:
tor-switch list-instances-with-ip [OPTIONS]
Examples:
tor-switch list-instances-with-ip
recommended-instances
Show RAM-aware recommended Tor LB instance count (square-root model, clamped 3..20). Output includes detected RAM, current user override (if any), and the effective N the binary will use. Other Kodachi components (dashboard, helpers) should query this instead of recomputing (single source of truth).
Usage:
tor-switch recommended-instances [OPTIONS]
Examples:
tor-switch recommended-instances
show-circuits
Show the live Tor circuits of an instance: every relay with its role, country and address, plus bootstrap progress (read-only). Needs root (sudo): Tor's control cookie is readable by Tor's own user only
Usage:
tor-switch show-circuits [OPTIONS]
Options:
--instance <INSTANCE>: Target instance (optional, defaults to the default instance)
Examples:
sudo tor-switch show-circuits
sudo tor-switch show-circuits --instance kodachi_tor_inst_2 --json
System Management
which-is-active
Check active firewall system
Usage:
tor-switch which-is-active [OPTIONS]
Examples:
sudo tor-switch which-is-active
cleanup
Clean up orphaned Tor instances
Usage:
tor-switch cleanup [OPTIONS]
Options:
--thorough: Perform thorough cleanup that will also reset failed systemd units
Examples:
sudo tor-switch cleanup
clean-orphan-services
Clean orphaned services
Usage:
tor-switch clean-orphan-services [OPTIONS]
Examples:
sudo tor-switch clean-orphan-services
System Routing
torrify-system-iptables
Route all traffic through Tor via iptables. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-iptables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-iptables
detorrify-system-iptables
Stop routing traffic through Tor via iptables. DESTRUCTIVE: removes Tor protection immediately
Usage:
tor-switch detorrify-system-iptables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch detorrify-system-iptables
torrify-system-nftables
Route all traffic through Tor via nftables. DESTRUCTIVE: rewrites the live firewall immediately
Usage:
tor-switch torrify-system-nftables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch torrify-system-nftables
detorrify-system-nftables
Stop routing traffic through Tor via nftables. DESTRUCTIVE: removes Tor protection immediately
Usage:
tor-switch detorrify-system-nftables [OPTIONS]
Options:
--force: Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it
Examples:
sudo tor-switch detorrify-system-nftables
boot-restore-torrified
Restore the Tor instance pool at boot when the persisted firewall is torrified (no-op otherwise)
Usage:
tor-switch boot-restore-torrified [OPTIONS]
Examples:
sudo tor-switch boot-restore-torrified --json
firewall-guard
Check the recorded torrify and re-apply it if its firewall was removed (run by the health-control watch when the user turns it on)
Usage:
tor-switch firewall-guard [OPTIONS]
Examples:
sudo tor-switch firewall-guard --json
Timer & Automation
auto-ip-change
Enable automatic IP changes
Usage:
tor-switch auto-ip-change [OPTIONS]
Options:
<INTERVAL>: Interval for IP changes (e.g., 10m, 1h, 30s)--instance <INSTANCE>: Target instance (optional)
Examples:
sudo tor-switch auto-ip-change 10m
stop-auto-ip-change
Stop automatic IP changes
Usage:
tor-switch stop-auto-ip-change [OPTIONS]
Examples:
sudo tor-switch stop-auto-ip-change
update-ip-timer
Update IP change timer
Usage:
tor-switch update-ip-timer [OPTIONS]
Options:
<INSTANCE>: Instance name<INTERVAL>: New interval (e.g., 5m, 1h, 30s)
Examples:
sudo tor-switch update-ip-timer browsing 5m
sudo tor-switch update-ip-timer worker-1 30m
sudo tor-switch update-ip-timer streaming 1h
sudo tor-switch update-ip-timer research 15m
sudo tor-switch update-ip-timer backup 24h
sudo tor-switch update-ip-timer privacy-1 5m
sudo tor-switch update-ip-timer privacy-2 10m
sudo tor-switch update-ip-timer privacy-3 15m
sudo tor-switch update-ip-timer research 2m
update-ip-all-timer
Update timer for all instances
Usage:
tor-switch update-ip-all-timer [OPTIONS]
Options:
<INTERVAL>: New interval for all instances (e.g., 10m, 1h)
Examples:
sudo tor-switch update-ip-all-timer 10m
sudo tor-switch update-ip-all-timer 2h
sudo tor-switch update-ip-all-timer 15m
remove-ip-timer
Remove IP change timer
Usage:
tor-switch remove-ip-timer [OPTIONS]
Options:
<INSTANCE>: Instance name
Examples:
sudo tor-switch remove-ip-timer browsing
remove-ip-all-timer
Remove all IP timers
Usage:
tor-switch remove-ip-all-timer [OPTIONS]
Examples:
sudo tor-switch remove-ip-all-timer
list-ip-timers
List all IP change timers
Usage:
tor-switch list-ip-timers [OPTIONS]
Examples:
tor-switch list-ip-timers
list-auto-ip-change
List auto IP change settings
Usage:
tor-switch list-auto-ip-change [OPTIONS]
Examples:
tor-switch list-auto-ip-change
Operational Scenarios
Scenario-oriented workflows generated from the binary's built-in -e --json examples.
Scenario 1: Basic Usage
Essential operations for getting started
Step 1: Start Tor daemon
sudo tor-switch start-tor
Note
Requires sudo privileges for system-level operations
Step 2: Stop Tor daemon
sudo tor-switch stop-tor
Note
Gracefully shuts down Tor service
Step 3: Restart Tor daemon
sudo tor-switch restart-tor
Note
Combines stop and start operations
Step 4: Route DNS through Tor using iptables
sudo tor-switch torrify-system-iptables-dns
Note
Redirects all system DNS queries to Tor DNS listener
Step 5: Route DNS through Tor using nftables
sudo tor-switch torrify-system-nftables-dns
Note
Redirects all system DNS queries to Tor DNS listener
Step 6: Route all traffic through Tor
sudo tor-switch torrify-system-iptables
Note
All network traffic will be routed through Tor
Step 7: Stop routing traffic through Tor
sudo tor-switch detorrify-system-iptables
Note
Returns to normal direct internet connection
Step 8: Route all traffic through Tor via nftables
sudo tor-switch torrify-system-nftables
Note
DESTRUCTIVE: rewrites the system firewall and takes effect immediately, with no confirmation prompt. Uses the modern nftables backend. A --force (alias --yes) flag is accepted for compatibility but is not required and changes nothing.
Step 9: Stop routing traffic through Tor via nftables
sudo tor-switch detorrify-system-nftables
Note
DESTRUCTIVE: drops the Tor firewall rules and returns you to a normal direct internet connection, with no confirmation prompt. Your traffic is no longer anonymised after this.
Step 10: Check if Tor service is running
tor-switch check-tor
Note
Checks if Tor service is active via systemctl
Step 11: Verify actual Tor connectivity
tor-switch torverify
Note
Makes direct HTTP request to check.torproject.org to verify torrification
Step 12: Get new Tor circuit/IP
sudo tor-switch new-tor-circuit
Note
Forces new Tor circuit for different exit node
Scenario 2: Instance Management
Managing multiple Tor instances for performance
Step 1: Create a secondary Tor instance
sudo tor-switch create-instance secondary
Note
Multiple instances provide load balancing and redundancy
Step 2: List all available instances
tor-switch list-instances
Step 3: Start specific instance
sudo tor-switch start-instance secondary
Step 4: Stop specific instance
sudo tor-switch stop-instance secondary
Step 5: Restart specific instance
sudo tor-switch restart-instance secondary
Step 6: Restart all Tor instances
sudo tor-switch restart-all-instances
Step 7: Delete an instance permanently
sudo tor-switch delete-instance secondary
Note
This permanently removes the instance configuration
Step 8: Start all configured instances
sudo tor-switch start-all-instances
Step 9: Stop all running instances
sudo tor-switch stop-all-instances
Scenario 3: Advanced Instance Operations
Create, clone, rename and manage multiple Tor instances
Step 1: Create 5 auto-named instances
sudo tor-switch create-multiple-instances 5
Note
Useful for load balancing and redundancy
Step 2: Create 3 instances with 'performance' prefix
sudo tor-switch create-multiple-instances 3 performance
Note
Creates instances with custom naming prefix
Step 3: Create 10 worker instances
sudo tor-switch create-multiple-instances 10 worker
Note
Ideal for high-throughput operations
Step 4: Create 5 regional instances
sudo tor-switch create-multiple-instances 5 region
Note
Perfect for geographic distribution
Step 5: Create 3 node instances
sudo tor-switch create-multiple-instances 3 node
Note
Simple node-based naming
Step 6: Clone 'main' instance to 'backup'
sudo tor-switch clone-instance main backup
Note
Copies all configuration from source instance
Step 7: Rename instance
sudo tor-switch rename-instance old-name new-name
Note
Updates all references and configuration files
Step 8: List all instances with current IP addresses
tor-switch list-instances-with-ip
Note
Shows both instance names and their current exit IPs
Step 9: Show detailed information for 'streaming' instance
tor-switch show-instance streaming
Note
Shows configuration, status, and current IP information
Step 10: Set 'performance-0' as the default instance
sudo tor-switch set-default-instance performance-0
Note
Changes which instance is used for default operations
Step 11: Set weight for load balancing
sudo tor-switch set-instance-weight secondary 50
Note
Used for load balancing when multiple instances are active
Step 12: Delete all instances except default
sudo tor-switch delete-all-instances
Note
Preserves default instance for basic functionality
Step 13: Delete ALL instances including default
sudo tor-switch delete-all-instances-with-default
Note
WARNING: Removes all instances
Scenario 4: Monitoring & Status
Checking system status and verifying operations
Step 1: Get detailed Tor status
tor-switch tor-status
Step 2: Detailed status in JSON format
tor-switch tor-status --json
Note
Machine-readable output for scripts. bootstrap_progress (0 to 100) is how far Kodachi's Tor pool has bootstrapped, the lowest of the instances that answered; it is null, with bootstrap_reason saying why, when no instance could be read (for example without sudo). bootstrap_instances counts the instances asked, answered and done
Step 3: Check Tor status for all instances
tor-switch check-tor-all
Note
Quick health check across all instances
Step 4: Verify if system traffic is routed through Tor
tor-switch torverify
Note
Makes HTTP request to check.torproject.org API to verify torrification
Step 5: Verify Tor connectivity with detailed JSON output
tor-switch torverify --json-pretty
Note
Useful for scripts and automation
Step 6: Get detailed status for all instances
tor-switch tor-status-all
Note
After torrify the main service (tor@default) is stopped on purpose; while every pool instance runs the overall status stays success and main_inactive_expected reads true
Step 7: Get Tor daemon status
tor-switch get-tor-status
Note
Quick status check - use tor-status for detailed report
Step 8: Show RAM-aware recommended load-balancing instance count
tor-switch recommended-instances
Note
Read-only single source of truth (square-root model). Other components should query this instead of recomputing
Step 9: See which relays carry your traffic right now: guard, middle and exit of every circuit, with country and address
sudo tor-switch show-circuits
Note
Read-only: it only asks Tor (GETINFO), it never builds or closes a circuit. It needs sudo because an instance's control cookie is readable by root only. Countries come from Tor's GeoIP database; ?? means unknown.
Step 10: Circuit view of one pool instance as JSON (for the dashboard and scripts)
sudo tor-switch show-circuits --instance kodachi_tor_inst_2 --json
Note
Fails with a clear message when the instance is not running or its control port does not answer.
Scenario 5: Troubleshooting
Debug and resolve common issues
Step 1: Clean up orphaned processes
sudo tor-switch cleanup
Note
Use when experiencing startup issues
Step 2: Clean orphaned Tor instances and services
sudo tor-switch cleanup
Note
Removes orphaned instances and service files
Step 3: Clean orphaned services
sudo tor-switch clean-orphan-services
Step 4: New circuits for all instances
sudo tor-switch new-tor-circuit-all
Note
Refreshes exit IPs for all active instances
Scenario 6: Exit Node Management
Control and configure Tor exit nodes for geographic routing and privacy. set-exit-node and set-exclude-node accept a 2-letter ISO country code (us, de, ch) or one of these group aliases: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world. Prefix a group with random- (random-europe, random-14eyes, random-low-volume) to pin one randomly chosen country from that group, or use `random` on its own for one random country worldwide.
Step 1: Route via United States
sudo tor-switch set-exit-node us
Note
Affects the default Tor instance. Traffic will exit through US-based Tor nodes
Step 2: Set UK exit for specific instance
sudo tor-switch set-exit-node gb --instance secondary
Note
Instance-specific exit node configuration
Step 3: Set Germany exit for streaming instance
sudo tor-switch set-exit-node de --instance streaming
Note
Useful for geo-restricted content
Step 4: Set Switzerland exit for secure instance
sudo tor-switch set-exit-node ch --instance secure
Note
Privacy-friendly jurisdiction
Step 5: Random exit node selection
sudo tor-switch set-exit-node random
Note
Random exit selection changes country selection; it does not guarantee anonymity
Step 6: Allow exit nodes from every country in the country-group table
sudo tor-switch set-exit-node all-world
Note
Widest possible exit set. Unlike `random`, which pins one randomly chosen country, this lets Tor pick freely from every country.
Step 7: Random European exit node
sudo tor-switch set-exit-node random-europe
Note
Stay within European jurisdiction
Step 8: Random Asian exit node
sudo tor-switch set-exit-node random-asia
Note
Exit through Asian infrastructure
Step 9: Random African exit node
sudo tor-switch set-exit-node random-africa
Note
Exit through African networks
Step 10: Random North American exit
sudo tor-switch set-exit-node random-north-america
Note
US, Canada, or Mexico exit
Step 11: Random South American exit
sudo tor-switch set-exit-node random-south-america
Note
Latin American exit points
Step 12: Random Oceania exit node
sudo tor-switch set-exit-node random-oceania
Note
Australia, NZ, or Pacific islands
Step 13: Random Middle Eastern exit
sudo tor-switch set-exit-node random-middle-east
Note
Middle Eastern exit points
Step 14: Random Five Eyes exit
sudo tor-switch set-exit-node random-5eyes
Note
US, GB, CA, AU, NZ
Step 15: Random Nine Eyes exit
sudo tor-switch set-exit-node random-9eyes
Note
5eyes + DK, FR, NL, NO
Step 16: Random Fourteen Eyes exit
sudo tor-switch set-exit-node random-14eyes
Note
9eyes + DE, BE, IT, ES, SE
Step 17: Random high-traffic exit
sudo tor-switch set-exit-node random-high-volume
Note
Better performance and anonymity
Step 18: Random low-traffic exit
sudo tor-switch set-exit-node random-low-volume
Note
Less common exit points
Step 19: Route through any European country
sudo tor-switch set-exit-node europe
Note
Countries: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA
Step 20: Route through any Asian country
sudo tor-switch set-exit-node asia
Note
Countries: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN
Step 21: Route through any African country
sudo tor-switch set-exit-node africa
Note
Countries: EG, KE, MA, NG, SC, TN, ZA
Step 22: Route through North America
sudo tor-switch set-exit-node north-america
Note
US, Canada, or Mexico
Step 23: Route through South America
sudo tor-switch set-exit-node south-america
Note
Countries: AR, BR, CL, CO, PE, UY, VE
Step 24: Route through Oceania
sudo tor-switch set-exit-node oceania
Note
Countries: AU, NZ
Step 25: Route through Middle East
sudo tor-switch set-exit-node middle-east
Note
Countries: AE, IL, IR, LB, OM, QA, SA, TR
Step 26: Use Five Eyes countries
sudo tor-switch set-exit-node 5eyes
Note
US, GB, CA, AU, NZ
Step 27: Use Nine Eyes countries
sudo tor-switch set-exit-node 9eyes
Note
5eyes + Denmark, France, Netherlands, Norway
Step 28: Use Fourteen Eyes countries
sudo tor-switch set-exit-node 14eyes
Note
9eyes + Germany, Belgium, Italy, Spain, Sweden
Step 29: Use high-traffic countries
sudo tor-switch set-exit-node high-volume
Note
Affects default instance. High-volume countries: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA
Step 30: Use low-traffic countries
sudo tor-switch set-exit-node low-volume
Note
Affects default instance. Countries excluding high-volume and 14eyes nations for uniqueness
Step 31: Set Canada for all instances
sudo tor-switch set-exit-node-all ca
Note
Applies setting to all configured instances
Step 32: Clear exit node restrictions
sudo tor-switch clear-exit-node
Note
Returns to default random exit selection
Step 33: Exclude specific countries
sudo tor-switch set-exclude-node cn,ru,ir
Note
Prevents routing through specified countries
Step 34: Exclude Five Eyes countries
sudo tor-switch set-exclude-node 5eyes
Note
US, GB, CA, AU, NZ
Step 35: Exclude Nine Eyes countries
sudo tor-switch set-exclude-node 9eyes
Note
5eyes + Denmark, France, Netherlands, Norway
Step 36: Exclude Fourteen Eyes countries
sudo tor-switch set-exclude-node 14eyes
Note
9eyes + Germany, Belgium, Italy, Spain, Sweden
Step 37: Exclude all European countries
sudo tor-switch set-exclude-node europe
Note
Excludes: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA
Step 38: Exclude all Asian countries
sudo tor-switch set-exclude-node asia
Note
Excludes: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN
Step 39: Exclude North American countries
sudo tor-switch set-exclude-node north-america
Note
US, Canada, Mexico excluded
Step 40: Exclude high-traffic countries
sudo tor-switch set-exclude-node high-volume
Note
Excludes: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA
Step 41: Exclude low-traffic countries
sudo tor-switch set-exclude-node low-volume
Note
Use only high-traffic exit nodes
Step 42: Exclude one random high-traffic country
sudo tor-switch set-exclude-node random-high-volume
Note
Randomly blocks one popular exit country
Step 43: Exclude one random low-traffic country
sudo tor-switch set-exclude-node random-low-volume
Note
Randomly blocks one uncommon exit country
Step 44: Exclude Asia for secure instance
sudo tor-switch set-exclude-node asia --instance secure
Note
Instance-specific exclusion
Step 45: Exclude 14eyes for privacy instance
sudo tor-switch set-exclude-node 14eyes --instance privacy-1
Note
Maximum privacy configuration
Step 46: Exclude France for all instances
sudo tor-switch set-exclude-node-all fr
Note
Global exclusion across all instances
Step 47: Clear all excluded countries
sudo tor-switch clear-exclude-node-main
Note
Resets to default behavior
Step 48: Clear excluded nodes for all instances
sudo tor-switch clear-exclude-node-all
Note
Global clear matching set-exclude-node-all scope
Step 49: Clear exit restrictions for all instances
sudo tor-switch clear-exit-node-all
Note
All instances return to random exit selection
Scenario 7: Load Balancing (Native Kernel-Level)
Native load balancing using iptables/nftables firewall rules
Step 1: Sequential distribution
sudo tor-switch set-load-balancing-mode round-robin
Note
Each new connection uses the next Tor instance in order
Step 2: Weight-based distribution
sudo tor-switch set-load-balancing-mode weighted
Note
Routes traffic based on instance weights
Step 3: Client IP affinity for session persistence
sudo tor-switch set-load-balancing-mode consistent-hashing
Note
Same client IP always routes to same Tor instance
Step 4: Set weight for specific instance
sudo tor-switch set-instance-weight tor1 50
Note
Only affects weighted mode distribution
Step 5: Set low weight for minimal traffic
sudo tor-switch set-instance-weight tor1 10
Note
10% of traffic when using weighted mode
Step 6: Set moderate weight for balanced traffic
sudo tor-switch set-instance-weight tor2 30
Note
30% of traffic distribution
Step 7: Set high weight for primary traffic
sudo tor-switch set-instance-weight tor3 60
Note
60% of traffic - primary instance
Step 8: High weight for performance instance
sudo tor-switch set-instance-weight performance-0 75
Note
Prioritize high-performance instance
Step 9: Minimal weight for backup instance
sudo tor-switch set-instance-weight backup 5
Note
Mostly idle, used for failover
Step 10: Equal weight for worker instances
sudo tor-switch set-instance-weight worker-1 25
Note
4 workers at 25% each = equal distribution
Step 11: Show current load balancing setup
tor-switch display-load-balancing-config
Step 12: Apply load balanced routing (iptables)
sudo tor-switch torrify-system-iptables-load-balanced
Note
Routes traffic through multiple Tor instances using iptables
Step 13: Apply load balanced routing (nftables)
sudo tor-switch torrify-system-nftables-load-balanced
Note
Modern firewall load balanced routing using nftables
Step 14: Pre-warm Tor instances and verify circuit readiness
sudo tor-switch prepare-tor
Note
Warms instances without applying any firewall rules. Run it before torrify to avoid first-connection delays
Scenario 8: HAProxy Integration (Application-Level Proxy)
HAProxy provides advanced application-level load balancing
Step 1: Generate config with round-robin algorithm
sudo tor-switch generate-haproxy-config roundrobin 9055
Note
Each server is used in turns on port 9055
Step 2: Generate config with source IP hash
sudo tor-switch generate-haproxy-config source 8080
Note
IP hash persistence on port 8080
Step 3: Generate config with least connections
sudo tor-switch generate-haproxy-config leastconn 9000
Note
Routes to instance with fewest active connections
Step 4: Generate config with random selection
sudo tor-switch generate-haproxy-config random 8888
Note
Randomly selects backend for each connection
Step 5: Start HAProxy service
sudo tor-switch haproxy-start
Step 6: Check HAProxy status
tor-switch haproxy-status
Step 7: Stop HAProxy service
sudo tor-switch haproxy-stop
Step 8: Show available HAProxy algorithms
tor-switch list-haproxy-modes
Note
roundrobin, source, leastconn, random
Scenario 9: Timer Management and Automation
Automatic IP rotation and timer-based operations
Step 1: Auto IP change every 10 minutes
sudo tor-switch auto-ip-change 10m
Note
Creates new Tor circuit for default instance to get new exit IP
Step 2: Set timer for specific instance
sudo tor-switch update-ip-timer browsing 5m
Step 3: Set 30-minute timer for worker instance
sudo tor-switch update-ip-timer worker-1 30m
Note
Balanced rotation for moderate privacy
Step 4: Set hourly timer for streaming
sudo tor-switch update-ip-timer streaming 1h
Note
Less frequent changes for stable connections
Step 5: Set 15-minute timer for research
sudo tor-switch update-ip-timer research 15m
Note
Frequent rotation for privacy-focused browsing
Step 6: Set daily timer for backup instance
sudo tor-switch update-ip-timer backup 24h
Note
Minimal rotation for long-running operations
Step 7: Set 10-minute timer for all instances
sudo tor-switch update-ip-all-timer 10m
Note
Synchronizes rotation across all instances
Step 8: Set 2-hour timer for all instances
sudo tor-switch update-ip-all-timer 2h
Note
Stable rotation for production workloads
Step 9: List all IP change timers
tor-switch list-ip-timers
Step 10: Remove timer for instance
sudo tor-switch remove-ip-timer browsing
Step 11: Stop auto IP change
sudo tor-switch stop-auto-ip-change
Step 12: Set timer for all instances
sudo tor-switch update-ip-all-timer 15m
Note
Synchronizes IP rotation across instances
Step 13: Remove all IP change timers
sudo tor-switch remove-ip-all-timer
Note
Removes all automatic IP rotation timers from all instances
Step 14: List automatic IP change settings
tor-switch list-auto-ip-change
Scenario 10: DNS Management
Configure and manage DNS routing through Tor. AUTH NOTE: start-tor-dns-* and torrify-system-*-dns are anonymity-affecting mutations and REQUIRE an active online-auth session (`sudo online-auth authenticate` first). stop-tor-dns-* is exempt: it is in the emergency/recovery list and works even when auth is unavailable.
Step 1: Start Tor DNS listener with iptables
sudo tor-switch start-tor-dns-iptables
Note
Sets up the Tor DNS listener on the instance's own DNSPort, 16000 for the first instance. AUTH REQUIRED: run `sudo online-auth authenticate` first.
Step 2: Stop Tor DNS routing
sudo tor-switch stop-tor-dns-iptables
Note
Emergency/recovery exempt: works without auth.
Step 3: Route all DNS through Tor
sudo tor-switch torrify-system-dns
Note
Auto-detects and uses whichever firewall backend is active. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt.
Step 4: Start Tor DNS listener with nftables
sudo tor-switch start-tor-dns-nftables
Note
Sets up the Tor DNS listener on the instance's own DNSPort, 16000 for the first instance. AUTH REQUIRED: run `sudo online-auth authenticate` first.
Step 5: Stop Tor DNS (nftables)
sudo tor-switch stop-tor-dns-nftables
Note
Emergency/recovery exempt: works without auth.
Step 6: Route DNS through Tor using iptables
sudo tor-switch torrify-system-iptables-dns
Note
Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt.
Step 7: Route DNS through Tor using nftables
sudo tor-switch torrify-system-nftables-dns
Note
Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt.
Scenario 11: DNS Verification
Test and verify DNS routing through Tor
Step 1: Verify Tor DNS resolution of .onion addresses
tor-switch verify-tor-dns
Note
Resolves .onion addresses to verify DNS goes through Tor
Step 2: Verify DNS resolution for all Tor instances
tor-switch verify-tor-dns-all
Note
Tests .onion resolution for all configured Tor instances
Step 3: Verify .onion resolution using system DNS
tor-switch verify-tor-dns-direct
Note
Uses system resolver to test .onion domain resolution
Step 4: Verify .onion resolution via Tor DNS port
tor-switch verify-tor-dns-port
Note
Uses instance's DNS port to test .onion resolution
Step 5: Verify Tor DNS and capture the result for a script
tor-switch verify-tor-dns --json
Note
The verify-tor-dns* commands take no arguments: they always test the currently active Tor DNS listener. To check one specific instance, make it the default first with set-default-instance, or use verify-tor-dns-all to cover every instance.
Scenario 12: Firewall Operations
Manage iptables and nftables firewall rules. The flush-* and torrify/detorrify commands change the live firewall the moment you run them, with no confirmation prompt. A --force (alias --yes) flag is still accepted for backwards compatibility, but it is NOT a confirmation gate and passing it changes nothing.
Step 1: Flush iptables rules
sudo tor-switch flush-iptables
Note
DESTRUCTIVE, NOT REVERSIBLE: drops every iptables rule and policy, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt.
Step 2: List current iptables rules
sudo tor-switch list-iptables
Step 3: Check active firewall
sudo tor-switch which-is-active
Step 4: Flush nftables rules
sudo tor-switch flush-nftables
Note
DESTRUCTIVE, NOT REVERSIBLE: drops every nftables rule, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt.
Step 5: List current nftables rules
sudo tor-switch list-nftables
Step 6: List NAT rules
sudo tor-switch list-iptables-nat
Note
Shows network address translation rules
Step 7: Rebuild the Tor instance pool at boot when the persisted firewall is already torrified
sudo tor-switch boot-restore-torrified --json
Note
You normally never run this by hand: kodachi-tor-pool-boot.service runs it at every boot. It is auth-exempt so it still works before online-auth is up. On a non-torrified system it does nothing.
Step 8: Check the torrify recorded in this boot and put its firewall back if something removed it
sudo tor-switch firewall-guard --json
Note
The check the firewall watch runs; you can run it yourself. With no torrify recorded in this boot it changes nothing. It needs no login.
Scenario 13: Configuration Management
Manage Tor configuration files and validation
Step 1: Validate torrc configuration
tor-switch validate-torrc
Note
Checks syntax without starting Tor
Step 2: Reload configuration
sudo tor-switch reload-tor-config
Note
Applies changes without restart
Step 3: Generate new control password
sudo tor-switch generate-new-tor-password
Step 4: Clean custom configuration
sudo tor-switch clean-torrc-custom
Step 5: Clean all custom configurations
sudo tor-switch clean-torrc-custom-all
Step 6: Reload all configurations
sudo tor-switch reload-tor-config-all
Step 7: Generate passwords for all instances
sudo tor-switch generate-new-tor-password-all
Step 8: Get custom configuration status
tor-switch get-tor-custom-status
Scenario 14: Backup and Restore
Backup and restore Tor instance configurations
Step 1: Backup configuration
sudo tor-switch backup-config
Step 2: List available backups
tor-switch list-backups
Step 3: Restore from backup
sudo tor-switch restore-config backup-2025-01-28
Note
Restores configuration and restarts instances
Step 4: Backup all configurations
sudo tor-switch backup-config-all
Step 5: Restore all from backup
sudo tor-switch restore-config-all backup-2025-01-28
Note
Restores complete multi-instance setup
Scenario 15: Main Tor Management (TROUBLESHOOTING ONLY)
WARNING, TROUBLESHOOTING ONLY: these commands edit the shared system Tor daemon (/etc/tor/torrc), not a Kodachi instance. Changing main Tor affects every application that talks to the system Tor and can break instance routing. For all normal work use the Kodachi instance commands instead. Add --maintor to target the system daemon explicitly.
Step 1: Validate main Tor configuration
tor-switch validate-torrc-main --maintor
Note
Validates /etc/tor/torrc syntax and settings
Step 2: Display main Tor configuration
tor-switch read-main-tor-config
Note
Shows ports, exit/exclude nodes, and security settings
Step 3: Backup main Tor configuration
sudo tor-switch backup-main-tor-config
Note
Creates timestamped backup in backups/main-tor/
Step 4: Restore main Tor configuration
sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup
Note
Current config is backed up before restoring
Step 5: Set US exit node for main Tor
sudo tor-switch set-exit-node-main US --maintor
Note
Forces traffic to exit through United States
Step 6: Clear exit node restrictions
sudo tor-switch clear-exit-node-main --maintor
Note
Allows Tor to choose any exit country
Step 7: Exclude countries from circuits
sudo tor-switch set-exclude-node-main CN,RU --maintor
Note
Prevents routing through specified countries
Step 8: Clear excluded countries
sudo tor-switch clear-exclude-node-main --maintor
Note
Removes all country exclusions
Step 9: Show exit/exclude settings
tor-switch list-exit-exclude-main
Note
Displays current geographic routing rules
Step 10: Reload main Tor configuration
sudo tor-switch reload-main-tor
Note
Sends SIGHUP signal to apply config changes
Step 11: Get main Tor daemon status
tor-switch status-main-tor
Note
Shows systemctl status and port information
Step 12: Verify DNS routing through Tor
tor-switch verify-main-tor-dns
Note
Tests DNS resolution via tor-resolve
Step 13: Request new Tor circuit
sudo tor-switch new-circuit-main-tor
Note
Gets new IP by building fresh circuit
Step 14: Security audit main Tor
tor-switch check-main-tor-security
Note
Checks for security misconfigurations
Step 15: Show Tor bandwidth usage
tor-switch main-tor-bandwidth
Note
Displays active SOCKS connections count
Step 16: List active Tor connections
tor-switch main-tor-connections
Note
Shows established connections on SOCKS port
Step 17: Display recent Tor logs
tor-switch main-tor-logs
Note
Shows last 50 lines from Tor log or journald
Step 18: Validate with JSON output
tor-switch validate-torrc-main --maintor --json
Note
Machine-readable output for scripting
Scenario 16: Advanced Workflows
Complete workflow examples for common use cases
Step 1: Complete privacy-focused setup
# Privacy-focused browsing setup
sudo tor-switch create-multiple-instances 3 privacy
sudo tor-switch set-exclude-node 5eyes --instance privacy-1
sudo tor-switch set-exclude-node 9eyes --instance privacy-2
sudo tor-switch set-exclude-node 14eyes --instance privacy-3
sudo tor-switch update-ip-timer privacy-1 5m
sudo tor-switch update-ip-timer privacy-2 10m
sudo tor-switch update-ip-timer privacy-3 15m
Note
Avoids surveillance alliance countries with rapid rotation
Step 2: Geographic distribution setup
# Regional distribution setup
sudo tor-switch create-instance europe
sudo tor-switch create-instance asia
sudo tor-switch create-instance americas
sudo tor-switch set-exit-node europe --instance europe
sudo tor-switch set-exit-node asia --instance asia
sudo tor-switch set-exit-node north-america --instance americas
Note
Access region-specific content simultaneously
Step 3: High-availability load balanced setup
# High-availability setup
sudo tor-switch create-multiple-instances 5 ha
sudo tor-switch set-load-balancing-mode weighted
sudo tor-switch set-instance-weight ha-1 30
sudo tor-switch set-instance-weight ha-2 25
sudo tor-switch set-instance-weight ha-3 20
sudo tor-switch set-instance-weight ha-4 15
sudo tor-switch set-instance-weight ha-5 10
sudo tor-switch torrify-system-iptables-load-balanced
Note
Redundant instances with priority-based traffic distribution
Step 4: Research and testing environment
# Research and testing setup
sudo tor-switch create-instance research
sudo tor-switch create-instance testing
sudo tor-switch set-exit-node random-low-volume --instance research
sudo tor-switch set-exit-node high-volume --instance testing
sudo tor-switch update-ip-timer research 2m
tor-switch verify-tor-dns-all
Note
Separate instances for different testing scenarios. verify-tor-dns takes no --instance flag, so verify-tor-dns-all is used to cover both instances at once.
Step 5: Maximum performance configuration
# Performance-optimized setup
sudo tor-switch create-multiple-instances 10 perf
sudo tor-switch set-load-balancing-mode round-robin
sudo tor-switch generate-haproxy-config
sudo tor-switch haproxy-start
tor-switch haproxy-status
Note
10 instances with HAProxy for maximum throughput
Step 6: Complete reset to default state
# Clean slate reset
sudo tor-switch stop-all-instances
sudo tor-switch cleanup
sudo tor-switch flush-iptables
sudo tor-switch restart-tor
tor-switch check-tor
Note
Removes all custom configurations and instances
Step 7: Complete system status check
# Monitoring and diagnostics
tor-switch tor-status-all
tor-switch list-instances
tor-switch list-ip-timers
tor-switch display-load-balancing-config
tor-switch haproxy-status
Note
Comprehensive view of all Tor configurations
Scenario 17: Bridge Management (Pluggable Transports)
obfs4 bridges allow Tor to bootstrap over XTLS-Vision Reality VPN connections, where plain Tor fails because Vision inspects the nested TLS. Bridges wrap the Tor handshake in an opaque layer that Vision cannot identify.
Step 1: Store a single obfs4 bridge and activate it for all instances
sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'
Note
Needs obfs4proxy or lyrebird. Get lines at https://bridges.torproject.org/. All instances are restarted automatically.
Step 2: Load multiple bridge lines from a file (one per line, # comments ignored)
sudo tor-switch set-bridges --from-file /tmp/bridges.txt
Note
Recommended for the dashboard: write bridge lines to a temp file then pass --from-file.
Step 3: Use a snowflake bridge where obfs4 bridges are blocked (WebRTC through volunteer proxies)
sudo tor-switch set-bridges --transport snowflake --bridge 'snowflake 192.0.2.3:80 <FINGERPRINT> fingerprint=<FINGERPRINT> url=https://<broker-front>/ fronts=<cdn-host> ice=stun:<stun-host>:3478'
Note
Needs the snowflake-client package: sudo apt install snowflake-client. Its lines ship with Tor Browser's built-in bridges. Copy the full line, including url=, fronts= and ice=; the IP:PORT is only a label. snowflake-client before 2.7 (Debian 13 ships 2.5.1) reads only front=, so tor-switch also writes front= with the first fronts= domain into torrc. Slower than obfs4.
Step 4: Use a meek bridge: Tor traffic carried inside HTTPS to a CDN front
sudo tor-switch set-bridges --transport meek_lite --bridge 'meek_lite 192.0.2.18:80 <FINGERPRINT> url=https://<meek-host>/ front=<front-host>'
Note
Needs obfs4proxy or lyrebird. obfs4proxy implements meek_lite and is installed, so nothing extra is needed. Its lines ship with Tor Browser's built-in bridges. url= must be https://.
Step 5: Use webtunnel bridges: Tor traffic inside what looks like an ordinary HTTPS site
sudo tor-switch set-bridges --transport webtunnel --from-file /tmp/webtunnel-bridges.txt
Note
Needs lyrebird, which Debian does not package: copy lyrebird from Tor Browser's Browser/TorBrowser/Tor/PluggableTransports folder to /usr/local/bin. Get lines at https://bridges.torproject.org/. Refused with a clear error if lyrebird is not found.
Step 6: Show stored bridge config and obfs4proxy detection result as JSON
tor-switch list-bridges --json
Note
Read-only, no sudo required.
Step 7: Validate stored bridge lines and check the transport's plugin without making changes
tor-switch test-bridges --json
Note
Read-only, no sudo required. Use before enable-bridges to confirm lines are well-formed.
Step 8: Revert to direct Tor (strip bridge block, restart all instances)
sudo tor-switch disable-bridges
Note
Preserves stored bridge lines so you can re-enable later.
Step 9: Re-activate previously stored bridges for all instances
sudo tor-switch enable-bridges
Note
Requires at least one bridge stored via set-bridges.
Step 10: Remove all stored bridges and revert all instances to direct Tor
sudo tor-switch clear-bridges
Note
Permanently removes bridges.json entries. Use disable-bridges instead to keep them for later.
Step 11: Use all stored bridges simultaneously (default behavior)
sudo tor-switch set-bridge-mode --mode all
Note
Re-applies the bridge config and restarts all instances.
Step 12: Randomly pick 2 bridges from the stored list each time bridges are applied
sudo tor-switch set-bridge-mode --mode random --count 2
Note
Useful when you have many bridges and want to vary which ones are used.
Step 13: Pick a fresh random subset of bridges and restart all instances
sudo tor-switch rotate-bridges
Note
In 'all' mode this re-applies without changing the active set. In 'random' mode a new subset is picked.
Step 14: Install a cron job that calls rotate-bridges every 15 minutes
sudo tor-switch bridge-rotate-timer 15m
Note
Minimum interval is 1 minute. Tagged with KODACHI_BRIDGE_ROTATE in crontab. Only one timer can be active; running again replaces the previous one.
Step 15: Remove the bridge rotation cron job
sudo tor-switch stop-bridge-rotate-timer
Note
Reports cleanly if no timer was installed.
Scenario 18: Help & Documentation
Built-in help and usage examples
Step 1: Show help information
tor-switch show-help
Note
Equivalent to -h; read-only, no privileges required
Step 2: Show usage examples
tor-switch show-examples
Note
Equivalent to -e; read-only, no privileges required
Scenario 19: Onion Services (host a .onion address)
Publish a service that runs on this machine as a v3 .onion address through a Tor instance, and watch whether it is up, its descriptor is built and it is reachable. Only 127.0.0.1 and ::1 targets are accepted, and Tor or Kodachi ports are refused.
Step 1: First create a dedicated instance, so the service is not linked to the instance you browse through
sudo tor-switch create-instance onionhost
Note
Recommended. A new, stopped instance also needs no --restart-ok.
Step 2: Publish a local web server on port 8080 as http://<address>.onion
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --instance onionhost
Note
The keys stay in the instance's own data directory and are never shown. Publishing can take a minute. Needs a login (the dashboard's login, or sudo online-auth authenticate).
Step 3: Host it on the configured default instance, accepting that its connections drop for 10-30 s while it restarts
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --restart-ok
Note
Without --restart-ok a running instance is refused, with the list of connections that would drop.
Step 4: Live health: instance running, descriptor built, local target up, reachable through Tor and visitors now
sudo tor-switch onion-service-status --name blog
Note
Read-only, but it needs sudo to read the instance's control port. Health is healthy, degraded, down, pending or instance_missing. Add --no-probe to skip the reachability test.
Step 5: Every hosted service with its instance, address, target and port
tor-switch onion-service-list --json
Note
A service whose instance was deleted shows instance_missing and no address.
Step 6: Stop hosting it and wipe its keys: the address is gone for good
sudo tor-switch onion-service-remove --name blog --restart-ok
Note
Add --keep-keys to keep the address for later. The output says exactly what the wipe did and did not achieve. Needs a login (the dashboard's login, or sudo online-auth authenticate).
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
NO_COLOR |
Disable all colored output when set | unset | 1|true|yes (any value disables color) |
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error (with --json, the error's code field names its kind) |
| 2 | Invalid arguments |