The /code panel: operating it

For operators

Deploying and running the Agents panel; users using it want Agent computers and its reference.

The Agents panel drives coding agents running on users' own computers from the chat's sidebar. The agent (opencode, or any ACP agent) runs on the user's computer under galopin, a single binary built from this repository's agent/. galopin dials out to the deployment over WSS and authenticates with its own OIDC credential. The deployment runs no model and stores no code for it.

This page is for operators. The user using the panel wants Agent computers (getting started) and the reference instead.

A session waiting on a busy model says so: when the provider answers "rate limit" or "overloaded" and the agent retries with backoff, the view shows "Retrying — <the provider's message> (attempt N, next try in S s)" beside Stop instead of a silent running turn. This needs the galopin update; an older computer keeps the plain running look.

What gets deployed

Nothing extra. The computer link is one WebSocket endpoint (GET /api/v2/code/machine), served by the chat process itself. There is no relay, no extra container and no extra port. The chat also serves the galopin binaries and their checksums at <base>/galopin/, with an installer at <base>/galopin/install.sh.

Turning it on

In the deploy kit: ./configure --agents at install time, or ./configure --set CODE_AGENTS_ENABLED=true on an existing install, then docker compose up -d.

Variable	What
CODE_AGENTS_ENABLED	true shows the Agents switch and serves /code; anything else hides it and /code answers 404
CODE_TERMINAL_ENABLED	true allows browser terminals on computers that also allow them (below); off by default
CHAT_SCHEDULES_ENABLED	on with the panel; exactly false is the kill switch for scheduled actions (below)
CHAT_SCHEDULES_MAX_PER_USER	how many schedules one user may have; default 20
CHAT_VAPID_PUBLIC_KEY / _PRIVATE_KEY / _SUBJECT	optional: Web Push keys, so users are notified when an agent needs them (Notifications for agents); the kit creates them
CODE_MACHINE_ISSUER	the issuer a computer's token must come from; defaults to the chat's own (OPENID_PROVIDER_URL)
CODE_MACHINE_AUDIENCE	the audience a computer's token must carry; default pystino-api
CODE_MACHINE_CLIENT_ID	the client a computer's token must be issued to; default opencode-enrollment

The last three only need setting when computer tokens come from somewhere unusual; the deploy kit's defaults match its bundled Authelia.

Who may use /code

CODE_AGENTS_ENABLED=true is the outer switch and always wins: off hides the Agents switch and /code answers 404 for everyone. When it is on, a further per-user answer applies on a Pystino gateway deployment: the gateway's code_agents capability (set per deployment and granted per group in the gateway console — Chat-only users). A user without it never sees the Agents switch, /code answers 404 for them with "not available for your account", and every pairing, device, schedule, file and terminal endpoint refuses them the same way — the panel reads as hidden, not as a refusal to argue with. Their computer link is closed (4404, the device staying enrolled) and reconnects by itself once a group grants the capability. A deployment with no gateway (the generic preset) is decided by the env switch alone, as before; so is an older gateway that sends no capabilities field — absent reads as allowed, never as a refusal.

Setting up a computer

On the computer, with <origin> the deployment's origin:

curl -fsSL <origin>/chat/galopin/install.sh | sh
galopin enroll --issuer <origin>/authelia --gateway <origin> --cerea <origin>/chat \
  [--no-terminal] [--deny CLASS] [--workspace-root PATH] …
galopin run

The pairing dialog prints this as one command, one step per line, calling the installed binary as ~/.local/bin/galopin. With its Install opencode box ticked it adds opencode's own installer, pinned to the release galopin is tested against (agent/packaging/opencode-version), before enroll.

The installer checks the binary against the deployment's SHA256SUMS and refuses a mismatch. The computer then appears in the panel as pending until its owner confirms it.

galopin run in a terminal stops when the terminal closes. To keep it running, the computer's owner installs it as a systemd user unit on Linux or a LaunchAgent on macOS (Keeping it running); to update galopin, the computer's owner re-runs the install line and restarts it (systemctl --user restart galopin); no re-enrollment is needed, and the computer keeps its pairing and policy (Updating galopin).

Two vetoes: the computer's and the deployment's

