Your computer
Attention detection
A command finishes.
A session goes quiet.
An agent needs attention.
Private context encrypted per phone
The terminal stays
on your computer.
Your computer owns the sessions. Your devices own the encryption keys. WebRTC carries terminal traffic directly between them whenever the network allows it. The relay handles setup, coordination and encrypted fallback.
Your computer
Computer service
Reads your terminal.
Encrypts screen updates.
Accepts authenticated input.
Keys stay here
WebRTC
data channelDirect path
unavailableEncrypted
terminal trafficEncrypted
relay route below
data channelDirect path
unavailableEncrypted
terminal trafficEncrypted
relay route below
Your phone
Mobile app
Decrypts screen updates.
Renders the terminal.
Encrypts your replies.
Keys stay here
Your chosen relaySetup & coordinationEncrypted WebSockets
Once WebRTC connects, screens, history and input travel directly between your devices. The relay stays connected for pairing, encrypted signaling, revocation and push.
If the direct connection is blocked or drops, encrypted terminal traffic uses the relay. Shellbell retries WebRTC while you’re using the app.
Your terminal content stays encrypted on both routes. Transport details
Event &
encrypted box
encrypted box
Relay + native push
Delivery attempt
Bounded relay notification job.
Google FCM on Android.
Apple APNs on iOS.
Routing metadata remains visible
Native
push
push
Your phone
Native receiver
Authenticates private context.
Decrypts supported details.
Presents the notification.
No live background terminal socket
Notification keys are separate from terminal keys. Provider acceptance does not prove a notification appeared on the phone.
Direct when available.
Relay when needed.
Setup starts with the relay. Shellbell then tries a direct WebRTC connection and moves terminal traffic onto it after the devices authenticate the new path.
Find each other.
Both devices connect outward to your chosen relay. Paired identities establish an encrypted session. Terminal access works on this route before WebRTC is ready.
Move the terminal traffic.
WebRTC offers, answers and network candidates travel inside encrypted relay signaling. The devices check certificates and fresh keys, then agree to switch. Screens, history and input use the direct data channel.
Recover if the route fails.
A blocked or lost direct connection uses encrypted relay transport. Shellbell retries WebRTC while the app is open. Input with an uncertain outcome is not automatically replayed during a switch.
Less terminal traffic at the relay.
Once WebRTC takes over, the relay no longer forwards terminal frames. Both relay sockets stay connected for signaling, pairing, revocation and push. Direct transport reduces terminal bytes, not the number of relay connections.
The network still matters.
STUN helps the devices discover addresses; it does not carry terminal content. No TURN server is configured. Restrictive networks can therefore remain on relay transport. Hosting your own relay does not change the clients’ STUN settings.
Pairing takes a scan
and your approval.
No Shellbell account or email signup. Pairing starts with the computer you control and the phone you approve.
01
Open the pairing window.
The computer creates a temporary QR code containing its public identity, relay address, a gate token, and a separate random pairing secret. The default window lasts five minutes.
02
Scan and check.
Your phone checks the computer identity from the QR. The relay checks the temporary gate and admits the request. It receives the gate hash, not the separate pairing secret.
03
Approve the phone.
Confirm the phone on your computer. The devices save their pairing keys locally. Routine reconnects and network changes don’t need another QR.
Terminal access
without moving the work.
The computer service adapts existing terminal sessions into a bounded screen model. The phone displays that model and sends your input back.
Only the session you’re viewing.
The computer captures the watched session, coalesces screen changes, and sends bounded updates. History is requested in chunks. The phone has Terminal and Reading views, and does not resize the remote terminal to fit its screen.
Computer service & backendsInput has an acknowledgement.
The computer checks the pairing and session before sending input to its terminal backend. Request identifiers help handle reconnects. An acknowledgement confirms backend acceptance, and uncertain input is not automatically replayed.
Bounded streaming contractA phone connection
that knows when to stop.
The mobile app closes live terminal connections when it goes into the background. Background alerts use the platform’s push system.
Live while you’re using it.
Screen updates serve the session you’re looking at. Leaving the app closes its WebSockets and active transport rather than keeping an always-on terminal stream in the background. Opening it again reconnects.
Mobile connection lifecyclePush when you’re away.
The computer detects attention events. The relay sends bounded notification attempts through APNs or FCM, so the phone can receive alerts without continuously polling your terminal. This design limits background work; actual battery use depends on the device and your usage.
Native notification designTwo ways to run
the computer service.
The native Mac app and headless service use the same terminal engine and phone protocol, with different service ownership.
The relay routes.
The endpoints decrypt.
The relay coordinates connections, pairing and notifications. It carries encrypted terminal traffic during setup or fallback. Once a direct route is established, that terminal traffic leaves the relay.
Shared policy, two runtimes.
packages/relay-core owns authentication, pairing, revocation, resource limits, and notification policy. Cloudflare and Node adapters supply WebSockets, storage, and scheduling. On Cloudflare, a Durable Object coordinates each computer. On Node, a single process uses private local SQLite.
Metadata has an owner.
Public identities, device names, pairing relationships, connection timing, and push-routing data support the relay’s work. Terminal plaintext and terminal decryption keys are absent. Organizations can host the same core under their own account or hostname and set their own operational policies.
Privacy here means a specific boundary: the relay cannot read your terminal. It does not mean the relay holds no metadata. The privacy inventory records what it sees and stores.
The details
are in the source.
The website explains the system. These documents define its contracts and operational requirements.
Architecture overview
Components, ownership, and session flow
Design & security boundaries
Keys, trust, input correctness, and lifecycle
Connection guide
Pairing, relay connections, and direct transport
Private notifications
Enrollment, encrypted context, and native delivery
Relay adapters
Runtime, storage, socket, and scheduling contracts
Privacy inventory
Exactly what each component stores and sees
Your terminal,
from your phone.
Free to use. Pair once, then return to the sessions you already have.