Connection & Authentication

The mobile app connects to your self-hosted Snippbot daemon over HTTP(S). This page covers initial setup, device registration, and authentication.

First-time setup

When you launch the app for the first time, you’ll see the Awakening splash screen, followed by the setup flow.

Enter your daemon URL

Type the address of your running Snippbot daemon. Examples:
- Local network: http://192.168.1.50:18781
- Reverse proxy: https://snippbot.yourdomain.com
Authenticate

Enter your Snippbot credentials (the same ones used for the web UI or CLI).
Register this device

The app automatically registers your phone as a trusted device. You’ll see your device name and a unique device ID.
Enable push notifications

Grant notification permissions when prompted. This enables real-time alerts for approvals, task completions, and insights.
Optional: Enable biometrics

On supported devices, enable Face ID or fingerprint unlock for quick, secure access.

Connection settings

After setup, manage your connection in Settings > Connection.

Setting	Description
Daemon URL	The base URL of your Snippbot daemon
Auth token	Stored securely in the device keychain (Keychain on iOS, Keystore on Android)
Device ID	Unique identifier for this device, generated on first registration
Device name	Display name shown in session participants and device lists

How authentication works

The mobile app uses bearer token authentication:

On login, the app receives a JWT from the daemon’s /auth/login endpoint
The token is stored in expo-secure-store (hardware-backed keychain)
Every API request includes the token in the Authorization: Bearer <token> header
Tokens are refreshed automatically before expiry

Device registration

When you authenticate, the app registers your device with the daemon:

POST /devices/push/register
{
  "device_id": "d_abc123...",
  "push_token": "ExponentPushToken[...]",
  "push_provider": "expo",
  "platform": "ios",
  "device_name": "iPhone 15 Pro",
  "app_version": "0.1.0",
  "os_version": "ios 18.2",
  "device_model": "iPhone 15 Pro"
}

This enables:

Push notifications routed to your specific device
Device trust verification in remote sessions
Device fingerprinting for security gate checks

Device fingerprint

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

Device model and manufacturer
OS version
Unique device identifier

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
iOS	Keychain Services (hardware-encrypted)
Android	Android Keystore + EncryptedSharedPreferences

Stored items:

Auth token
Device ID
Push token
Session credentials

Changing your daemon

To connect to a different Snippbot instance:

Go to Settings > Connection
Tap Disconnect
Enter the new daemon URL
Re-authenticate with credentials for the new instance

Troubleshooting

”Connection failed” on setup

Verify the daemon is running: snippbot status on your server
Check the URL includes the port (default: 18781)
Ensure your phone and server are on the same network (or use a reverse proxy)
Try http:// if HTTPS isn’t configured

Token expired

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

Go to Settings > Connection
Tap Re-authenticate
Enter your credentials again

Device not showing in daemon

Check Settings > Connection for the device ID
On the daemon web UI, go to Devices and verify the device appears
If missing, tap Re-register device in the app settings