# Remote Access

Polyscope includes a remote access feature that lets you monitor and interact with your workspaces from any device — your phone, a tablet, or another computer's browser. All communication is end-to-end encrypted through a relay server, so your code and conversations stay private.

## How It Works

Remote access uses an E2E encrypted relay to connect your devices:

1. Your Mac registers with the relay server using your GitHub account
2. Your remote device authenticates with GitHub and connects to the relay
3. Your Mac and the remote device perform an encrypted key exchange
4. All subsequent messages are encrypted on your Mac before they leave, and only your device can decrypt them

The relay server acts as a transparent pipe — it forwards encrypted blobs between your devices but cannot read them.

## Setup

1. **Sign in with GitHub** on Polyscope desktop
2. Your Mac automatically registers with the relay when Polyscope is running
3. On your remote device, open the Polyscope URL and sign in with the same GitHub account
4. Your Mac appears in the server list — tap to connect

No additional configuration is needed.

<!-- ![Remote access connection](/images/docs/TODO.png) -->

## Mobile Access

The mobile interface gives you full access to your workspaces on the go:

- **Send prompts** — Write and send prompts to agents
- **View activity** — See agent messages, tool calls, and progress in real time
- **Approve plans** — Review and approve or deny agent plans
- **Answer questions** — Respond to agent questions
- **Review changes** — Browse changed files and diffs
- **Create workspaces** — Start new workspaces from your phone
- **Switch workspaces** — Navigate between active workspaces

<!-- ![Mobile interface](/images/docs/TODO.png) -->

## Desktop via Browser

Remote access also works from any desktop browser. This means you can connect to your Polyscope instance from a second computer — useful when you're at a different desk or working from a shared machine.

## Security

### End-to-End Encryption

Every message between your Mac and remote device is encrypted with **AES-256-GCM**. The encryption key is established through an **ECDH P-256** key exchange with ephemeral keys — meaning a fresh key pair is generated for every connection session.

### Server Identity Verification

Your Mac has a persistent identity key (ECDSA P-256) that is pinned when you first connect. On subsequent connections, the remote device verifies the server's signature to ensure you're connecting to the same Mac — not an impersonator.

### Forward Secrecy

Because the key exchange uses ephemeral keys, compromising one session's key does not reveal past or future sessions.

### Zero-Trust Relay

The relay server:

- **Cannot decrypt** your messages — it only sees encrypted payloads
- **Cannot inject** messages — the identity signature prevents impersonation
- **Validates** that your GitHub account owns the server before allowing connections

## Multi-Server Support

You can connect to multiple Polyscope servers from the desktop app — useful when you run separate instances on different machines (e.g., a local Mac and a remote Linux server).

### Servers Menu

The native **Servers** menu in the menu bar lists all registered servers. Select a server to switch the current window's connection. Each window can connect to a different server independently, so you can monitor your local and remote workspaces side by side.

### Switching Servers

When connected to a remote server, the workspace header shows a **[server]** label so you always know which server you're working with. To switch:

1. Open the **Servers** menu in the menu bar
2. Select the server you want to connect to
3. The current window reconnects — other windows stay on their existing server

## Preview URLs

When you're connected to a remote server, Polyscope automatically creates a secure tunnel so you can access your workspace's preview URL from any device.

## Troubleshooting

- **Mac not appearing in server list** — Make sure Polyscope is running and you're signed in to the same GitHub account on both devices
- **Connection drops** — The relay reconnects automatically. If it persists, check your internet connection on both devices
- **Authentication errors** — Sign out and sign back in with GitHub on the device showing the error