The agent and its relay
What Deploy does, how a pane on your screen reaches a session on the agent, and how sharing is enforced.
A Griddler Agent is a container that runs your Claude Code and Codex sessions somewhere other than your PC. This page is the mechanics behind that page.
What's in the container
- tmux, which holds every session as a window, so a session outlives whoever is looking at it.
- Claude Code and Codex, signed in with copies of your own sign-ins.
- The agent, a small program that starts and stops sessions, reports their state, and carries their terminals to Griddler Social.
- Your repositories, mounted from the machine it runs on: your home folder on a dev VM, or the folder
that holds your checkouts (like
C:\Source, seen as/src) on Docker Desktop. - A volume for the agent's own home: sign-ins, settings and session history. It survives upgrades and Remove.
What Deploy does
Check the machine
Over SSH for a dev VM, or through Docker Desktop locally: is docker there, is it a headless machine, and which VM is it.
Enrol
Griddler registers the agent with Griddler Social under your name and gets the agent its own key. Social stores only a fingerprint of that key.
Get the image
An installed Griddler asks Social for a short-lived pass to River Logic's container registry, and the machine pulls the agent image that matches your version of Griddler. The pass is used once and never stored.
Copy your sign-ins
Your Claude Code sign-in (and Codex's, if you're signed in), your Claude settings without their hooks, and your git config are copied into the volume. Nobody signs in on the VM.
Start
The container starts, set to restart on its own. Within a few seconds it reports in, and the card turns online.
How a pane reaches a session
The agent never listens for connections. It opens one outbound connection to Griddler Social and keeps it open. Your Griddler opens its own connection to Social for each agent pane. Social joins the two.
When you open an agent pane:
- Your Griddler asks Social for that session, with your sign-in.
- Social checks that the agent is yours, or that its Sharing covers you, and in which mode.
- Social tells the agent to open a view. The agent gives that view its own private tmux session holding only that one window, so no keystroke can reach another session or a shell.
- From then on, bytes flow both ways through Social. Social drops a watcher's typing before it reaches the agent.
Closing the pane closes that view. The session itself keeps running in tmux.
Sharing, enforced by Social
| Sharing | Who Social lets in | Their typing |
|---|---|---|
| Private (new agents start here) | Only you | — |
| Team can watch | Anyone signed in at River Logic | Dropped |
| Team can drive | Anyone signed in at River Logic | Passed through, as you |
Social checks sharing again whenever it changes. Narrowing it disconnects the people it no longer covers, with the reason; widening it to drive lets people already watching type at once. kick on the agent's card disconnects one viewer.
The agent's own key can only do agent things: report in, pick up work, and carry terminals. It can't enrol, change sharing, read anyone's mail, or fetch images.
What's recorded
- Social records who opened which session, when, for how long, and whether they watched or drove.
- It doesn't record what was typed or shown. There's no scrollback on the server; a new viewer sees the session's current screen because tmux redraws it.
- The agent's reports carry each session's state, folder, title and its last few lines, for the card and the attention colours.
When Social isn't there
If the relay is down, the PC that deployed the agent can still reach it directly, over SSH or docker, and Griddler uses that for its own panes. Teammates can't: sharing only works through Social.
Limits
- 8 viewers on one session, 32 open panes on one agent, and 8 agent panes open per person.
- The connections send a keep-alive every 30 seconds, so an idle pane stays connected.
- A view with no keystroke for a day is closed on the agent.