Tailscale Android Client

https://github.com/tailscale/tailscale-android
Admin
Tailscale is a mesh VPN built on WireGuard that makes it easy to connect devices securely and...
Tokens:166,882
Snippets:1,080
Trust Score:10
License:BSD-3-Clause
Update:5 days ago
Show doc for...
Tokens:
Raw
### Usage Example: Starting the Engine and Patching Prefs

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Example code showing how to start the engine logged-in with an auth key and how to patch prefs via the masked structure.

```APIDOC
## Usage Example

### Description
Demonstrates starting the engine with an auth key and patching prefs using Ipn.MaskedPrefs.

### Code
```kotlin
// Starting the engine logged-in with an auth key:
val options = Ipn.Options(AuthKey = authKey, FrontendLogID = logID)
Client(scope).start(options) { result ->
  result.fold(
      onSuccess = { TSLog.d(TAG, "start accepted") },
      onFailure = { e -> TSLog.e(TAG, "start failed: $e") },
  )
}

// Patching prefs via the masked structure:
val masked = Ipn.MaskedPrefs().apply {
  WantRunning = true
  ExitNodeID = "ABCD-1234"
}
Client(scope).editPrefs(masked) { result -> … }
```
```

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

### UninitializedApp.restartVPN startService example

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/App.md

Shows how to start IPNService with ACTION_RESTART_VPN, catching IllegalStateException and other exceptions. Logs errors using TSLog.

```kotlin
val intent = Intent(this, IPNService::class.java).apply { action = IPNService.ACTION_RESTART_VPN }
try {
  startService(intent)
} catch (illegalStateException: IllegalStateException) {
  TSLog.e(TAG, "restartVPN hit IllegalStateException in startService(): $illegalStateException")
} catch (e: Exception) {
  TSLog.e(TAG, "restartVPN hit exception in startService(): $e")
}
```

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

### Build and install the Android app with make

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

Use these commands to build the APK and install it on a connected device or emulator. Requires the Android SDK and appropriate environment setup.

```sh
make apk
make install
```

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

### Start function signature (Go)

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale.md

Defines the Start function that initializes the libtailscale backend. It takes dataDir, directFileRoot, hwAttestationPref, and appCtx, and returns the singleton Application. Start returns immediately; backend initialization continues in a background goroutine.

```go
func Start(dataDir, directFileRoot string, hwAttestationPref bool, appCtx AppContext) Application
```

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

### Starting the VPN with error handling

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/IPNService.md

Example from UninitializedApp.startVPN that creates a PendingIntent for the IPNService and sends it, catching SecurityException and other exceptions.

```kotlin
val intent = Intent(this, IPNService::class.java).apply { action = IPNService.ACTION_START_VPN }
val pendingIntent = PendingIntent.getForegroundService(this, 0, intent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
try { pendingIntent.send() }
catch (e: SecurityException) { TSLog.e(TAG, "startVPN hit SecurityException: $e") }
catch (e: Exception) { TSLog.e(TAG, "startVPN hit exception: $e") }
```

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

### POST start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Starts the backend with full preferences or an authentication key for unattended login.

```APIDOC
## POST start

### Description
Starts the backend with full preferences or an authentication key for unattended login.

### Method
POST

### Endpoint
start

### Parameters
#### Request Body
- **UpdatePrefs** (Prefs) - Optional - Full preferences (not masked).
- **AuthKey** (string) - Optional - Authentication key for unattended login.

### Request Example
(No explicit example provided)

### Response
#### Success Response (200)
(No explicit response schema provided)

#### Response Example
(No explicit example provided)
```

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

### POST start - Ipn.Options

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/types.md

Request body for the start operation, containing optional fields to configure the daemon.

```APIDOC
## POST start

### Description
Starts the Tailscale daemon with optional configuration.

### Method
POST

### Endpoint
start

### Request Body
- **FrontendLogID** (String?) - Optional - null
- **UpdatePrefs** (Prefs?) - Optional - null
- **AuthKey** (String?) - Optional - null

```

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

### Starting engine with auth key and patching prefs

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Shows how to start the engine logged-in with an auth key using Ipn.Options and Client.start, then patch prefs via Ipn.MaskedPrefs and Client.editPrefs. The result is handled with fold, logging success or failure.

```kotlin
// Starting the engine logged-in with an auth key:
val options = Ipn.Options(AuthKey = authKey, FrontendLogID = logID)
Client(scope).start(options) { result ->
  result.fold(
      onSuccess = { TSLog.d(TAG, "start accepted") },
      onFailure = { e -> TSLog.e(TAG, "start failed: $e") },
  )
}

// Patching prefs via the masked structure:
val masked = Ipn.MaskedPrefs().apply {
  WantRunning = true
  ExitNodeID = "ABCD-1234"
}
Client(scope).editPrefs(masked) { result -> … }
```

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

### start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Starts the Tailscale daemon with the given options. Sends a POST request to the 'start' endpoint with the options as JSON.

```APIDOC
## POST start

### Description
Starts the Tailscale daemon with the provided options.

### Method
POST

### Endpoint
start

### Parameters
#### Request Body
- **options** (Ipn.Options) - Required - The options to start the daemon with.

### Request Example
{
  "options": {}
}

### Response
#### Success Response (200)
- **result** (Result<Unit>) - The result of the operation.

#### Response Example
{
  "result": {}
}
```

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

