Griddler Agent

Where: Top bar→Agents

Griddler Agent runs Claude Code and Codex in a container on a headless dev VM, or in Docker Desktop on your own PC. Its sessions keep running after you close the pane or quit Griddler. On a dev VM they also keep running when your PC is off. From your grid you start a session on the agent, or open one that's already running, and the pane becomes that session's live terminal.

You can share an agent with your team. Teammates open its sessions through Griddler Social with their own sign-in. They don't need SSH or an account on the VM.

⤢ Open

Before you deployCopy Anchor Link

The exact errors and their fixes are under When something goes wrong.

Set up and use an agentCopy Anchor Link

Deploy

Click the robot icon in the top bar to open Agents and pick where the agent runs:

Pick	Runs on
This machine — Docker Desktop	Docker Desktop on this PC.
VM name — your dev VM · purpose · region	That dev VM. The list shows the team's dev VMs whose owner tag names you, straight from Azure, so a new VM shows up within 5 minutes. Hover one for its SSH host, size and IP, and who else it's shared with.
Other ssh host…	A box opens: type the SSH host of a VM that isn't on the list. Deploy stays greyed until you do.

With no VM tagged to you, the last row reads Other ssh host… (no dev VM is tagged to you); signed out, Other ssh host… (sign in to see your dev VMs).

Click Deploy. Griddler remembers which row you picked for next time (not the host you typed).

