Remote Sessions

Remote sessions let you continue a conversation started on one device (e.g., your desktop) on another (e.g., your phone). The system uses a 6-layer security gate to ensure only authorized devices can join active sessions.

How it works

1. A session is created on the origin device (desktop web UI or CLI)
2. A transfer token is generated (xfer_...)
3. The token is shared via QR code, deep link, or manual entry
4. The joining device (mobile) redeems the token and passes security checks
5. Both devices can view the conversation in real-time

Joining a session

There are three ways to join a session from the mobile app:

QR code scan

1. On the origin device, generate a transfer QR code from the session menu
2. On mobile, go to Settings > Chat Sessions > Scan QR Code
3. Point your camera at the QR code
4. The app automatically extracts the transfer token and begins the join flow

Deep link

Tap a snippbot://session/xfer_... link on your phone (e.g., from a message or email). The app opens directly to the join flow.

Manual entry

1. Go to Settings > Chat Sessions > Scan QR Code
2. Tap Enter code manually at the bottom of the scanner
3. Type the transfer token (starts with xfer_)
4. Tap Submit

Security gate

When joining a session, the app passes through up to 6 security layers. Each layer is configurable in session security settings.

Layer	Check	Configurable
1. Rate limiting	Max join attempts per time window	Server-side
2. Device trust	Device must be in the daemon’s trusted device list	require_trusted_device
3. Device fingerprint	Hardware fingerprint must match a known device	require_fingerprint_match
4. TOTP verification	6-digit authenticator code required	require_totp_on_join
5. Owner approval	Session owner must approve via push notification	require_owner_approval
6. Token validation	Transfer token must be valid and unexpired	Always enabled

TOTP verification

When TOTP is required, you’ll see a 6-digit code entry screen:

1. Open your authenticator app (Google Authenticator, Authy, etc.)
2. Find the Snippbot entry
3. Enter the 6-digit code in the app
4. The code is verified against the daemon

Note

TOTP must be configured on the daemon first. See Settings > Security for setup instructions.

Owner approval

When owner approval is required:

1. The session owner receives a push notification with the requesting device name and platform
2. The owner can Approve or Deny directly from the notification
3. On mobile, you’ll see a waiting screen with a countdown timer (default: 60 seconds)
4. If approved, you’re redirected to the conversation
5. If denied or timed out, the join attempt fails

Idle resume

When you return to a conversation after being idle, the app may require re-verification:

• If require_totp_on_idle_resume is enabled, you’ll be prompted for a TOTP code after the idle threshold
• The idle threshold is configurable (default: 30 minutes)
• This prevents unauthorized use of an unattended device

Observer mode

When you join a session as a secondary device, you enter observer mode:

• You see all messages in real-time via a fan-out SSE stream
• Tool calls, thinking, and agent responses stream live
• A session indicator pill shows at the top of the chat with participant count
• Tap the pill to see all active participants (device name, platform, join time)

Tip

Observer mode is read-only by default. The session owner controls who can send messages.

Session indicator

Active sessions show a colored pill at the top of the chat:

Color	Meaning
Green	Session active, you’re connected
Yellow	Session active, reconnecting
Red	Session expired or disconnected

Tap the indicator to view:

• Session ID and status
• All participants (device name, platform, last seen)
• Session expiry time
• Option to leave the session

Approval banner

When you’re the session owner and another device requests to join, an approval banner slides in at the top of the chat:

• Shows the requesting device name and platform
• Approve and Deny buttons
• Auto-dismisses after the approval timeout
• Also delivered as a push notification for background handling

Security settings

Configure session security in Settings > Chat Sessions > Security.

Transfer mode

Mode	Description
Explicit Only (recommended)	Session owner must manually generate a transfer code
QR Code + Deep Link	Transfer via QR scan or snippbot:// deep link
Automatic	Any paired device can join any conversation

Security toggles

Setting	Default	Description
Require trusted device	On	Only trusted devices can join
Require TOTP on join	Off	Authenticator code required to join
Require owner approval	On	Owner must approve each join request
Require TOTP on idle resume	Off	Re-verify identity after idle timeout
Require fingerprint match	Off	Verify device hardware fingerprint

Timeout and lockout

Setting	Range	Default	Description
Session expiry	5–1440 min	30 min	Sessions auto-expire after this duration
Max TOTP attempts	1–10	5	Device locked after this many failed codes
Lockout duration	1–120 min	15 min	How long a device stays locked

Use the + / - stepper controls to adjust these values.

Troubleshooting

QR code not scanning

1. Ensure camera permission is granted in device settings
2. Hold the camera steady, 6–12 inches from the QR code
3. Make sure the QR code is well-lit and not distorted
4. Try the manual entry option as a fallback

”Invalid transfer token”

1. Transfer tokens expire after a short time — generate a new one
2. Ensure the token starts with xfer_
3. Check that the session is still active on the origin device

TOTP code rejected

1. Verify your authenticator app’s time is synced (Settings > Time correction in most apps)
2. Use the most recent code — codes rotate every 30 seconds
3. After too many failures, your device may be locked out for the configured lockout duration

Approval timed out

1. Ensure the session owner has push notifications enabled
2. The default timeout is 60 seconds — the owner must respond quickly
3. Try again after the timeout expires