The computer's owner decides at enroll time what the computer allows (files, terminals, a local deny of a kind of action, slash-command shell, models from elsewhere, workspace roots). The panel's Pair a computer dialog offers every one of those flags, so nobody edits the printed command by hand. Those settings are stored on the computer, and the chat can never loosen them over the link. The table of every flag, its default and what it decides lives in one place, The computer policy; the owner can tighten a computer later without re-enrolling, but loosening needs a new enrollment.

The terminal needs both sides to say yes. The computer allows it unless it was enrolled with --no-terminal (a computer enrolled before terminals were on by default needs enrolling again), and the deployment must set CODE_TERMINAL_ENABLED=true. Everything in /code needs a sign-in within the last 7 days; the computer's own link is unaffected (see below). A terminal also re-checks that every minute. An open terminal is an ordinary shell running as the computer's owner: anyone who controls that user's Cerea session can run commands on the computer, with no model and no permission rule in between. Enable it only where that is acceptable: enabling it lets a Cerea session change the computer's local policy (a shell can edit policy.json and the config galopin starts the agent with). Both sides record terminal opens and closes, never their content.

What the fixed floor and the local deny are, until the OS sandbox exists. They are galopin refusing or asking about the calls the agent shows it, which is as advisory against bash as any tool-level rule: a shell can do anything the ask for it does not name. A local --deny command is meaningful against a hijacked Cerea session; --deny web while commands may run is not (a command can fetch), and galopin enroll / galopin policy set warn about that combination. A session created by an older galopin may still show the stuck Deny banner (its stored rules are append-only); start a new session to clear it.

The 7-day sign-in

Everything in /code needs a sign-in within the last 7 days (src/lib/server/code/stepUp.ts); the computer's own link is unaffected. It is one deny-by-default guard in hooks/handle.ts: every request under /api/v2/code/ except GET /api/v2/code/status answers 401 {code: "reauth_required"} while the session's authTime is older than the window, or missing (the hook reads it off the session document it already loaded, with no extra query). A route added under that prefix later is protected without anyone remembering to; the guard spec fails if one appears that it has not been told about.

/status is the one open route. It returns only {enabled, signedIn, fresh, reauthPath, signInPath} plus freshUntil when fresh, and nothing derived from a computer: no names, counts or inbox badge. reauthPath is a /login?reauth=1&next=/code path (with the app base) for the Sign in button; signInPath is the same destination without the force, for a caller with no session at all. A session can be unusable two ways, and the panel says which: stale (signed in, older than 7 days) gets the forced re-login, signed out (no session at all — the ordinary expiry of a chat without a refresh token) gets the plain sign-in, which the identity provider's own SSO session answers silently. A signed-out open tab leaves for that plain sign-in by itself (guarded against a loop: a redirect that already happened in the last minute is not repeated, and the card shows instead); with Authelia's bundled session settings, ticking Remember me at sign-in is what makes that re-login silent — without it the provider asks for the password again after an hour regardless of Cerea.

Three things the hook cannot see, each handled where it lives: the computer link and the terminal socket are WebSocket upgrades that bypass hooks (the terminal re-checks freshness in its own 60-second loop and closes with 4403 reauth_required), and an event stream opened while fresh ends itself with a reauth_required frame at authTime + 7d. The page asks /status on load, and a shared codeReauth store flips on any reauth_required answer or on a freshUntil timer: the panel then closes its streams, drops its in-memory computer state and shows one card. The Needs-you inbox goes dark with the rest, which is the price of the guard covering every route.

How computers are trusted

• Tokens are checked locally. A computer's access token is verified against the issuer's keys (JWKS): the issuer, the audience, the authorised client and the expiry must all match, and ID tokens are refused. The token's subject must belong to someone who has signed in to this chat; if not, the connection is refused.
• A user confirms each computer. The first connection creates a pending device. Nothing is sent to it until its owner clicks Confirm in the panel. Reject and Revoke tombstone the device: that computer id is refused from then on, its connection is closed, and galopin revokes its own refresh token and exits.
• The browser never talks to a computer. Every browser request goes to the chat, which maps each allowed path onto exactly one computer operation, after checking that the device belongs to the caller.

