How-To: User and Group Bypass (Split Tunneling)

This guide provides practical recipes for running specific applications, system accounts, or local development servers outside the Tor transparent proxy using TTP split-tunneling features.

1. Exempting a Dedicated System User

To run a dedicated user account outside Tor proxying:

# Start TTP excluding the 'clearnet-user' account
sudo ttp start --bypass-user clearnet-user

Launching a Dedicated Clearnet Browser

Execute a web browser instance as the bypassed user:

# Launch Firefox as the bypassed user
sudo -u clearnet-user firefox &

Any TCP connection initiated by processes owned by clearnet-user bypasses the inet ttp nftables table and routes directly via standard network interfaces.

2. Exempting a System Group

To exempt all users belonging to a specific system group:

# Start TTP excluding the 'bypass-users' group
sudo ttp start --bypass-group bypass-users

Add your local user to the bypass group:

sudo usermod -aG bypass-users $USER

Note that group membership updates require re-logging or spawning a new shell via sg bypass-users.

3. Running Local Web Servers Unproxied

To host a local development web server (e.g. Node.js, Python, or Nginx) accessible over standard ISP networks while TTP is active:

# Run local Python HTTP server under a bypassed user
sudo -u clearnet-user python3 -m http.server 8080

Alternatively, use sudo ttp bypass to run the server in a transient systemd scope:

sudo ttp bypass python3 -m http.server 8080

4. One-Off Command Execution (`sudo ttp bypass`)

To execute a single command as an unproxied process without creating permanent user exemptions:

# Perform a direct curl request
sudo ttp bypass curl -s https://api.ipify.org

Security Considerations

Cleartext Exposure

Traffic generated by bypassed UIDs/GIDs does not pass through Tor. Avoid running applications carrying sensitive credentials or personal identifiers under a bypassed identity.