Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.feral.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Pairing & Access

FERAL pairing depends on access mode. If mode and network are wrong, QR scans still fail.

​
Modes

ModeSetup labelPair URL shapeTypical use
localSame WiFihttp://<lan-ip>:9090/pair?t=...Phone and brain on same network
remoteAnywherehttps://<tailnet-host>/pair?t=...Phone outside your LAN
localhostThis Mac onlyno pair URL emittedSkip pairing for now

​
LAN flow (Same WiFi)

  1. In setup, select Same WiFi.
  2. Go to Devices -> Pair new device -> Web phone.
  3. Click Generate one-time link.
  4. Scan QR on phone.
  5. If PIN is required, type the PIN shown on the Mac.
  6. Tap Pair this device on phone.
If the QR URL is unreachable from phone: 
FERAL_HOST=0.0.0.0 feral start
Then regenerate the link.

​
Anywhere flow (Remote / Tailscale Funnel)

Current behavior: setup attempts tunnel activation automatically when you pick Anywhere. If that step fails, use the CLI fallback below (or use Settings -> Access to retry).
  1. In setup, select Anywhere.
  2. If setup fails to bring tunnel up, run:
feral access remote-up
  1. If prompted, complete Tailscale login (tailscale up) and Funnel enable steps.
  2. Regenerate pairing link from Devices and scan from phone.
Status checks: 
feral access status
Disable remote mode: 
feral access remote-down

​
Pair modal tabs

  • Web phone: default browser-based phone pairing flow.
  • Daemon token: token for SDK/daemon node registration.
  • Native app QR: compatibility QR path for native app flows.
  • Bluetooth: browser BLE scan path.

​
Common errors and fixes

Error symptomLikely causeAction
Mode B (localhost) does not expose pairingMode is localhostRerun feral setup and choose Same WiFi or Anywhere
LAN IP not detectedHost has no active LAN addressConnect to network and retry
Mode C (remote) ... no public URLRemote mode selected but tunnel not enabledferal access remote-up
QR opens /pair but phone cannot connectBrain bound to loopback or WiFi isolationrestart with FERAL_HOST=0.0.0.0; test another network
Wrong PIN / expired tokenOld token or PIN retries exhaustedRegenerate one-time link

​
Practical note

If you’re intentionally not pairing yet, keep This Mac only and skip all phone steps.