### App companion object with get() method

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/App.md

Defines constants and the get() method that initializes the Go backend on first call and returns the singleton App instance.

```kotlin
companion object {
  const val FILE_CHANNEL_ID = "tailscale-files"
  const val KEY_EXPIRY_CHANNEL_ID = "tailscale-key-expiry"
  const val KEY_EXPIRY_NOTIFICATION_ID = 3
  private val PREF_KEY_SAF_URI = "saf_directory_uri"
  private const val TAG = "App"
  private val interfaceJson = Json { encodeDefaults = true }
  private lateinit var appInstance: App

  @JvmStatic
  fun get(): App {
    appInstance.initOnce()
    return appInstance
  }
}
```

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

### Install Android SDK components with Nix

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

On first use of the Nix environment, install the Android SDK components. The SDK directory is ignored by Git and reused across builds.

```sh
make androidsdk
```

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

### Start Docker development shell

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

Use this command to build and start a Docker-based development shell, avoiding installation on the host system. Docker recipes preserve the image and remove the container on completion.

```sh
make docker-shell
```

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

### onStartCommand behavioral matrix

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/IPNService.md

Handles incoming intents and returns the appropriate start mode. It covers stop, restart, foreground-only, start, Always-On VPN, and fallback cases.

```kotlin
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int =
    when (intent?.action) {
      ACTION_STOP_VPN -> { app.setWantRunning(false); close(); START_NOT_STICKY }
      ACTION_RESTART_VPN -> { app.setWantRunning(false) { close(); app.startVPN() }; START_NOT_STICKY }
      ACTION_START_FOREGROUND_ONLY -> { showForegroundNotification(); START_NOT_STICKY }
      ACTION_START_VPN -> { showForegroundNotification(); app.setWantRunning(true); Libtailscale.requestVPN(this); START_STICKY }
      "android.net.VpnService" -> { /* Always-On VPN start */ ...; app.setWantRunning(true); Libtailscale.requestVPN(this); START_STICKY }
      else -> { if (isAbleToStartVPN()) { showForegroundNotification(); App.get(); Libtailscale.requestVPN(this); START_STICKY } else START_NOT_STICKY }
    }
```

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

### Start usage in Kotlin

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale.md

Calls Libtailscale.start with the files directory, direct file root, hardware attestation preference, and the app context. This is the Kotlin equivalent of the Go Start function.

```kotlin
app = Libtailscale.start(filesDir.absolutePath, directFileRoot, hardwareAttestation, this)
```

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

### Basic start (Kotlin)

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale.md

Initializes the libtailscale app and sets up required components. Must be called with the application context and directories.

```kotlin
app = Libtailscale.start(this.filesDir.absolutePath, directFileRoot, hardwareAttestation, this)
ShareFileHelper.init(this, app, directFileRoot, applicationScope)
Request.setApp(app)
Notifier.setApp(app)
Notifier.start(applicationScope)
```

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

### Start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale.md

Initializes the libtailscale library and returns the singleton Application. It sets up environment variables, registers hardware attestation if enabled, and returns immediately while backend initialization continues in a background goroutine.

```APIDOC
## Start

### Description
Initializes the libtailscale library and returns the singleton Application. It sets up environment variables, registers hardware attestation if enabled, and returns immediately while backend initialization continues in a background goroutine.

### Method
Function

### Signature
```go
func Start(dataDir, directFileRoot string, hwAttestationPref bool, appCtx AppContext) Application
```

### Parameters
- **dataDir** (string) - Required - Directory for app state and logs. Sets `XDG_CACHE_HOME` → `<dataDir>/cache`, `XDG_CONFIG_HOME` → `<dataDir>/config`, `HOME` → `dataDir` when unset.
- **directFileRoot** (string) - Required - Storage Access Framework (SAF) tree URI (or plain path) for the Taildrop directory.
- **hwAttestationPref** (bool) - Required - If true and `appCtx.HardwareAttestationKeySupported()`, registers Hardware-Attestation key functions with `key.RegisterHardwareAttestationKeyFns`.
- **appCtx** (AppContext) - Required - Java-side context implementation (see `App` class in this repo).

### Returns
- **Application** - The singleton Application instance.

### Example (Kotlin)
```kotlin
app = Libtailscale.start(filesDir.absolutePath, directFileRoot, hardwareAttestation, this)
```

```

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

### startLoginInteractive

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Starts the interactive login flow. Sends a POST request to the 'login-interactive' endpoint.

```APIDOC
## POST login-interactive

### Description
Starts the interactive login flow.

### Method
POST

### Endpoint
login-interactive

### Parameters
None

### Response
#### Success Response (200)
- **result** (Result<Unit>) - The result of the operation.

#### Response Example
{
  "result": {}
}
```

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

### Libtailscale.start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale.md

Starts the libtailscale app with the given file paths and hardware attestation. Returns an app instance for further operations.

