How guardianproject/orbot-android works
1. What this repo is
Orbot is an Android app that turns the device into a Tor-powered proxy/VPN client. Its core job is to start and supervise Tor, route selected app traffic through it, and provide a UI for connection, bridge, onion-service, and privacy settings.
2. Top-level runtime boundaries
There are two important execution domains: the main Android app process and a separate :tor process for Tor itself. The readme notes that Tor now runs as its own Linux process, which cleanly separates UI/service logic from the actual Tor daemon logs and lifecycle.
3. User-facing application layer
OrbotActivity, BaseActivity, and the fragments under ui/ form the main interaction surface. The app uses a bottom-navigation style UI with major sections such as Connect, App Manager, Kindness, and More. Navigation and screen layout are defined in res/navigation and res/layout*.
4. Connection management subsystem
The ui/connect package is the main control panel for starting/stopping the Tor connection, choosing how to connect, selecting bridges, and handling permission prompts. ConnectViewModel and ConnectUiState suggest a state-driven UI layer that reflects service status, logs, and connection setup results.
5. Tor service orchestration
The service package is the backend coordinator. OrbotService, StartTorReceiver, OnBootReceiver, and Notifications manage startup, restarts, boot handling, foreground-service behavior, and ongoing status notifications. OrbotConstants centralizes service-wide config and intent/action names.
6. Traffic routing and VPN boundary
The VPN path is implemented under service/vpn with OrbotVpnManager, VpnServicePrepareWrapper, and TorifiedApp/TorifiedAppWrapper. This subsystem decides which apps are “torified” and likely controls Android VPN routing so selected app traffic goes through Tor rather than the normal network stack.
7. Native tunnel and low-level networking
The repo includes native code under app/src/main/jni/hev-socks5-tunnel and prebuilt libraries in jniLibs. This indicates a lower-level SOCKS5/tunneling layer used to bridge Android networking to Tor or to support VPN transport. ShadowSocks.kt, TProxyService.kt, and TorConfig.kt are the main Java/Kotlin pieces around this networking stack.
8. Circumvention and bridge acquisition
The service/circumvention package handles blocked-network resilience. It includes Bridge, BuiltInBridges, Transport, SmartConnect, AutoConf, MoatApi, and MoatTunnel, which together suggest: built-in bridge catalogs, transport selection, automatic configuration, and bridge retrieval through Moat. Assets like builtin-bridges.json, fronts, and country-specific dns-*.json files are part of this subsystem’s offline/region-aware data.
9. Kindness / snowflake proxy mode
The ui/kindness package implements a separate feature for running a Snowflake proxy, likely to help other users reach Tor. SnowflakeProxyService, SnowflakeProxyWrapper, PowerConnectionReceiver, and related dialogs indicate a power/network-state-sensitive background service with user controls and test flows. This is a distinct subsystem from normal client connection mode.
10. Onion service and client authorization management
The ui/v3onionservice area manages hosting Tor onion services and their backups/restores. A parallel clientauth package handles v3 client authorization data. These subsystems include their own activities, dialogs, content providers, databases, list adapters, and backup utilities, showing that local persistence and CRUD-style management are important here.
11. Local data and persistence
The repo contains database/schema classes for onion services and client auth, plus preference helpers in util/Prefs.kt and util/PreferenceProvider.kt. This suggests three main state stores: Android shared preferences for app settings, app-local databases for onion-service/auth records, and files/assets for bundled bridge and localization data.
12. System integration points
The app integrates with Android boot broadcast handling, quick settings tiles (ui/quicksettings), notifications, device authentication prompts, exact alarm permission handling, and battery optimization prompts. These are the main OS-facing boundaries where Orbot asks for privileges or exposes control outside the app UI.
13. Localization and regional behavior
localization/ plus Regionalization.kt and many res/values-* folders show heavy locale support. The assets dns-*.json and bridge/front data also imply region-aware behavior, likely used to adapt connection strategies for censored or restrictive environments.
14. Build, release, and external dependencies
The project is a Gradle-based Android build with Kotlin/Java plus native code, CI workflows, and Fastlane metadata/screenshots for store release. External runtime dependencies that materially affect architecture are Tor itself, the hev-socks5-tunnel native dependency, Moat/bridge discovery services, and the Android VPN/foreground-service APIs.
15. How data flows through the system
A typical flow is: user action in the UI → ViewModel/state update → service intent/receiver → Tor startup and network configuration → VPN/tunnel setup and optional bridge acquisition → live status/log updates back to the UI via notifications/state. Separate flows exist for onion-service CRUD and for Snowflake proxy operation, but they share the same Android app shell and persistence infrastructure.
Main entry points: OrbotService.java Orbot Service · nav_graph.xml Navigation · ConnectFragment.kt Connect · OrbotVpnManager.java VPN
Components 21
App Shell
Main Android process, lifecycle entrypoints, navigation, and shared UI scaffolding.
- Orbot · Main app entrypoint and user-facing shell.
app/src/main/java/org/torproject/android/OrbotActivity.kt - Base UI · Shared activity behavior and common UI plumbing.
app/src/main/java/org/torproject/android/ui/core/BaseActivity.kt - Navigation · Screen graph and layout resources for app sections.
app/src/main/res/navigation/nav_graph.xml - Connect · Main connection control surface for Tor startup and bridges.
app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt - Connect VM · State holder for connection status, setup, and log-driven UI.
app/src/main/java/org/torproject/android/ui/connect/ConnectViewModel.kt - Connect State · Structured connection state rendered by the connect screen.
app/src/main/java/org/torproject/android/ui/connect/ConnectUiState.kt - App Manager · Controls which apps are routed through Tor.
app/src/main/java/org/torproject/android/ui/AppManagerFragment.kt - More · Settings, logs, safety, and miscellaneous app controls.
app/src/main/java/org/torproject/android/ui/more/MoreFragment.kt
Tor Service
Process orchestration, startup, notifications, boot handling, and Tor lifecycle control.
- Orbot Service · Central backend that supervises Tor and app networking.
app/src/main/java/org/torproject/android/service/OrbotService.java - Startup · Boot and explicit-start receivers that wake the service.
app/src/main/java/org/torproject/android/service/StartTorReceiver.kt - Notifications · Foreground and status notifications for connection lifecycle.
app/src/main/java/org/torproject/android/service/Notifications.kt
Networking
VPN, Tor routing, and low-level tunnel integration.
- VPN · Prepares and manages Android VPN routing for torified apps.
app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java - Torified Apps · App allowlist/torification model used by the VPN layer.
app/src/main/java/org/torproject/android/service/vpn/TorifiedApp.kt - Tunnel · Low-level SOCKS/tproxy bridge between Android networking and Tor.
app/src/main/java/org/torproject/android/service/TProxyService.kt - Tor Config · Tor configuration and resource installation for runtime startup.
app/src/main/java/org/torproject/android/service/tor/TorConfig.kt
Circumvention
Bridge discovery, auto-configuration, and restricted-network connection strategies.
- Bridges · Bridge catalog, transport selection, auto-configuration, and Moat retrieval.
app/src/main/java/org/torproject/android/service/circumvention/SmartConnect.kt - Bridge Data · Bundled bridge lists and region-specific DNS/front data.
app/src/main/assets/builtin-bridges.json
Onion Services
Onion service hosting and client authorization management.
- Onion Services · Hosting and managing v3 onion services with local persistence.
app/src/main/java/org/torproject/android/ui/v3onionservice/OnionServiceActivity.java - Client Auth · v3 client authorization CRUD and backup flows.
app/src/main/java/org/torproject/android/ui/v3onionservice/clientauth/ClientAuthActivity.java
Kindness Mode
Snowflake proxy features and related background controls.
- Kindness · Snowflake proxy mode for helping others reach Tor.
app/src/main/java/org/torproject/android/ui/kindness/KindnessFragment.kt - Snowflake Proxy · Service and wrapper for running the Snowflake proxy.
app/src/main/java/org/torproject/android/ui/kindness/SnowflakeProxyService.kt
Connections 22
- Orbot → Navigation: hosts sections · Main activity renders the bottom-navigation app shell.
- Orbot → Base UI: extends · Shared activity behavior comes from the base class.
- Navigation → Connect: routes to · Navigation graph opens the connection control screen.
- Navigation → App Manager: routes to · Navigation graph opens app-routing management.
- Navigation → More: routes to · Navigation graph opens settings and logs.
- Connect → Connect VM: observes · Connect screen is driven by ViewModel state.
- Connect VM → Connect State: emits · State object represents connection lifecycle and UI status.
- Connect → Orbot Service: starts/stops · User actions turn into service commands.
- Startup → Orbot Service: launches · Boot and start receivers bring up the backend service.
- Orbot Service → Notifications: publishes status · Service keeps the foreground notification in sync.
- Orbot Service → Tor Config: configures Tor · Service prepares the Tor runtime and resources.
- Orbot Service → VPN: controls · Service delegates VPN setup and teardown.
- VPN → Torified Apps: applies policy · VPN manager uses app torification settings.
- VPN → Tunnel: routes traffic · VPN path hands traffic to the tunnel layer.
- Tunnel → Tor Config: binds to · Tunnel layer depends on Tor-side configuration.
- Connect → Bridges: selects bridges · Connect UI exposes bridge and connection-mode choices.
- Bridges → Bridge Data: loads data · Bridge selection uses bundled bridge and regional data.
- Kindness → Snowflake Proxy: controls · Kindness UI starts and monitors the proxy service.
- Snowflake Proxy → Orbot Service: shares runtime · Snowflake mode runs alongside the app/service ecosystem.
- Onion Services → Client Auth: manages auth · Onion-service hosting is paired with client authorization management.
- Onion Services → Orbot Service: uses backend · Onion-service operations depend on the Tor backend.
- More → Notifications: reads logs/status · More/settings surfaces operational information to the user.