Skip to main content

Use Overdeck on your phone

Overdeck runs on a phone in two ways. The browser phone view is a small version of the dashboard at /m: you install it from the phone’s browser to the home screen, and it reaches one machine at that machine’s Tailscale HTTPS address. The Overdeck app for iPhone and Android is still in testing (see below) and reaches your machines through overdeck.ai, with no Tailscale. Both show what needs you, your conversations and the pipeline, answer agent questions, and sign in with their own pairing, never with the machine’s root token.

Before you start (browser phone view)

  • Tailscale Serve with HTTPS on the machine. A phone app needs an https:// address. Select Set up Tailscale in Settings → Anywhere (or run pan tailscale setup) to turn on HTTPS access through Tailscale Serve, so the machine is reachable at an address such as https://desk.tailnet.ts.net. See Remote access for trusted addresses and pairing.
  • Require a token to sign in. Turn on Settings → Access Tokens → Require a token to sign in (dashboard.require_token_mint: true in ~/.overdeck/config.yaml). Tailscale Serve forwards phone traffic from the machine itself. With the setting off, the dashboard treats the phone as a browser on the machine and gives it full access without pairing. The setting turns on by itself, and cannot be turned off, once the machine has a trusted remote address, a paired device or a machine link. Set up Tailscale also turns it on.

Set up a phone

On the machine, open Settings → Anywhere → Set up a phone, or run Set up a phone from the command palette. The dialog has two tabs: Overdeck app (first) and Browser on the phone.

Overdeck app

Step 1 asks you to install the Overdeck app and sign in to it with the same overdeck.ai account as this machine. This machine must be signed in to overdeck.ai first (pan account login); otherwise the tab says so and shows no code. The iOS and Android apps are in TestFlight and Google Play internal testing. They are not in the public App Store or Google Play yet, so most people should use the browser phone view below. If you have a test build of the app, select Create pairing code and scan the QR code with the app. The code works once and expires after 10 minutes; select Create another code for a new one. The tab lists the phones paired with this machine; Remove signs a phone out of this machine and closes its open connections. No Tailscale is needed for the app. In the Overdeck app’s Settings, Paired machines has its own Forget, which removes a machine from the phone only; to remove the phone from the machine, use Settings → Anywhere there.

Browser on the phone

The dialog has four steps:
  1. Install Tailscale. Scan the QR code with the phone, install Tailscale, and sign in with the same account as the machine.
  2. Choose this machine’s address. The list offers only trusted https:// addresses that other devices can reach. To add one, type it and select Add. An http:// address is refused, because a phone app needs HTTPS.
  3. Require a token to sign in. The dialog checks the setting. While it is off, step 4 stays hidden. Select Open the setting, turn it on, then select Check again.
  4. Scan the pairing code. Choose Android or iPhone, then select Create pairing link. The code works once and expires after 10 minutes. Select Create another code for a new one.

Android

Scan the pairing code with the camera. Chrome opens the phone app and pairs it. Then select Install app in the banner below the header to add it to the home screen.

iPhone

The iPhone needs two scans, in this order:
  1. Scan the first QR code. It opens the app in Safari. Tap Share, then Add to Home Screen.
  2. Open the app from the home screen. Tap Scan pairing code and scan the second QR code. You can also paste the pairing link instead.
The order matters. An app on the iPhone home screen keeps its own storage, so it cannot use a pairing made earlier in Safari. Pair inside the installed app. Notifications need iOS 16.4 or later.

Answer a question

When an agent asks a question, it needs three taps:
  1. Open the app (or tap the notification).
  2. Tap an option.
  3. Tap Send.
The first open question is already expanded. A notification link opens its own question. To give an answer that is not an option, tap Type an answer.

See the pipeline

Tap Pipeline (or open /m/pipeline) to see the active issues grouped by phase: Ship, Review, Work, Plan and Ready. Each row shows the issue ID and title, with its project and how long ago it changed. Needs you marks an issue that waits for you. Tap a row to see the issue: its phase, state, agent (Live, Idle, Waiting for you, Done or Stopped, with its last activity), cost so far by stage, pull request with its review and checks, description (long ones collapsed behind Show more), project, labels and a link to the tracker. A value the machine cannot read says “not available”. The pipeline on the phone is read-only. To start, stop, merge or move an issue, use the desktop.

What the phone can and cannot do