```APIDOC
## Libtailscale.start

### Description
Starts the libtailscale app with the given file paths and hardware attestation. Returns an app instance for further operations.

### Method
start

### Parameters
- **filesDir** (String) - Required - Absolute path to the files directory.
- **directFileRoot** (String) - Required - Root directory for direct files.
- **hardwareAttestation** (Object) - Required - Hardware attestation object.
- **context** (Context) - Required - Android context.

### Returns
- **app** (Libtailscale) - The started app instance.

### Example
```kotlin
app = Libtailscale.start(this.filesDir.absolutePath, directFileRoot, hardwareAttestation, this)
```
```

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

### POST /localapi/v0/start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Starts or reconfigures the engine with the provided options. The request body is an Ipn.Options JSON object. Returns an empty response.

```APIDOC
## POST /localapi/v0/start

### Description
Starts or reconfigures the engine with the provided options.

### Method
POST

### Endpoint
/localapi/v0/start

### Parameters
#### Request Body
- **Ipn.Options** (object) - Required - Engine options as JSON.

### Request Example
```json
{
  "type": "Ipn.Options"
}
```

### Response
#### Success Response (200)
Empty response.
```

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

### GET prefs - Ipn.Prefs

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/types.md

Response model for retrieving current preferences.

```APIDOC
## GET prefs

### Description
Retrieves the current preferences.

### Method
GET

### Endpoint
prefs

### Response
#### Success Response (200)
- **ControlURL** (String) - Default ""
- **RouteAll** (Boolean) - Default false
- **AllowsSingleHosts** (Boolean) - Default false
- **CorpDNS** (Boolean) - Default false
- **WantRunning** (Boolean) - Default false
- **LoggedOut** (Boolean) - Default false
- **ShieldsUp** (Boolean) - Default false
- **AdvertiseRoutes** (List<String>?) - Default null
- **AdvertiseTags** (List<String>?) - Default null
- **ExitNodeID** (StableNodeID?) - Default null
- **ExitNodeAllowLANAccess** (Boolean) - Default false
- **Config** (Persist.Persist?) - Default null
- **ForceDaemon** (Boolean) - Default false
- **HostName** (String) - Default ""
- **AutoUpdate** (AutoUpdatePrefs?) - Default AutoUpdatePrefs(true, true)
- **InternalExitNodePrior** (String?) - Default null

Computed: selectedExitNodeID (from InternalExitNodePrior), activeExitNodeID (from ExitNodeID), both empty→null.

```

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

### prefs

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the current preferences. Sends a GET request to the 'prefs' endpoint.

```APIDOC
## GET prefs

### Description
Retrieves the current preferences.

### Method
GET

### Endpoint
prefs

### Parameters
None

### Response
#### Success Response (200)
- **prefs** (Ipn.Prefs) - The current preferences.

#### Response Example
{
  "prefs": {}
}
```

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

### GET /localapi/v0/prefs

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Reads the current preferences. No request body is required. Returns an Ipn.Prefs object.

```APIDOC
## GET /localapi/v0/prefs

### Description
Reads the current preferences.

### Method
GET

### Endpoint
/localapi/v0/prefs

### Parameters
None

### Response
#### Success Response (200)
- **Ipn.Prefs** - The current preferences.

#### Response Example
```json
{
  "type": "Ipn.Prefs"
}
```
```

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

### client.status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipnstate.md

Usage example for the client.status method, which retrieves the current status of the Tailscale client.

```APIDOC
## client.status

### Description
Retrieves the current status of the Tailscale client. The result contains backend state, version, and peer information.

### Usage Example
```kotlin
client.status { result ->
  result.onSuccess { status ->
    val self = status.Self
    TSLog.d(TAG, "backend=${status.BackendState} version=${status.Version}")
    status.Peer?.forEach { (_, ps) -> TSLog.d(TAG, "peer ${ps.computedName(status)}: ${ps.Online}") }
  }
}
```
```

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

### client.currentProfile

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipnstate.md

Usage example for the client.currentProfile method, which retrieves the current login profile.

```APIDOC
## client.currentProfile

### Description
Retrieves the current login profile. The result contains profile information including name and custom control server hostname.

### Usage Example
```kotlin
client.currentProfile { result ->
  result.onSuccess { profile ->
    TSLog.d(TAG, "profile ${profile.Name} (${profile.customControlServerHostname()})")
  }
}
```
```

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

### POST /localapi/v0/login-interactive

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Starts an interactive login flow. No request body is required. Returns an empty response.

```APIDOC
## POST /localapi/v0/login-interactive

### Description
Starts an interactive login flow.

### Method
POST

### Endpoint
/localapi/v0/login-interactive

### Parameters
None

### Response
#### Success Response (200)
Empty response.
```

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

### client.tailnetLockStatus

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipnstate.md

Usage example for the client.tailnetLockStatus method, which retrieves the tailnet lock status.

```APIDOC
## client.tailnetLockStatus

### Description
Retrieves the tailnet lock status. The result contains whether tailnet lock is enabled and whether the public key is trusted.

### Usage Example
```kotlin
client.tailnetLockStatus { result ->
  result.onSuccess { lock ->
    TSLog.d(TAG, "tka enabled=${lock.Enabled} keyTrusted=${lock.IsPublicKeyTrusted()}")
  }
}
```
```

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

### Example usage from App.getInterfaces

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/ifaceparse.md

Shows how to call ParseInterfacesJSONAsNetmon with the JSON string from GetInterfacesAsJson, handle errors, and log skipped counts.

