Pair and use the mobile companion

Cerevisor Companion connects directly to the Cerevisor desktop app on the same Wi-Fi or LAN — or, away from home, across your own VPN (see Use your phone away from home). There is no Cerevisor account or internet relay in the connection path. Cerevisor must remain open on the computer.

Cerevisor Companion currently supports Android. An iOS version is not available yet.

Pair your phone

1. Open Settings > Mobile companion on the desktop.
2. Turn on Allow your phone on this LAN. The listener is off by default, and your firewall may ask once for permission.
3. Select Show QR. The code is single-use and expires after two minutes.
4. Open Cerevisor Companion and select Scan desktop QR. If camera access is declined, paste the pairing code instead.
5. Keep both apps open until the Runs screen says Live now.

The phone pins that desktop's identity. A QR from another desktop is rejected until you explicitly unpair.

What you can do

Cerevisor Companion is free. On every plan you can:

• See active runs and up to 20 recent runs from the open desktop workspace.
• Follow durable lifecycle, agent, tool, output, cost, and failure activity.
• Read Markdown and text, inspect images, and open bounded interactive HTML in the locked viewer.
• Approve once or deny a permission prompt.
• Approve or reject supported approval and plan prompts.
• Answer option-based questions.
• Stop the exact active run you are viewing.
• See the open workspace as a live canvas and launch a workflow: Run once, Loop, Fix & Enhance, or Endless.
• Create, rename, or delete workflows, and manage their connections (handoffs, conditions, gates, and loops).
• Build a workflow by chat from the phone, answer the builder's questions, and follow a build someone typed on the desktop — the phone shows the same conversation.
• Message a running or finished agent to steer it.
• Set each agent's provider and model, the app-default provider and model, and the chat builder's model and thinking effort.
• Switch between saved workspaces (worlds) or create a new one.
• Pause, resume, or stop Progressive Mode on a workflow, and message it while it builds.
• Watch the Operator, answer its questions, and stop it (see The Operator on your phone).

Consequential approvals and destructive actions such as deleting an agent ask for immediate device authentication. Free-text questions asked by a running workflow still stay on the desktop — the phone answers those by options only — but you can type freely to the chat builder, to agents, and to the Operator.

Some of these need a current desktop version. If your desktop is older, the phone simply hides the newer controls instead of showing broken ones.

The Operator on your phone

If you have turned on the Operator on the desktop (see The Operator), the Companion gets an Operator screen:

• See what the Operator is doing now and what it has done recently, plus today's spend.
• Answer an open Operator question in your own words.
• Stop the Operator from the phone (hold to confirm). Stopping turns off future automatic runs; a check that is already underway finishes first. Reviewing and approving what the Operator has prepared stays on the desktop.

Let workflows use phone tools

All phone tools start turned off. To make selected actions available:

1. Pair the phone and wait until it says Live now.
2. Open Settings in Cerevisor Companion.
3. Under Phone tools, turn on only what you want to allow: Photo library, Organize into albums, Delete photos, or Send files to desktop.
4. Keep the Companion app open while a workflow is scanning or changing the photo library. If the phone does not answer within two minutes, that workflow step reports an error and the run continues instead of waiting forever.

The switches are independent. Reading the photo library does not allow organizing or deleting. A delete request always opens Android's own confirmation on the phone; select Cancel there to decline it. You can turn any switch off again at any time. Phone details travel directly between your paired devices over your Wi-Fi, LAN, or personal VPN.

Send a file into a workflow

1. In Companion Settings > Phone tools, turn on Send files to desktop.
2. Return to the Canvas. Select the send-file button near the connection indicator.
3. Select Choose photo or Choose file, then pick an item up to 15 MB.
4. Under Where should it go?, select a workflow to attach the file for its next run. Select Just save on desktop if you only want a private inbox copy.
5. Select Send and attach or Send to desktop and keep both apps open until the progress reaches 100% and Sent appears.

The desktop verifies the complete file before saving it privately. When you selected a workflow, the file appears with that workflow's launcher inputs and is available to its next run. Files sent without a workflow are kept in ~/.cerevisor/companion/inbox/ on the desktop.

Use your phone away from home (your own VPN)

The companion works away from home when both devices are on a VPN you control, such as Tailscale (easiest) or WireGuard. Your traffic stays end-to-end encrypted and travels only inside your own VPN — it never touches a Cerevisor server, and there is still no account.

1. Install the VPN on both the desktop and the phone and sign both into the same private network (with Tailscale, the same tailnet).
2. On the desktop, open Settings > Mobile companion. Under Phones connect to, pick the VPN address (it is labeled, for example 100.x.y.z — Tailscale (VPN)).
3. If the phone is not paired yet, select Show QR and scan it as usual. If it is already paired, open mobile Settings > Type address manually and enter the desktop's VPN address or name (for example 100.64.0.12 or my-pc.tailnet.ts.net).
4. That's it. As long as both devices are on your VPN and Cerevisor is open, the phone connects from anywhere.

Good to know:

• The address you pick is the one the pairing QR advertises. If you pin the VPN address, a phone that is only on plain home Wi-Fi (without the VPN app) will not reach it — put the phone on the VPN too, or switch back to Auto.
• If the desktop shows "your chosen address is not active right now", start the VPN on the desktop; Cerevisor falls back to the automatic Wi-Fi address until it returns.
• Manually typing a wrong address is safe: your phone has pinned the desktop's identity, so a wrong or hostile address can only fail to connect — it can never impersonate your desktop.
• Do not forward the companion port on your internet router as a shortcut. A VPN keeps the listener off the public internet, which is the supported way to connect remotely.

Connection states

• Live now means the phone has authenticated the paired desktop and is receiving current state.
• Connected - refreshing from desktop means the channel is live and a fresh authoritative snapshot is replacing cached state.
• Reconnecting - showing the last desktop snapshot means visible data may be stale. Controls are unavailable until the connection is live again.
• This phone was revoked on the desktop is final. Pair again only if the desktop owner intends to restore access.

Opening the app in the foreground starts an immediate reconnect. Alerts are best-effort in v1 and may not arrive after the phone has been locked for a long period.

If a run does not appear

1. Confirm the desktop app is open and the expected workspace is open.
2. Confirm the Runs banner says Live now.
3. Open mobile Settings and select Refresh connection.
4. If the desktop's local IP address changed, select Update address by QR and scan a fresh QR from the same desktop, or select Type address manually and enter the new address. Both preserve the pinned identity.

If pairing or reconnecting fails

• Put both devices on the same normal home or office LAN. Guest Wi-Fi and client isolation commonly block device-to-device traffic.
• Confirm Allow your phone on this LAN is enabled and the desktop status says Ready on your local network.
• Allow Cerevisor through the desktop firewall for private networks.
• Replace an expired QR instead of retrying the old one.
• If the phone was revoked or belongs to a different desktop, unpair on the phone and deliberately pair again.

If an output does not open

• Reconnect first; output capabilities belong to the current desktop workspace snapshot.
• Retry a locked HTML viewer that reports it did not finish opening.
• Open oversized or unsupported files on the desktop. The phone viewer intentionally fails closed instead of browsing arbitrary files.

Unpair versus revoke

Unpair this phone removes the local phone identity from that phone. It does not prove that the desktop has revoked the old public key.

Revoke in desktop Settings > Mobile companion > Paired phones is authoritative. It closes a live connection and prevents that device identity from reconnecting.

For the security model and exact limits, see Mobile companion security.