### Install Locally Built TorVPN APK

Source: https://github.com/tpo/applications/vpn/blob/main/README.md

Installs the locally built universal debug APK of TorVPN onto a connected Android device. The '-d' flag indicates installation on a connected device, and '-t' allows test APKs to be installed. This command assumes the APK is located at 'app/build/outputs/apk/debug/app-universal-debug.apk'.

```bash
adb -d install -t app/build/outputs/apk/debug/app-universal-debug.apk
```

--------------------------------

### Clone TorVPN Repository and Navigate

Source: https://github.com/tpo/applications/vpn/blob/main/README.md

Clones the TorVPN project repository from GitLab and changes the current directory to the project root. This is the first step for building the application locally. It requires Git to be installed.

```bash
git clone https://gitlab.torproject.org/tpo/applications/vpn.git
cd vpn
```

--------------------------------

### Quick Settings Tile Integration - Kotlin

Source: https://context7.com/tpo/applications/llms.txt

The `TorVPNTileService` implements the Android Quick Settings tile, allowing users to control the VPN connection directly from the notification shade. It handles starting, stopping, and managing VPN states, including error handling and permission requests.

```kotlin
class TorVPNTileService : TileService() {

    override fun onClick() {
        when (VpnStatusObservable.statusLiveData.value) {
            CONNECTING, CONNECTED -> {
                // Stop VPN when connected or connecting
                VpnServiceCommand.stopVpn(this)
            }
            CONNECTION_ERROR -> {
                // Open app to show error details
                startMainActivity(ACTION_MAIN)
            }
            else -> {
                // Start VPN or request permission
                if (VpnServiceCommand.prepareVpn(this) == null) {
                    VpnServiceCommand.startVpn(this)
                    VpnStatusObservable.update(CONNECTING)
                } else {
                    startMainActivity(ACTION_REQUEST_VPN_PERMISSON)
                }
            }
        }
    }

    // Tile states update automatically based on VPN status
    // STATE_INACTIVE: Disconnected (ready to connect)
    // STATE_ACTIVE: Connected or connecting
    // Subtitle shows: "Connected", "Connecting", "No internet", or error message
}
```

--------------------------------

### Install Debug APK using ADB

Source: https://github.com/tpo/applications/vpn/blob/main/README.md

Installs a debug version of the TorVPN application on an Android device using the Android Debug Bridge (ADB). Requires the ADB tool to be installed and the device to be connected and recognized by ADB. This command assumes the APK file is named 'app-debug.apk' in the current directory.

```bash
adb install app/build/outputs/apk/debug/app-debug.apk
```

--------------------------------

### Configure Local Properties for Private Token

Source: https://github.com/tpo/applications/vpn/blob/main/README.md

Adds a private GitLab access token to the 'local.properties' file for accessing prebuilt AndroidOnionmasq libraries. This is an example of how to configure project-specific settings for local builds, ensuring sensitive information is not committed to version control.

```properties
gitLabPrivateToken=<YOUR_PRIVATE_ACCESS_TOKEN>
```

--------------------------------

### CSS for Active Border and Color Highlighting

Source: https://github.com/tpo/applications/vpn/blob/main/app/src/main/assets/help/offline/fa/tor-vpn/getting-started/download-and-install/index.html

This CSS snippet defines styles for elements that have an active border or text color, specifically using a primary color. It's likely used for UI elements that indicate a selected or active state within the Tor VPN interface.

```css
/*
 * [data-active-border-color-primary="./"] { border-color: var(--bs-primary) !important; border-bottom: 3px solid; margin-bottom: 1.5rem; }
 * [data-active-color-primary="./"] { color: var(--bs-primary) !important; }
 */
```

--------------------------------

### Configure VPN Profile and Routing - Kotlin

Source: https://context7.com/tpo/applications/llms.txt

The `prepareVpnProfile` function configures the Android VPN service builder, setting up routing for all IPv4 and IPv6 traffic, defining VPN interface addresses, DNS servers, and MTU. It ensures all traffic is routed through the VPN and specifies network families and meter status.

```kotlin
private fun prepareVpnProfile(): Builder {
    val builder = Builder()
    builder.setSession("TorVPN session")
    builder.addRoute("0.0.0.0", 0)           // Route all IPv4
    builder.addRoute("::", 0)                 // Route all IPv6
    builder.addAddress("169.254.42.1", 16)   // VPN interface IPv4
    builder.addAddress("fc00::", 7)           // VPN interface IPv6
    builder.addDnsServer("169.254.42.53")    // Custom DNS IPv4
    builder.addDnsServer("fe80::53")          // Custom DNS IPv6
    builder.allowFamily(OsConstants.AF_INET)
    builder.allowFamily(OsConstants.AF_INET6)
    builder.setMtu(1500)
    builder.setMetered(false)                 // Don't count as metered
    return builder
}
```

--------------------------------

### Control TorVPN Service Lifecycle

Source: https://context7.com/tpo/applications/llms.txt

Manages the VPN lifecycle including preparation, starting, and stopping. It utilizes Android's WorkManager for reliable background execution and checks for user permissions before starting the VPN. It also provides a way to check the current active status of the VPN.

```kotlin
val vpnIntent: Intent? = VpnServiceCommand.prepareVpn(context)

if (vpnIntent != null) {
    // Launch activity for user permission
    startActivityForResult(vpnIntent, VPN_REQUEST_CODE)
} else {
    // Permission already granted, start VPN immediately
    VpnServiceCommand.startVpn(context)
}

// Stop the VPN connection
VpnServiceCommand.stopVpn(context)

// Check if VPN is currently active
val isActive = VpnStatusObservable.isVPNActive()
```