```go
jsonStr, err := a.appCtx.GetInterfacesAsJson()
if err != nil { return nil, err }
ifaces, st, err := ifaceparse.ParseInterfacesJSONAsNetmon([]byte(strings.TrimSpace(jsonStr)))
if err != nil { return nil, err }
if st.IfacesSkipped > 0 || st.AddrsSkipped > 0 {
	log.Printf("getInterfaces(JSON): parsed %d/%d ifaces, %d/%d addrs", st.IfacesParsed, st.IfacesTotal, st.AddrsParsed, st.AddrsTotal)
}
return ifaces, nil
```

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

### Node usage example from netmap

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-tailcfg.md

Shows how to retrieve a Node from the netmap and access its properties like displayName, primaryIPv4Address, isExitNode, and isAdmin. Also demonstrates deep-link navigation by matching ComputedName or StableID.

```kotlin
// From the netmap (see Notifier):
val node: Tailcfg.Node = netmap.getPeer(peerId) ?: netmap.SelfNode
TSLog.d(TAG, "${node.displayName} ipv4=${node.primaryIPv4Address} exitNode=${node.isExitNode}")
if (node.isAdmin) { /* show admin actions */ }

// Deep-link navigation uses computedName matching:
val found = peers.firstOrNull { identifier.equals(it.ComputedName, ignoreCase = true) }
    ?: peers.firstOrNull { it.StableID == identifier }
```

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

### Build Tailscale debug APK with Nix

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

Build the debug APK after installing SDK components. The output is written to ./tailscale-debug.apk.

```sh
make tailscale-debug
```

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

### Example usage from updateTUN

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/ranges-calc.md

Calls rangescalc.Calculate with router config routes, logs and returns on error, then adds each IPv4 route to the VPN builder. IPv6 loop is commented as 'same'.

```go
prefixesV4, prefixesV6, err := rangescalc.Calculate(rcfg.Routes, rcfg.LocalRoutes)
if err != nil {
	b.logger.Logf("updateTUN: route calculation error: %v", err)
	return err
}
for _, route := range prefixesV4 {
	route = route.Masked()
	if err := builder.AddRoute(route.Addr().String(), int32(route.Bits())); err != nil {
		return err
	}
}
for _, route := range prefixesV6 { /* same */ }
```

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

### Usage example for status, tailnetLockStatus, and currentProfile

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipnstate.md

Shows how to use the IpnLocal client to fetch status, tailnet lock status, and current profile. Logs backend state, version, peer online status, TKA enabled state, key trust, and profile name with custom control server hostname.

```kotlin
client.status { result ->
  result.onSuccess { status ->
    val self = status.Self
    TSLog.d(TAG, "backend=${status.BackendState} version=${status.Version}")
    status.Peer?.forEach { (_, ps) -> TSLog.d(TAG, "peer ${ps.computedName(status)}: ${ps.Online}") }
  }
}

client.tailnetLockStatus { result ->
  result.onSuccess { lock ->
    TSLog.d(TAG, "tka enabled=${lock.Enabled} keyTrusted=${lock.IsPublicKeyTrusted()}")
  }
}

client.currentProfile { result ->
  result.onSuccess { profile ->
    TSLog.d(TAG, "profile ${profile.Name} (${profile.customControlServerHostname()})")
  }
}
```

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

### Catch MDM/keystore exceptions with try-catch

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/errors.md

Use this for MDM/keystore exceptions that are thrown as Java-style exceptions. The example catches MDMSettings.NoSuchKeyException for unconfigured policies and IOException for storage failures.

```kotlin
try {
  App.get().getSyspolicyStringValue("Hostname")
} catch (e: MDMSettings.NoSuchKeyException) {
  // policy not configured
} catch (e: IOException) { /* storage failed */ }
```

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

### GET /localapi/v0/profiles/

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Lists all login profiles. No request body is required. Returns a list of IpnLocal.LoginProfile objects.

```APIDOC
## GET /localapi/v0/profiles/

### Description
Lists all login profiles.

### Method
GET

### Endpoint
/localapi/v0/profiles/

### Parameters
None

### Response
#### Success Response (200)
- **List<IpnLocal.LoginProfile>** - A list of login profiles.

#### Response Example
```json
[
  {
    "type": "IpnLocal.LoginProfile"
  }
]
```
```

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

### TaildropNotifier usage example

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/Notifier.md

Shows how to initialize the notifier with Notifier.setApp and Notifier.start, then observe engine state and health warnings via coroutines, and toggle a device favorite. The state collection logs when the tailnet is up, and the health warnings log each warning code and title.

```kotlin
Notifier.setApp(app)
Notifier.start(applicationScope)

// Observe the engine state:
scope.launch {
  Notifier.state.collect { state ->
    if (state == Ipn.State.Running) TSLog.d(TAG, "tailnet is up")
  }
}
// Observe health warnings:
scope.launch {
  healthNotifier.currentWarnings.collect { warnings ->
    warnings.forEach { TSLog.w(TAG, "${it.WarnableCode}: ${it.Title}") }
  }
}
// Favorites (debounced write, optimistic update):
favoritesManager.toggleDevice(peer.StableID)
```

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

### Run one-shot Nix commands

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