Griddler checks the machine, gets the agent image for your version of Griddler, and copies your Claude Code sign-in (and Codex, if you're signed in) to it. Nobody signs in on the VM. The line under the list shows each step, then ✓ done.

Start a session

Open the New Terminal dialog and set Where to your agent. Repository lists the checkouts the agent found, or Agent home (no repo). Pick a model and click Start.

1234

⤢ Open

1. 1Set Where to your agent
2. 2Pick a checkout, or Agent home
3. 3Pick a model and effort
4. 4Start

Close it and come back

Closing the pane only detaches it; the session keeps running on the agent. Reopen it with Open in Agents, or pick it under Session in the New Terminal dialog (join: …) and click Join. After Griddler restarts, an agent pane in a tab you haven't opened yet shows ▷ Reconnect · the machine · the folder, like ▷ Reconnect · agent-local · agent. Click it to reconnect to the same session, with its history.

⤢ Open · replay

Share it

Each agent has Sharing: Private, Team can watch or Team can drive. See below.

What an agent pane looks likeCopy Anchor Link

An agent pane is a normal pane in your grid. Its folder badge names the machine and the folder, like devvm · griddler, or just the machine, like agent-local, for the agent's home folder. Hover it for the full path and the agent's name.

⤢ Open

• It turns green when the session needs you, like a local pane, a few seconds after it happens.
• It gets your directives and the team tools when it starts, acting as you.
• The session belongs to the agent, not the pane. Closing the pane, quitting Griddler, or turning your PC off (dev VM only) doesn't end it. Stop in Agents does, and so does quitting Claude or Codex inside it.
• On a teammate's agent shared as Team can watch, the header shows 👁 watch only. Typing does nothing and the chip flashes. The model and effort menus are greyed out too.

⤢ Open

What the agent gets from youCopy Anchor Link

Deploy copies these each time, and Re-sync copies the sign-ins and settings again.

The agent sees your repositories through one mounted folder. On a dev VM that's your whole home folder, at the same path. On this PC it's the folder that holds most of the repositories Griddler knows, such as C:\Source, which the agent sees as /src. The step log's [repos] line says which folder it picked. Checkouts directly inside that folder show in Repository.

Who can see and drive your agentCopy Anchor Link

A new agent starts at Private. Deploying it again keeps whatever you picked; deploying after Remove starts at Private again.

• Anyone who drives a session is typing as you, with your Claude Code, Codex and git sign-ins, in your checkouts.
• Anything printed in a shared session, including tokens or connection strings in command output, is visible to everyone watching it.
• A change to Sharing takes effect immediately. Widening it to Team can drive lets people already watching type straight away. Teammates it no longer covers are disconnected.
• On it now on the agent's card lists who has a session open, and whether they're watching or driving. kick disconnects them; they can reopen it while Sharing allows. Your own rows say (you) instead: close your own cell from the grid.
• Only a driver's window sets the session's size. Watching never resizes it for you.

Reading the Agents panelCopy Anchor Link

Your agents are under Your agents, one card each:

Under the buttons, one line per session: its state (needs you, working, done after a turn, idle, starting), the agent and its title, or its folder and start time (claude · agent · started 07:41 PM), the last thing it said, then Open (puts it in your grid) and Stop. On it now uses the same names. Stop asks first; the session's transcript stays on the agent. States can take a few seconds to update.

Agents teammates share with you are under Shared with you: the agent's name and the owner (… · rowan's), its state, the sessions with Open, and you can drive, watch only, via ssh / via local (you reach it directly, from the PC that deployed it) or unreachable (it isn't connected to Griddler Social).

⤢ Open

The list refreshes every 30 seconds while the panel is open; ↻ Refresh checks now.

The top-bar buttonCopy Anchor Link

The robot icon turns green while an agent is reporting in, and amber when one of its sessions needs you. Its tooltip then reads like Agents — 1/1 beating · a session wants you. With the panel closed it updates every 2 minutes.

When something goes wrongCopy Anchor Link

Deploy, Re-sync or Remove failedCopy Anchor Link

The line under the list shows ✗ and the error, with the step log open (show log / hide log toggles it), and these tools:

Deploy errorsCopy Anchor Link

A host typed in the wrong case (your SSH config says devvm, you typed DEVVM) is corrected for you and noted in the log.

Opening a session failsCopy Anchor Link

When a pane stopsCopy Anchor Link

An agent pane that loses its session is covered by Disconnected — and the reason, with Close pane. For the reasons that aren't about permission, there's also ▷ Reconnect: it reattaches the session if its window is still there on the agent, or resumes it into a fresh one if the agent was redeployed.

⤢ Open

Look inside the containerCopy Anchor Link

The container is named griddler-agent- plus the agent's name with @ turned into -, like griddler-agent-you-devvm. Run these on the machine it runs on:

docker logs -f griddler-agent-you-devvm      # the agent's log
docker exec -it --user 1000 -e HOME=/agent griddler-agent-you-devvm tmux attach -t griddler   # its sessions
docker volume rm griddler-agent-you-devvm    # after Remove: delete its sign-ins and session history

On the PC that deployed the agent, Griddler connects to it directly over docker or SSH when Griddler Social can't carry the session.

Doctor rowsCopy Anchor Link

The Doctor has two rows under Griddler:

What to knowCopy Anchor Link

• Runs as you. The agent uses the sign-ins copied from the PC that deployed it. Re-sync copies them again after you sign in again on that PC.
• Skips permission prompts unless you say otherwise. The New Terminal dialog's bypass box decides for each new session. Its default comes from Bypass permissions by default (dangerous) in Settings→Panes & startup.
• Nothing on the VM listens to the network. The agent makes only outbound connections; the terminal travels over one connection to Griddler Social.
• Griddler Social relays the terminal but doesn't store it. It keeps no scrollback and no keystrokes, only who opened which session, in which mode, and for how long.
• Upgrading restarts sessions. Clicking Deploy again replaces the container. Open panes show Disconnected with ▷ Reconnect: Claude sessions resume from their history; Codex sessions start fresh.
• Removing an agent keeps its data. Remove stops the container and revokes its access. Your copied sign-ins and session history stay on that machine for a later Deploy.
• A Griddler Trace includes the last failed Deploy, Re-sync or Remove.

LimitsCopy Anchor Link

• Up to 8 people on one session, 32 open panes on one agent, and 8 agent panes open per person.
• Desktop Griddler only. You can't open agent sessions from the iPhone app.
• If Griddler Social restarts, open agent panes show Disconnected. The sessions keep running; click ▷ Reconnect.
• Attention on agent panes arrives a few seconds after the session changes.
• Right after Deploy, opening a session can fail with "not streaming through Griddler Social" for up to a minute. Try again.
• A title you type in an agent pane's header stays in your grid; the session on the agent doesn't get it.
• Profile is greyed out for agent sessions: they always use the sign-in the agent was given.
• Co-op campaigns aren't available on agent panes.
• Git over HTTPS doesn't work from a Docker Desktop agent. Agents on a dev VM use your git sign-in there.
• A session on an agent can't see the other panes in your grid or drive your web cells; see Agent tools.
• Viewers idle for a day are disconnected.