What the chat stores

• Pairing records (the codeDevices collection): a name, the computer id, the token subject and issuer it last used, the capabilities and policy it reported, and its credential health. None of it can reach a computer; only a live connection can, and those are held in memory.
• Files attached to agent messages, in the chat's attachment store, so they still show after a reload. They are deleted when the device is.

Everything else (workspaces, sessions, transcripts, the code) stays on the computer. That includes images a tool produced (a browser tool's screenshot, an image the agent read): the panel fetches each from the computer whenever it is shown, and the chat keeps no copy.

What the panel does

An affordance shows only when the session's backend reports the capability, and the computer's policy can still refuse it.

Feature	What the user sees	How it works
Transcript	the chat's message column, opened at the newest message	One subscription replays the session's whole log (session.sync) and then tails it live. The replay folds behind a Loading chat… skeleton, and the transcript renders once, landed at the bottom — a long session never renders progressively from the top, and nothing is scrollable while it loads, so a scroll during the load cannot strand the reader away from the newest message. After that, live turns stick to the bottom as anywhere in chat, until the reader scrolls up. The replay's end is a historyDone marker frame the bridge emits (Cerea-internal, no computer involvement). The replay carries only the newest page on a computer that pages (session.sync's limit, capability historyPaging); scrolling within about one screen of the top fetches the previous page (GET v1/agents/:id/history, op session.history) and prepends it with the visible message held where it was — a Loading earlier messages… row while it loads, a quiet Start of the session marker at the top, a retry row on failure. Older computers send the whole log as before. Going back to a session you had open shows it at once: the last 8 sessions are kept in this tab's memory (never stored on disk) and the fresh replay swaps in when it completes; until then the copy is read-only (no paging, retry or fork; a permission card waits for the refresh).
Modes and models	pills in the composer	Live lists (backend.modes / backend.models). Non-gateway models (anything outside pystino/*) are hidden unless the computer was enrolled with --allow-free-models. The agent filters them and reports how many it hid; Cerea filters again and answers 403 to a disallowed set or create (src/lib/server/code/modelPolicy.ts).
Permission selector	a Plan · Ask · Auto · Allow selector in the composer's pill row, and its note	The computer's word, never a guess. GET v1/agents/:id carries permissionMode (session.get; a subagent reports its root's); the selector shows it, and POST v1/agents/:id/permission-mode {mode} (session.setPermissionMode) sets it, after which the view re-reads the snapshot and permission.rules rather than claim the new word from the click. A bad mode is a 400 here; the computer answers invalid for a subagent's id (it follows its root) and not_found for an unknown session, and both come back as their HTTP statuses. What a session will do on each kind of action is in the shield's sheet, not beside the selector. Disabled on a subagent's view, hidden on a computer that sends no permissionMode and while the sign-in is stale. The change is audited here as permission.mode (session and mode). New sessions start on Ask. The selector's first word is Plan, which the wire still spells deny (session.setPermissionMode also accepts plan): the computer refuses every call that would change something, and choosing Plan in the panel also switches the session to the plan agent (Ask and Allow switch back to build; a custom agent the user picked stays). The agent picker lists only the custom agents while the selector shows.
Permissions	chat's approval card, and a Permissions dialog opened from a session's ⋯ menu or from the shield button beside the selector	galopin answers every ask (reject, once or a card); Cerea shows the cards. galopin writes no rules into opencode (ADR 0097). permission.asked becomes the card; Allow once / Always allow (this session) / Deny become permission.reply once / always / reject, for galopin's own gp_ asks and opencode's alike. "Always" adds a per-session exception (the computer answers opencode "once" and stores it itself, scoped by the computer, not by the agent's proposal: an edit's is the file(s) of that ask, exact, so the card says Always allow edits to this file; a command keeps a specific prefix or falls back to the exact command; a path outside the project is its directory; with no concrete scope the answer is once and nothing is stored), and the card offers the button on every card a human answers (the /code transcript, the Needs-you inbox), including a credential ask, which is a card even on Allow: there the reply carries actor: {kind: "user"} and the computer stores the exception marked overAsk, the only kind that holds there, which later matching asks in that session run under (Plan still holds exceptions back). Only the loop brake stays once-only; a local --deny and the computer's own files still refuse, and a reviewer's or rule's answer is never "always". The dialog reads GET v1/agents/:id/permission-rules (permission.rules) itself — the session's Exceptions and its coordination grant — so it can be opened for any session's row, selected or not, and shows the same content while the transcript stays in view: one row per kind of action with what happens and why (computed from the computer's limits, the administrator's rows and the reviewer's availability; no backend rule is listed) and the exceptions as Allowed for this session: … with Remove. DELETE v1/agents/:id/permission-approvals/:id (permission.saved.remove {id, sessionId}) removes one exception, so that command asks again, and can only tighten; it is audited here (session and exception id, never patterns) and on the computer. There is no free-form rules writer. No route reaches the ceiling, the computer's own rules or its policy. A Coordination section in the dialog holds two switches — Can find, read and message other sessions and Can start new sessions — read from permission.rules' coordination field and written by POST v1/agents/:id/coordination {keys} (session.grantCoordination), in the two shapes galopin composes (the message trio together or not at all, the spawn key on its own; [] clears); a partial set is a 400 here, a subagent's id and an unknown key are the computer's 400, and an old galopin is a 404. The grant lands before the session's next turn; a spawned session inherits it. The selector, the shield button, Remove and the switches sit behind the stale-sign-in guard like every other route under /api/v2/code/.
Questions	the SAME card chat's own ask_user_question uses, lifted to the composer	question.asked/question.resolved (opencode's built-in "question" tool, the questions capability), each Question normalized to one select field via AskQuestion.svelte's onanswer prop; POST v1/agents/:id/questions/:requestId translates accept/decline into question.reply answer/reject. Not offered when the backend's capability is false (ACP: always).
Stop	chat's stop button	session.cancel; an abort ends the turn normally, it is not shown as a failure.
Usage and context	a ring in the composer (ContextMeter.svelte)	The usage side channel: a percentage when the model's context window is known, otherwise a token count; "Compact now" calls session.compact. Cost and token counts are not the engine's: galopin's proxy stamps every model request it forwards with the session (x-pystino-tag, the top-level session, so a subagent counts toward its parent; an engine that names no session is attributed to the one session whose turn is running, and to none when several run), Pystino stores the tag on its usage row, and the popup shows the session's cost and tokens (and the latest turn's, from the moment this page saw it start) as metered by the gateway (GET /api/v2/code/agents/:id/usage, asked with the signed-in user's own token, so only their own requests can be read). This is the same for every engine. When the engine reports no context figure the ring shows the gateway's token count instead; with no figures from either side it is hidden. A Pystino older than this change, or a request galopin could not attribute, simply has no figures. A turn's cost is complete once its last request has finished, so it is read again when the turn ends.
Changes	the Changes side pane	session.diff, which asks git for the workspace's uncommitted changes (untracked files included, capped) rather than trusting a backend's own diff, which misses files a shell command wrote. Outside a git work tree the list is the backend's: opencode's own diff, plus galopin's before/after snapshots of the edit tool calls it saw for any file opencode did not list; for an ACP engine (goose, pi) galopin's snapshots are the whole list. A binary or oversize file reads as changed without content, and a credential, .env or galopin-own file is never read (it shows as changed, content not shown).
Subagents	a card at the task call that spawned it, expandable into the child's own transcript	session.children, each child carrying parentToolCallId; children are not listed as sessions of their own. A background child (background:true, unless the computer was enrolled with --no-background-subagents) outlives its parent turn — the strip says so — and its result folds into an automatic marker; a task_id resume reads as a follow-up.
Sessions talking to sessions	"Spawned …" / "Sent to …" / "Read …" cards, linked to the other session	session_spawn / session_send / session_read tool calls (agent-tools). Whether each asks is decided by the computer's own rules for the asking agent (session_spawn / session_send / session_read), or by a grant a schedule gave the session: allow shows an allowed by this computer's rules badge and no card, deny refuses, ask or no rule raises a card. A session started with session_spawn is a delegate of the session that started it: those two read and message each other with no card, and when the delegate finishes a turn its spawner started, galopin puts its final message in the spawner's transcript as a message from that session ("Report from