Run commands without entering an interactive Nix shell. These commands install SDK components and build the debug APK.

```sh
nix develop --command make androidsdk
nix develop --command make tailscale-debug
```

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

### Taildrop upload with manifest and error handling (putTaildropFiles)

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Non-trivial example mirroring putTaildropFiles. Builds a manifest FilePart and file parts from content URIs, then calls client.putTaildropFiles. Closes all part bodies and logs an error if any exception occurs while creating the upload body.

```kotlin
val manifestPart = FilePart().apply {
  body = InputStreamAdapter(manifest.byteInputStream(Charset.defaultCharset()))
  filename = "manifest.json"
  contentType = "application/json"
}
val parts = mutableListOf(manifestPart)
try {
  files.forEach { file ->
    val stream = context.contentResolver.openInputStream(file.uri)
        ?: throw Exception("Error opening file stream")
    parts += FilePart().apply {
      filename = file.Name
      contentLength = file.DeclaredSize
      body = InputStreamAdapter(stream)
    }
  }
  client.putTaildropFiles(context, peerId, files) { result ->
    result.onFailure { TSLog.e(TAG, "upload failed: $it") }
  }
} catch (e: Exception) {
  parts.forEach { it.body.close() }
  TSLog.e(TAG, "Error creating file upload body: $e")
}
```

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

### GET status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Retrieves the current backend state, authentication URL, network map, and client version.

```APIDOC
## GET status

### Description
Retrieves the current backend state, authentication URL, network map, and client version.

### Method
GET

### Endpoint
status

### Parameters
(No parameters documented)

### Request Example
(No request body)

### Response
#### Success Response (200)
- **BackendState** (string) - e.g., "Running", "Stopping"
- **AuthURL** (string) - for login flows
- **Peer** (map) - network map peers
- **User** (map) - network map users
- **CurrentTailnet** (object) - with MagicDNS suffix
- **ClientVersion** (string) - client version

#### Response Example
(No explicit example provided)
```

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

### MDMSettings usage example

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/MDMSettings.md

Shows how to read the current forced-exit-node policy from app code (UI layer) using MDMSettings.exitNodeID.flow, and how to programmatically refresh MDMSettings using MDMSettings.update with the RestrictionsManager.

```kotlin
// Read the current forced-exit-node policy from app code (UI layer):
MDMSettings.exitNodeID.flow.collect { state ->
  if (state.isSet) {
    TSLog.d(TAG, "MDM exit node: ${state.value}")
  }
}

// Programmatic refresh (normally triggered by the receiver / App.update):
MDMSettings.update(App.get(), getSystemService(Context.RESTRICTIONS_SERVICE) as RestrictionsManager)
```

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

### InstalledAppsManager and InstalledApp definitions

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/util.md

Defines the InstalledApp data class and InstalledAppsManager class for fetching installed apps.

```kotlin
data class InstalledApp(val name: String, val packageName: String)

class InstalledAppsManager(val packageManager: PackageManager) {
  fun fetchInstalledApps(): List<InstalledApp>
}
```

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

### Example JSON input schema

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/ifaceparse.md

JSON structure expected by the parser, matching App.InterfaceJson and App.AddrJson. Contains interface fields and an addrs array with ip and prefixLen.

```json
[{"name":"wlan0","index":2,"mtu":1500,"up":true,"broadcast":true,"loopback":false,"pointToPoint":false,"multicast":true,
  "addrs":[{"ip":"192.168.1.5","prefixLen":24}]}]
```

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

### ADB commands for Fire Stick TV development

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

Useful commands for connecting to a Fire Stick TV over ADB, installing the APK, launching the main activity, and uninstalling the app. Requires ADB debugging to be enabled on the device.

```sh
adb connect 10.2.200.213:5555
adb install -r tailscale-fdroid.apk
adb shell am start -n com.tailscale.ipn/com.tailscale.ipn.MainActivity
adb shell pm uninstall com.tailscale.ipn
```

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

### UninitializedApp companion object members

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/App.md

Defines constants and functions available before backend init. Includes notification IDs, channel ID, lateinit properties for notificationManager and appViewModel, and a get() function.

```kotlin
companion object {
  const val TAG = "UninitializedApp"
  const val STATUS_NOTIFICATION_ID = 1
  const val STATUS_EXIT_NODE_FAILURE_NOTIFICATION_ID = 2
  const val STATUS_CHANNEL_ID = "tailscale-status"
  lateinit var notificationManager: NotificationManagerCompat
  lateinit var appViewModel: AppViewModel

  @JvmStatic
  fun get(): UninitializedApp
  fun getExitNodeName(prefs: Ipn.Prefs?, netmap: Netmap.NetworkMap?): String?
}
```

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

### Set up Nix development environment

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

For Nix 2.4 or later, these commands enable the required experimental features and enter the development environment. The flake provides host tools and a repo-local Android SDK.

```sh
alias nix='nix --extra-experimental-features "nix-command flakes"'
nix develop
```

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

### GET tka/status - IpnState.NetworkLockStatus

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/types.md

Response model for retrieving network lock status.

