Connection & Authentication

Available on Android

Snippbot for Android is on Google Play (US-only rollout for now). iOS is planned but not available yet.

The mobile app connects directly to your self-hosted Snippbot daemon over HTTP(S). There is no Snippbot account to create, and nothing is routed through Snippbot servers. This page covers pairing, connection, and authentication.

First-time setup

When you launch the app for the first time, you land on the pairing screen.

1. Get a pairing code

   In your daemon’s web UI, open Devices → Pair Device to get a 6-digit pairing code.

2. Enter your daemon address and the code

   Type the address of your running Snippbot daemon and the 6-digit code, then tap Connect. Examples:

   • Local network: 192.168.1.50, port 18781
   • Remote Access tunnel or reverse proxy: https://snippbot.yourdomain.com

   On the same network, the app scans for a daemon and pre-fills the address if it finds one.

3. Done — the device is paired

   The daemon issues this phone its own device token. There is no username or password.

4. Optional: Turn on push notifications

   Push is opt-in. Open Settings → Notifications and tap Request Permission to get alerts for session-join approvals and agent replies. See Push Notifications.

5. Optional: Turn on biometric lock

   In Settings → Security, enable the Face ID / fingerprint toggle to lock the app behind your device’s biometrics.

No daemon yet? Tap Explore the demo on the pairing screen to look around with sample data — nothing leaves the device in demo mode.

Pairing by QR is faster

Settings → Remote Access → Show pairing QR in the web UI produces a code that carries the address and a one-time token, so there is nothing to type. Scan it from the app’s login screen. The 6-digit code below it still works if the camera won’t cooperate.

Note

The daemon must be reachable from your phone. On the same Wi-Fi network the app can usually find it for you. To reach it from elsewhere, turn on Remote Access (Settings → Remote Access; cloudflared or ngrok) — or, if you already run one, put it behind a reverse proxy with HTTPS.

Local network vs. remote

The app stores two addresses for your daemon and picks between them automatically:

Endpoint	When it’s used
Local (e.g. 192.168.1.50:18781)	Whenever your phone can reach your daemon’s network. Faster, and traffic never leaves your home
Remote (your tunnel address)	When the local address doesn’t answer — cellular, a coffee shop, anywhere else

Both are stored when you pair by QR. There is nothing to switch when you leave the house; the app probes the local address first, and falls back after about a second and a half.

If you paired before this existed, your single stored address is reclassified automatically on upgrade — you do not need to pair again. To gain the second endpoint, turn on Remote Access and re-pair by QR.

Connection settings

After setup, manage your connection in Settings > Connection.

Setting	Description
Connection details	Host, port, TLS status, and base URL of your daemon
Health check	Check that the daemon is reachable and responding
Endpoints	Your local and remote addresses, with Re-learn from daemon to refresh them
Manual override	Set host, port, and TLS by hand
Cloudflare Access	Optional service token (client ID and secret) if your tunnel sits behind Cloudflare Access
Re-pair Device	Go back to the pairing screen

How authentication works

The mobile app uses bearer token authentication with a per-device token:

1. When you pair, the daemon exchanges the 6-digit code (or QR token) for a device token, a refresh token, and a device ID
2. The tokens are stored in expo-secure-store (hardware-backed keystore)
3. Every API request includes the token in the Authorization: Bearer <token> header
4. If the daemon rejects an expired token, the app refreshes it automatically with the refresh token

Push token registration

Pairing does not register a push token. Only when you opt in to notifications (Settings → Notifications) does the app send its push token to the daemon:

What gets registered

POST /devices/{device_id}/push-token
{
  "push_token": "ExponentPushToken[...]",
  "push_provider": "fcm",
  "app_version": "1.0.1",
  "os_version": "android 35",
  "device_model": "Pixel 8"
}

This lets the daemon route push notifications to your specific device.

Device fingerprint

The app generates a hardware fingerprint using a SHA-256 hash of stable device attributes:

• Device model and manufacturer
• OS name and version
• Screen dimensions

This fingerprint is sent with session join requests and verified against the daemon’s trust store. You can require fingerprint matching in session security settings.

Secure storage

All sensitive data is stored using expo-secure-store, which maps to:

Platform	Backend
Android	Android Keystore + EncryptedSharedPreferences
iOS (planned)	Keychain Services (hardware-encrypted)

Stored items:

• Device token and refresh token
• Device ID
• Connection details
• Device fingerprint

Changing your daemon

To connect to a different Snippbot instance:

1. Open the Settings tab
2. Tap Disconnect at the bottom and confirm
3. On the pairing screen, enter the new daemon address
4. Enter a pairing code from the new daemon’s Devices → Pair Device

Caution

Disconnecting clears the device token and connection details from your phone. It does not remove the device from the old daemon — delete it there from the web UI’s Devices page if you no longer want it paired.

Troubleshooting

”Connection failed” on setup

1. Verify the daemon is running: snippbot status on your server
2. Check the port (default: 18781)
3. Ensure your phone and server are on the same network, or turn on Remote Access
4. Pairing codes are single-use — generate a new one if the old one may have been used

Token expired

The app refreshes tokens automatically. If you still see an auth error:

1. Go to Settings > Connection
2. Tap Re-pair Device
3. Enter a fresh pairing code from the web UI

Device not showing in daemon

1. On the daemon web UI, go to Devices and check whether the phone appears
2. If it’s missing, re-pair from Settings > Connection > Re-pair Device