> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Remote

> Check on your agents from your phone — pair with a QR scan, no account needed

Start a task on your computer, walk away, and check on your agents from your phone. See who's working, who's idle, who needs input. Send messages, answer questions, resume sessions — all from a chat-style interface on your phone.

No account, no app install. Scan a QR code and you're connected. End-to-end encrypted — the relay server never sees your code, prompts, or output.

## How It Works

Your phone connects to your desktop CliDeck through a lightweight relay:

```
Phone ←→ Relay (Cloudflare) ←→ Desktop CliDeck
              (encrypted,
            can't read anything)
```

1. **Your desktop** runs CliDeck as usual with your agent sessions
2. **The relay** forwards encrypted messages between your phone and desktop — it never decrypts them
3. **Your phone** opens a web app that shows your sessions in a chat-like interface

The relay is a Cloudflare Worker that passes encrypted blobs between two WebSocket connections. It doesn't store anything. When you disconnect, the room is gone.

## Security

Mobile Remote uses **end-to-end encryption (E2E)**. Here's what that means in practice:

| What                     | Who can see it                                         |
| ------------------------ | ------------------------------------------------------ |
| Your prompts and code    | Only your phone and your desktop                       |
| Agent responses          | Only your phone and your desktop                       |
| Session names and status | Only your phone and your desktop                       |
| Anything at all          | **Not the relay. Not CliDeck's servers. Nobody else.** |

**How the encryption works:**

* When you pair, your desktop and phone each generate a cryptographic key pair (ECDH P-256)
* They exchange public keys through the relay to derive a shared secret
* All messages after that are encrypted with **AES-256-GCM** — the same standard used by Signal and WhatsApp
* The relay only sees encrypted blobs. It cannot decrypt them. Even if someone intercepted the traffic, they couldn't read it

The pairing URL (in the QR code) contains your desktop's public key in the URL fragment — the part after `#` that browsers never send to the server. The relay never sees it.

<Note>
  CliDeck is a local tool. Mobile Remote doesn't change that. Your code, prompts, and agent output stay between your devices. The relay is just a dumb pipe.
</Note>

## Getting Started

Mobile Remote is built into CliDeck. No separate app to install.

<Steps>
  <Step title="Have active sessions">
    Mobile Remote shows your existing sessions — it doesn't create new ones. Launch one or more agent sessions in CliDeck first.
  </Step>

  <Step title="Click the mobile icon">
    In the CliDeck sidebar, click the **phone icon** in the navigation rail. A modal opens.
  </Step>

  <Step title="Install (first time only)">
    The first time you use Mobile Remote, CliDeck installs the `clideck-remote` package automatically. Click **Add to CliDeck** and wait a few seconds.
  </Step>

  <Step title="Scan the QR code">
    A QR code appears. Scan it with your phone's camera. A web app opens in your phone's browser — no app store download needed.
  </Step>

  <Step title="You're connected">
    Your phone shows all your active sessions. Tap one to see the conversation and start interacting.
  </Step>
</Steps>

You can also copy the pairing link and open it manually on any device with a browser.

## What You Can Do From Your Phone

Once paired, your phone shows a session list grouped by project — similar to a chat app.

### View sessions and status

Each session shows its name, agent icon, last message preview, and a live working/idle indicator. You can see at a glance which agents are done and which are still thinking.

### Send messages

Tap a session to open it. Type a message and hit send — it goes straight to the agent's terminal, as if you typed it on your keyboard.

### Answer agent questions

When an agent presents a choice menu (like "Yes / No / Yes to all"), the menu appears as tappable buttons on your phone. No need to type — just tap your choice.

### Resume previous sessions

Saved sessions from previous CliDeck runs appear in a separate section. Tap to resume them.

### Close sessions

Swipe or use the session menu to close a session from your phone.

## What You Can't Do (Yet)

* **Create new sessions** — You can only interact with sessions that already exist on your desktop. Start sessions from CliDeck on your computer first.
* **Multiple phones** — One phone connection at a time per CliDeck instance.

## Desktop Lock Screen

While your phone is connected, CliDeck shows a lock screen overlay on your desktop. This blurs the terminal content and blocks keyboard input — so if you're away from your desk, nobody can see your sessions or type into them.

The lock screen shows:

* Connection time
* Number of active sessions
* A **Disconnect** button to end the session

When your phone disconnects (close the browser tab or navigate away), the lock screen lifts automatically and your desktop returns to normal.

## Free Tier

Mobile Remote is free with one limit: **one active session at a time**. If you tap a different session while one is open, your current session closes first.

A confirmation prompt lets you know before switching. You can check "Don't show again" to switch silently.

## Disconnecting

To end a mobile session:

* **From your phone** — Close the browser tab
* **From your desktop** — Click **Disconnect** on the lock screen, or click the mobile icon in the sidebar and disconnect from the modal

Once disconnected, the relay room is destroyed. Your pairing QR code is single-use — pair again next time with a fresh QR code.

## Troubleshooting

### QR code not appearing

* Make sure `clideck-remote` installed successfully. Check the mobile icon modal for error messages.
* Try clicking the mobile icon again to retry pairing.

### Phone can't connect

* Make sure your phone has internet access.
* The QR code is single-use. If you've already scanned it once and disconnected, click the mobile icon to generate a fresh one.

### No sessions showing on phone

* Mobile Remote only shows sessions that are already running on your desktop. Create at least one session in CliDeck first.
* If you just started CliDeck, wait for the agent to initialize before pairing.

### Status not updating on phone

* Make sure telemetry is configured for your agents. Without telemetry, CliDeck can't detect working/idle status — and that means your phone can't show it either.