```APIDOC
## GET tka/status

### Description
Retrieves the network lock status.

### Method
GET

### Endpoint
tka/status

### Response
#### Success Response (200)
- **Enabled** (Boolean?) - Whether network lock is enabled
- **PublicKey** (String?) - Public key
- **NodeKey** (String?) - Node key
- **NodeKeySigned** (Boolean?) - Whether node key is signed
- **FilteredPeers** (List<TKAFilteredPeer>?) - Filtered peers
- **StateID** (ULong?) - State ID
- **TrustedKeys** (List<TKAKey>?) - Trusted keys

Helper: IsPublicKeyTrusted().

```

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

### Backend use pattern from net.go

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/libtailscale-multitun.md

Shows how the backend brings the tunnel down, creates a new TUN device from a file descriptor, adds it, and brings the tunnel up. The up/down distinction handles VPN reconfiguration vs. Tailscale stop.

```go
if b.devices.Down() {
	b.logger.Logf("updateTUN: tunnel brought down: %v", err)
}
// …
tunDev, _, err := tun.CreateUnmonitoredTUNFromFD(int(tunFD))
if err != nil { closeFileDescriptor(); return err }
b.devices.add(tunDev)
if b.devices.Up() { b.logger.Logf("tunnel brought up") }
```

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

### Initialize SDK, log, use feature flags, and handle Taildrop directory

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/util.md

Initializes the Tailscale Android SDK with TSLog.init, logs a message, initializes feature flags with a map, checks a flag, and handles Taildrop directory validation with a coroutine.

```kotlin
TSLog.init(this)
TSLog.d("App", "started")
FeatureFlags.initialize(mapOf("enable_new_search" to true))
if (FeatureFlags.isEnabled("enable_new_search")) { /* search UI active */ }

// Taildrop directory handling:
if (!ShareFileHelper.hasValidTaildropDir()) {
  scope.launch { ShareFileHelper.observeTaildropPrompt().collect { /* show picker */ } }
}
```

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

### GET status - IpnState.Status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/types.md

Response model for retrieving the current status of the Tailscale daemon.

```APIDOC
## GET status

### Description
Retrieves the current status of the Tailscale daemon.

### Method
GET

### Endpoint
status

### Response
#### Success Response (200)
- **Version** (String) - Version string
- **TUN** (Boolean) - Whether TUN is enabled
- **BackendState** (String) - Backend state
- **AuthURL** (String) - Authentication URL
- **TailscaleIPs** (List<Addr>?) - Tailscale IP addresses
- **Self** (PeerStatus?) - Self peer status
- **ExitNodeStatus** (ExitNodeStatus?) - Exit node status
- **Health** (List<String>?) - Health messages
- **CurrentTailnet** (TailnetStatus?) - Current tailnet status
- **CertDomains** (List<String>?) - Certificate domains
- **Peer** (Map<String, PeerStatus>?) - Map of peers
- **User** (Map<String, Tailcfg.UserProfile>?) - Map of users
- **ClientVersion** (Tailcfg.ClientVersion?) - Client version

```

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

### Options

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Data class representing the body of POST /localapi/v0/start (Client.start). Contains optional frontend log ID, update prefs, and auth key.

```APIDOC
## Options

### Description
Data class representing the body of POST /localapi/v0/start (Client.start). Contains optional frontend log ID, update prefs, and auth key.

### Fields
- **FrontendLogID** (String?) - Optional - Frontend log ID.
- **UpdatePrefs** (Prefs?) - Optional - Preferences to update.
- **AuthKey** (String?) - Optional - Authentication key.

### Example
```kotlin
val options = Options(FrontendLogID = "log123", AuthKey = "authkey")
```
```

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

### getFavorites

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the list of favorite peers. Sends a GET request to the 'pins' endpoint.

```APIDOC
## GET pins

### Description
Retrieves the list of favorite peers.

### Method
GET

### Endpoint
pins

### Parameters
None

### Response
#### Success Response (200)
- **favorites** (Favorites) - The list of favorite peers.

#### Response Example
{
  "favorites": {}
}
```

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

### HardwareKeyStore class and exceptions (util/HardwareKeyStore.kt)

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/util.md

Hardware-attestation key store using StrongBox-backed EC keys (`setIsStrongBoxBacked(true)`, `DIGEST_NONE`). `createKey()` throws `HardwareKeysNotSupported` below API 28; `sign`/`public`/`load` throw `NoSuchKeyException` for unknown IDs. Backs `libtailscale.AppContext.HardwareAttestationKey*`.

```kotlin
class NoSuchKeyException : Exception("no key found matching the provided ID")
class HardwareKeysNotSupported : Exception("hardware-backed keys are not supported on this device")

class HardwareKeyStore() {
  companion object { val keyStoreKeys: HashMap<String, KeyPair> }
  val keyStore: KeyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
  fun newID(): String
  fun createKey(): String
  fun releaseKey(id: String)
  fun sign(id: String, data: ByteArray): ByteArray   // NONEwithECDSA (hashing on Go side)
  fun public(id: String): ByteArray
  fun load(id: String)
}
```

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

### fileTargets

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the list of file targets. Sends a GET request to the 'file-targets' endpoint.

```APIDOC
## GET file-targets

### Description
Retrieves the list of file targets.

### Method
GET

### Endpoint
file-targets

### Parameters
None

### Response
#### Success Response (200)
- **targets** (List<Ipn.FileTarget>) - The list of file targets.

#### Response Example
{
  "targets": []
}
```

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

