Skip to content

Remote control and mobile

Control Center is a desktop app, but the work it tracks doesn’t stop when you step away from your desk. Remote control pairs your phone with your cc_server, using Remote, the companion app at remote.usectrl.dev, so you can follow the fleet from there: read messages and tickets, reply to an agent, and triage your newsfeed over an end-to-end-encrypted connection. The phone and cc_server are trusted plaintext endpoints; a relay carries only encrypted application records.

Think of it as a read-mostly companion to the deck. It is not meant to replace the full desktop client.

The phone reaches cc_server over a WebSocket: either a direct connection (loopback, LAN, tailnet, or wss://) or an invite-gated room on a signaling broker. Both paths require an authenticated, end-to-end-encrypted session; the broker only forwards its encrypted records. There is no peer-to-peer data channel.

The paired phone reaches a small, intentional slice of the server’s surface:

  • Read tickets, agents, spaces and their messages and your newsfeed
  • Reply: send a message in a space, update or assign a ticket, mark an article read or saved
  • Run a playbook: instantiate a saved plan template with its parameters. This only proposes a plan; nothing executes or spends until an operator approves it in Plan Studio on a full client
  • Switch workspaces, from the phone’s own picker

That is close to all of it. A phone is a lower-privilege principal than a full client. It cannot spawn processes, spend LLM budget, push to GitHub, or create workspaces. See the access model for how that is enforced rather than merely intended.

When the phone cannot reach the server directly, the connection uses a brokered relay: the server joins one invite-gated room on a wss:// broker as its owner and paired clients join with time-boxed admission tokens. Three pieces come together:

Piece Role
Remote (phone app) The companion web app, hosted at remote.usectrl.dev by default, or self-hosted. Loads in a browser, holds the pairing record in IndexedDB.
Relay broker A stateless wss:// relay (cc_signaling_server) hosting N-way rooms. It forwards encrypted records without the pairing secret or app plaintext, but sees routing identifiers, IPs, record sizes and timing.
cc_server The room’s owner. It answers the phone’s calls through the same dispatcher every other client uses.

A pairing offer carries a connection descriptor listing every path to the server (LAN, tailnet, public wss://, relay) plus its identity fingerprint. The phone’s resolver picks the best reachable path. The server signs the encrypted handshake, and the client pins its fingerprint. On first connection, check the fingerprint against a QR or another trusted source: a first signed identity alone does not prove which server you reached. A changed pin is rejected rather than silently trusted again. The relay carries ciphertext when no direct path exists, but can still interrupt or delay the connection.

Pairing is minted from the app and delivered as a deep link; see Pair a device for the procedure. The anatomy is what matters here.

https://<pwa-host>/#<payload>

The payload rides in the URL fragment, the part after # that browsers do not send in the HTTP request to the PWA host. It carries everything the phone needs to reach the server and prove who it is: the connection descriptor (every path plus the identity fingerprint), a freshly minted device id, a 32-byte pre-shared key and an expiry stamp. The phone decodes it, stores a pairing record locally and strips the fragment from the URL. The web app’s code can read the fragment, so use a trusted app host and treat the link as a secret.

There are two payload shapes and they are not interchangeable. The phone QR minted from the in-app pairing panel is the v2 PairingPayload above, pointed at the Remote PWA host. cc_server pair --client-url emits a v1 link ({s, i, k} — server URL, device id, key) for the web and desktop clients: open it in a browser, or paste it into Paste a pairing link on the desktop. These are pairing data formats, not transport fallbacks: both clients must support the current encrypted session protocol.

They also differ in lifetime, which is easy to get wrong:

Minted by Credential expiry
In-app pairing panel (pairing.mint) 30 days, always
cc_server pair on the command line No expiry encoded; server policies still apply

Server-wide maximum device-age and idle-timeout policies can reject either credential earlier. Neither pairing format bypasses those policies.

A paired device is authenticated but untrusted. Several independent gates keep an approved (or leaked) pairing from becoming full control of the server.

1. Membership, not pairing, is the boundary

Section titled “1. Membership, not pairing, is the boundary”

A valid pairing key proves which device you are. What you may read or change is decided by your workspace role, re-resolved on every single call and by per-repo grants on anything that exposes repo content. A device holding a perfectly good key but belonging to a user who is not a member of the named workspace is refused with “Not a member of this workspace”.

The role floor is derived from the operation’s kind unless it declares its own: reads need guest, mutations need member, destructive operations need admin.

Beyond the role check, a phone session carries a lower capability than a desktop or web session. Operations declared full-client-only are refused for a phone before the handler runs, regardless of how privileged the user behind it is: minting, listing, renaming and revoking device pairings; reading and setting tunnel connectivity; server backup and workspace export/import; process detection and kill; adapter probes; server settings; SSO admin; fleet control; and taking over or handing back a running agent.

For the MCP tool surface specifically (tools/call), a default-deny allow-list governs which tools the phone may invoke. Anything not listed is rejected before it runs. The list is read-and-observe heavy plus a handful of local-only writes — a message, a ticket update, an article flag — that spend no LLM budget, spawn no process and touch no external system.

Denied, for example: consulting an agent, starting an AI review, killing an agent, publishing a review to GitHub, hiring or firing agents, creating a workspace.

The server holds no “current workspace”. It is stateless by design: every workspace-scoped call must name its target workspace_id in its arguments and the dispatcher refuses the call outright when that is missing or names a workspace the server does not have registered — before anything opens a database. A phone can therefore never inherit or drift into another client’s scope and naming a foreign workspace does not help either, because the membership check in gate 1 still applies. This is the same workspace isolation invariant the rest of the product enforces.

5. End-to-end encryption on direct and relayed connections

Section titled “5. End-to-end encryption on direct and relayed connections”

Every direct or relayed client session requires a signed Noise handshake. The pairing key authenticates that handshake; fresh ephemeral keys derive the traffic keys, rather than using the pairing key to seal each frame. The server signs its identity into the exchange and the client checks its saved fingerprint pin. There is no plaintext or older-client fallback. A relay admission token only gets a client into a room; it cannot decrypt the records.

An app-minted credential is time-boxed to 30 days; past that the connect gate fails it and the phone must re-pair. Revocation is live: the server watches the device table and drops a revoked device’s open sessions within seconds rather than waiting for its next connect.

A sliding-window limiter caps remote tool traffic at 120 calls a minute, with a tighter 30-a-minute sub-cap on the mutating verbs. The budget belongs to the principal, not the session: three of your devices draw from one allowance, so a hijacked client cannot buy headroom by opening more sessions and one noisy member cannot starve the others.

The relay broker hosts transient, invite-gated rooms and forwards encrypted records without app plaintext or pairing keys. It still sees IP addresses, room and peer identifiers, record sizes, timing and connection lifetime, and can drop or delay traffic. The paired client and the chosen cc_server are the plaintext endpoints; the server operator and services it sends content to can see that content. Encryption in transit does not encrypt server data at rest.

Once paired, the phone receives live updates as notification frames — new agent messages, tickets assigned to you, status changes — mirroring the desktop’s own notifications. The server checks workspace membership before forwarding an event to a session. The client then filters those authorized events to the workspace you are viewing; that display filter is not the access boundary.

Surface What it shows
Settings → You → Your devices (/workspaces/:workspaceId/settings/you/devices) Paired clients with live status, plus Pair a new client (web browser, desktop app, or phone) and revoke

The same panel mints pairings for a second browser or desktop app, not just phones — the flow is identical, only the deep link differs.