--- title: "Mobile companion security" description: "How Cerevisor Companion protects LAN traffic, pairs and revokes devices, isolates outputs, and limits mobile authority." slug: reference/mobile-companion-security section: reference canonical_url: https://cerevisor.com/docs/reference/mobile-companion-security last_verified: 2026-07-30 last_verified_version: "1.9.0" updated_at: 2026-08-14T11:11:55.053396+00:00 --- Cerevisor Companion is a narrow local companion, not a remote-desktop product. The desktop remains the authority for run state, permissions, licensing, files, and audit. ## Network and privacy boundary - The phone connects directly to the desktop over a reachable private network: the same Wi-Fi or LAN, or a VPN the user controls (for example Tailscale or WireGuard). Cerevisor does not operate an internet relay for companion traffic; remote access happens only inside the user's own VPN. - The desktop listener is off by default and exists only while Cerevisor is open and the feature is enabled. - The desktop advertises one address for pairing — automatically a physical LAN adapter, or a user-pinned adapter such as a VPN address. Do not expose the companion port to the public internet with router port forwarding; a personal VPN is the supported remote path. - Manually changing the desktop address on the phone cannot redirect trust: the reconnect handshake still verifies the pinned desktop identity key, so a wrong or hostile address fails instead of impersonating the desktop. - Established messages are authenticated and encrypted by the companion protocol. Android permits the local `ws://` carrier because LAN hosts do not have stable public certificates; the application payload is still encrypted end to end between the paired phone and desktop. - No analytics or telemetry pipeline was added for the companion. ## Pairing and reconnect The desktop QR contains a short-lived, single-use pairing secret and the desktop's public identity. The phone creates its own identity key, verifies the signed desktop transcript, and stores its private key in OS-protected secure storage. The desktop stores only the phone's public key and safe metadata. Reconnect uses a fresh desktop nonce, a fresh key exchange, and signatures from both pinned identities. Sequence windows, command IDs, one-use approval nonces, expiry checks, and first-answer-wins rules reject replay and duplicate actions. ## Mobile authority The phone receives opaque run, prompt, and output identifiers, not filesystem paths. Every accepted mobile command passes through the same desktop resolver, license gate, target check, and run audit path as the corresponding desktop action. Mobile access is limited to the named controls that the desktop makes available. Typed input from the phone reaches only specific, named channels — chat-builder messages, messages to agents, and Operator answers — and each is handled by the same desktop code path as local typing. There are no persistent always-allow rules, no internet relay, no arbitrary desktop file access, and no generic remote desktop control. ## Phone tool controls Phone tools are off until you turn them on in the Companion app. Each switch grants a separate kind of access: - **Photo library** lets workflows inspect photo and video names, dates, dimensions, sizes, and small previews. They can list recent or large items and look for exact duplicates. It does not allow changes. - **Organize into albums** lets workflows add selected photos or videos to an album. The originals remain in place. - **Delete photos** lets workflows request removal of selected photos or videos. Turning on the switch is not permission to delete silently: Android always shows a confirmation on the phone for the actual items, and declining leaves them untouched. - **Send files to desktop** lets you choose a photo or document and send it to the private desktop inbox, with an option to attach it to a workflow's next run. A workflow cannot pull arbitrary files from the phone. You can turn off any switch at any time. The desktop then stops offering that kind of phone action to new workflow steps. These features remain inside the same direct, encrypted phone-to-desktop connection described above; files and photo details do not pass through a Cerevisor server. Incoming files are limited to 15 MB, checked for damage or alteration after transfer, and saved under `~/.cerevisor/companion/inbox/` with private desktop permissions. File names are cleaned before saving. If you choose a workflow, Cerevisor attaches that verified inbox copy as an input for the next run; otherwise it stays only in the inbox. ## Generated output isolation Text, Markdown, and images use native view-only renderers with bounded sizes. Interactive HTML is packaged as one bounded immutable document and opened in a locked local WebView. The locked viewer has no Cerevisor bridge, network access, file access, cookies, persistent storage, external navigation, popups, downloads, clipboard, uploads, sensors, or keyboard authority. The document may use its own local JavaScript for tap, scroll, pinch, animation, and controls inside that document. ## Consequential approvals An allow decision that can widen a run's immediate authority requires device authentication, and so do destructive workspace actions started from the phone, such as deleting an agent. The desktop issues a short-lived, single-use challenge bound to the device, prompt, normalized answer, authentication method, and timestamp. This does not create an always-allow rule. ## Audit and revocation Pairing, reconnect, revocation, prompt decisions, stop attempts, and security terminations produce bounded audit rows. Audit excludes pairing secrets, private keys, raw answer content, output contents, frame bytes, and desktop paths. Revoking a phone on the desktop marks its public identity revoked and closes its live connection. Local **Unpair** only deletes the identity from that phone; desktop revocation is the authoritative response to a lost or untrusted device. ## Out of scope The protocol protects against LAN observation, active pairing substitution, reconnect impersonation, replay, revoked devices, accidental authority widening, arbitrary file requests, and hostile generated HTML within the documented model. A fully compromised phone OS or desktop OS is outside that model.