### Lifecycle and initialization methods

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/App.md

Declares lifecycle and initialization methods: onCreate, onTerminate, getLibtailscaleApp, and startLibtailscale.

```kotlin
override fun onCreate()
override fun onTerminate()
fun getLibtailscaleApp(): libtailscale.Application
fun startLibtailscale(directFileRoot: String, hardwareAttestation: Boolean)
```

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

### currentProfile

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the current login profile. Sends a GET request to the 'profiles/current' endpoint.

```APIDOC
## GET profiles/current

### Description
Retrieves the current login profile.

### Method
GET

### Endpoint
profiles/current

### Parameters
None

### Response
#### Success Response (200)
- **profile** (IpnLocal.LoginProfile) - The current login profile.

#### Response Example
{
  "profile": {}
}
```

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

### profiles

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the list of login profiles. Sends a GET request to the 'profiles/' endpoint.

```APIDOC
## GET profiles/

### Description
Retrieves the list of login profiles.

### Method
GET

### Endpoint
profiles/

### Parameters
None

### Response
#### Success Response (200)
- **profiles** (List<IpnLocal.LoginProfile>) - The list of login profiles.

#### Response Example
{
  "profiles": []
}
```

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

### FileTarget data class

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Serializable data class representing an item of GET /localapi/v0/file-targets.

```kotlin
@Serializable data class FileTarget(var Node: Tailcfg.Node, var PeerAPIURL: String)
```

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

### GET /localapi/v0/pins

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Reads the favorites list. No request body is required. Returns a Favorites object.

```APIDOC
## GET /localapi/v0/pins

### Description
Reads the favorites list.

### Method
GET

### Endpoint
/localapi/v0/pins

### Parameters
None

### Response
#### Success Response (200)
- **Favorites** - The favorites list.

#### Response Example
```json
{
  "type": "Favorites"
}
```
```

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

### status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Retrieves the current status of the Tailscale daemon. Sends a GET request to the 'status' endpoint.

```APIDOC
## GET status

### Description
Retrieves the current status of the Tailscale daemon.

### Method
GET

### Endpoint
status

### Parameters
None

### Response
#### Success Response (200)
- **status** (StatusResponse) - The current status.

#### Response Example
{
  "status": {}
}
```

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

### Options data class for POST /localapi/v0/start

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Serializable data class used as the body of POST /localapi/v0/start (Client.start).

```kotlin
@Serializable
data class Options(
    var FrontendLogID: String? = null,
    var UpdatePrefs: Prefs? = null,
    var AuthKey: String? = null,
)
```

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

### GET /localapi/v0/tka/status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipnstate.md

Retrieves the tailnet lock status. The response is represented by the NetworkLockStatus data class.

```APIDOC
## GET /localapi/v0/tka/status

### Description
Retrieves the tailnet lock status.

### Method
GET

### Endpoint
/localapi/v0/tka/status

### Response
#### Success Response (200)
- **Enabled** (Boolean?) - Whether tailnet lock is enabled.
- **PublicKey** (String?) - Public key.
- **NodeKey** (String?) - Node key.
- **NodeKeySigned** (Boolean?) - Whether the node key is signed.
- **FilteredPeers** (List<TKAFilteredPeer>?) - List of filtered peers.
- **StateID** (ULong?) - State ID.
- **TrustedKeys** (List<TKAKey>?) - List of trusted keys.

#### Response Example
{
  "Enabled": true,
  "PublicKey": "key1",
  "NodeKey": "node1",
  "NodeKeySigned": true,
  "FilteredPeers": [],
  "StateID": 123,
  "TrustedKeys": [{"Key": "key1"}]
}
```

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

### PUT /localapi/v0/profiles/

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Creates a new login profile. No request body is specified. Returns a String.

```APIDOC
## PUT /localapi/v0/profiles/

### Description
Creates a new login profile.

### Method
PUT

### Endpoint
/localapi/v0/profiles/

### Parameters
None

### Response
#### Success Response (200)
- **String** - The new profile ID.

#### Response Example
```json
{
  "type": "String"
}
```
```

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

### MainViewModel method signatures table

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/viewmodels.md

Lists the method signatures for MainViewModel, including updateSearchTerm, hidePeerDropdownMenu, copyIPV4Address, copyIPV6Address, copyMagicDNSAddress, togglePin, startPing, onPingDismissal, skipPromptsForAuthKeyLogin, maybeRequestVpnPermission, showVPNPermissionLauncherIfUnauthorized, toggleVpn, searchPeers, enableSearchAutoFocus, disableSearchAutoFocus, and setVpnPermissionLauncher.