The phone answers questions from agents and conversations, including questions with more than one part and Codex approval menus. It uses the same delivery as the desktop dialog. Other kinds of waiting input are shown but not answered on the phone. These include permission prompts, plan approvals, choice menus, rate-limit menus, session resume, held handoffs and turns that ended. Needs you also shows read-only rows for MCP sign-ins and other machine notices, such as “Approve on the desktop”, harness update failures, restart resumes, bot connections and agent requests. For a conversation, tap Open to read it. For an agent, answer it on the desktop. The phone groups conversations by project. Each project gets its own header, with No project last. Every group starts collapsed, and the phone remembers which groups you opened. Tap + next to a project’s name to start a conversation in that project; it opens full screen and uses the machine’s default model. Conversations owned by linked machines are listed too; opening one reads it from the machine that runs it, the same as the desktop, at /m?conversation=@<environment-id>/<name>. A machine running an older version of Overdeck shows its groups by project key, with no +, until you update it. The phone does not show terminals. It shows the pipeline but does not change it: there are no issue actions, filters or drag and drop. In a phone browser at /m, a banner “A newer Overdeck is running. Reload to update.” appears once the dashboard you are pointed at has been updated since this tab loaded it. Tap Reload; unsent drafts are kept. The installed Overdeck app updates when you install a new build and shows no banner.

Notifications

In the browser phone view, tap Turn on notifications in the banner below the header, or in Settings (the gear in the header), and allow notifications. In the Overdeck app, turn on Notifications in the app’s Settings; see Push notifications for Android permission. A notification for a question or an approval opens its card in Needs you. A notification that an issue finished, failed or stopped opens that issue’s sheet instead, with a What happened line naming the event and when it happened. See Push notifications for what is sent and how it is encrypted. The installed Overdeck app bundles its own copy of the phone screens, so a change to them reaches the app only with a new app build. A notification for a question that is no longer waiting opens Needs you with “This question was already answered.” When this machine cannot read a linked machine’s list, Needs you shows Can't reach <machine>; it may have items waiting. Open that machine from the machine list to see its items. The phone app’s service worker only shows notifications. It never stores pages, so the phone always shows the current state of the machine.

Appearance

In the Overdeck app, open Settings and choose System, Light or Dark under Appearance. System follows the phone’s light or dark setting and changes with it. The choice is stored on the phone only and stays after you close the app or switch machines. Signing out resets it to System. The lock-screen Live Activity and notifications follow the phone’s own appearance. In the browser phone view (/m), tap the gear in the header and choose System, Light or Dark. The choice is stored in this browser only, and it never changes the desktop dashboard’s theme. With nothing chosen, the phone view follows the device’s light or dark setting.

Look and feel

The Overdeck logo animation plays once when the app opens. In the browser phone view it plays once per browser session, on the first plain /m load; opening a link to a question, conversation or issue skips it. A tap skips the animation. With Reduce Motion on, it shows the logo without movement for a moment instead. In the browser phone view, the install and notification hints sit in one banner below the header. You can dismiss the banner; both controls stay in Settings (the gear in the header).

Diagnostics

When the machine you open has anonymous telemetry on, the Overdeck app sends anonymous diagnostics to PostHog so the maintainers can fix what is actually failing: failed API routes and their HTTP status (exact for common codes, otherwise the status class), your phone’s link health (failures, drops, and recoveries), and app crashes without their messages. Events carry the machine’s anonymous install id, the platform, and the app version, never conversation content, names, labels, URLs, or your GitHub identity. See Anonymous telemetry for the full list of what is and is not sent. Turning telemetry off in the machine’s Settings → Telemetry reaches the phone the next time it successfully connects to that machine.

Remove a phone

On the machine, open Settings → Anywhere → Paired devices and select Revoke next to the phone, or select Remove under Phones paired with this machine in the Set up a phone dialog’s Overdeck app tab. The next time the browser phone view opens, it shows Pair this phone again. The Overdeck app shows “This phone was removed from <machine>. Pair again.” with Pair again and Forget.

Delete your account

In the app, open Settings and tap Delete account. Type DELETE and confirm. Deletion signs out every device, removes your machines from the directory, and deletes your hosted data within 24 hours; it can’t be undone. The phone then signs out and shows Your account is being deleted. If the request fails, the phone stays signed in and offers Delete on the web instead. You can also delete the account at https://account.overdeck.ai/account.

Get help

Still stuck? Ask on the Overdeck Discord or file a GitHub Issue.