```kotlin
| Method | Signature |
|--------|-----------|
| `updateSearchTerm` | `fun updateSearchTerm(term: String)` |
| `hidePeerDropdownMenu` | `fun hidePeerDropdownMenu()` |
| `copyIPV4Address` / `copyIPV6Address` / `copyMagicDNSAddress` | `fun copyIPV4Address(peer: Tailcfg.Node, clipboardManager: ClipboardManager)` (and V6/MagicDNS variants) |
| `togglePin` | `fun togglePin(peer: Tailcfg.Node)` |
| `startPing` | `fun startPing(peer: Tailcfg.Node)` |
| `onPingDismissal` | `fun onPingDismissal()` |
| `skipPromptsForAuthKeyLogin` | `fun skipPromptsForAuthKeyLogin(): Boolean` |
| `maybeRequestVpnPermission` | `fun maybeRequestVpnPermission()` |
| `showVPNPermissionLauncherIfUnauthorized` | `fun showVPNPermissionLauncherIfUnauthorized()` |
| `toggleVpn` | `fun toggleVpn(desiredState: Boolean)` |
| `searchPeers` | `fun searchPeers(searchTerm: String)` |
| `enableSearchAutoFocus` / `disableSearchAutoFocus` | `fun enableSearchAutoFocus()` / `fun disableSearchAutoFocus()` |
| `setVpnPermissionLauncher` | `fun setVpnPermissionLauncher(launcher: ActivityResultLauncher<Intent>)` |
```

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

### GET /localapi/v0/profiles/current

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Retrieves the current login profile. No request body is required. Returns an IpnLocal.LoginProfile object.

```APIDOC
## GET /localapi/v0/profiles/current

### Description
Retrieves the current login profile.

### Method
GET

### Endpoint
/localapi/v0/profiles/current

### Parameters
None

### Response
#### Success Response (200)
- **IpnLocal.LoginProfile** - The current login profile.

#### Response Example
```json
{
  "type": "IpnLocal.LoginProfile"
}
```
```

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

### GET /localapi/v0/status

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Retrieves the current engine status. No request body is required. Returns an IpnState.Status object.

```APIDOC
## GET /localapi/v0/status

### Description
Retrieves the current engine status.

### Method
GET

### Endpoint
/localapi/v0/status

### Parameters
None

### Response
#### Success Response (200)
- **IpnState.Status** - The engine status.

#### Response Example
```json
{
  "type": "IpnState.Status"
}
```
```

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

### FileTarget

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/models-ipn.md

Data class representing an item of GET /localapi/v0/file-targets. Contains the target node and its PeerAPI URL.

```APIDOC
## FileTarget

### Description
Data class representing an item of GET /localapi/v0/file-targets. Contains the target node and its PeerAPI URL.

### Fields
- **Node** (Tailcfg.Node) - Required - The target node.
- **PeerAPIURL** (String) - Required - The PeerAPI URL for the target node.

### Example
```kotlin
val target = FileTarget(node, "https://peerapi.example.com")
```
```

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

### Query status and set WantRunning preference with Client

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/localapi-client.md

Creates a Client with the application scope, retrieves the backend status, and sets the WantRunning preference to true. The status result is handled with fold, logging the backend state or an error. The editPrefs call logs a failure if setting the preference fails.

```kotlin
val client = Client(applicationScope)
client.status { result ->
  result.fold(
      onSuccess = { status ->
        // status: IpnState.Status — peers, exit nodes, version…
        TSLog.d(TAG, "backend state: ${status.BackendState}")
      },
      onFailure = { e -> TSLog.e(TAG, "status failed: ${e.message}") },
  )
}
client.editPrefs(Ipn.MaskedPrefs().apply { WantRunning = true }) { result ->
  result.onFailure { TSLog.e(TAG, "failed to set WantRunning: $it") }
}
```

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

### packagesForVpnBuilder function

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/IPNService.md

Internal Kotlin function that builds the list of packages for the VPN builder based on the allow/deny list policy. If allowPackages is true, it includes the Tailscale package; otherwise it includes built-in disallowed packages. The result is deduplicated.

```kotlin
internal fun packagesForVpnBuilder(
    packagesList: List<String>,
    allowPackages: Boolean,
    tailscalePackageName: String,
    builtInDisallowedPackages: List<String>,
): List<String> =
    if (allowPackages) {
      if (packagesList.isEmpty()) emptyList()
      else (packagesList + tailscalePackageName).distinct()
    } else {
      (packagesList + builtInDisallowedPackages).distinct()
    }
```

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

### GET /localapi/v0/file-targets

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/endpoints.md

Lists Taildrop file targets. No request body is required. Returns a list of Ipn.FileTarget objects.

```APIDOC
## GET /localapi/v0/file-targets

### Description
Lists Taildrop file targets.

### Method
GET

### Endpoint
/localapi/v0/file-targets

### Parameters
None

### Response
#### Success Response (200)
- **List<Ipn.FileTarget>** - A list of file targets.

#### Response Example
```json
[
  {
    "type": "Ipn.FileTarget"
  }
]
```
```

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

### Run Kotlin-only checks with Nix

Source: https://github.com/tailscale/tailscale-android/blob/main/README.md

For faster Kotlin-only iteration, this command runs ktfmtCheck and compileDebugKotlin, avoiding the gomobile bind step.

```sh
nix develop --command bash -lc 'cd android && ./gradlew ktfmtCheck compileDebugKotlin'
```

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

### DnsConfig class definition

Source: https://github.com/tailscale/tailscale-android/blob/main/_autodocs/api-reference/util.md

Defines the DnsConfig class in Java with methods to get DNS config as string and update DNS from network.

```java
public class DnsConfig {
    String getDnsConfigAsString();   // line[0] nameservers, line[1] search domains; "" if unknown
    boolean updateDNSFromNetwork(String dnsConfigs);
}
```
Tokens:
Raw