How to mirror a surface over ssh
An agent serves its surface on the machine it runs on, where a browser cannot reach it. This guide fronts that remote surface with a local mirror: you dial the host, keep a live local copy of everything it serves, and re-serve that copy to browsers.
The browser only ever talks to the local copy. The ssh pipe swaps behind it.
implementSurface, and ③ re-serves that copy to the browser. The browser only ever talks to the local copy — only the ssh pipe behind it swaps.You need the remote agent’s defineSurface(…) contract and its binary’s .drv
(a Nix derivation).
1. Dial the host
A session over ssh is makeSession (the
transport-agnostic reconnect loop) plugged with sshConnector (the ssh
transport). You own the session: key your own map and tear it down yourself.
There is no shared pool.
// `AgentClient` is the structural member face — there is no contract type to be
// generic over. The connector takes the SURFACE as a VALUE: Effect RPC builds
// its client from `surface.group`, and the face is re-nested from
// `surface.spec` — neither is recoverable from a type alone, and passing the
// surface is what makes the dialled face and the served group provably the same
// tag set.
const session: Session<AgentClient, SshProv> = makeSession({
initialConnection: "probing", // an ssh session provisions before it connects
connectOnce: sshConnector({
surface: base,
host: "[email protected]", // any ssh target; "localhost" short-circuits
binary: "my-agent", // exe name inside the realised closure
// Policy-free: YOU (the consumer) compose the localhost arm's spawn env, keeping only
// the keys that are SET (an empty HOME/PATH would misdirect lookups). kolu uses
// kolu-pty's `composeSpawnEnv`. Never the caller's ambient `process.env`; unused for ssh.
localEnv: Object.fromEntries(
(["HOME", "PATH"] as const)
.map((k): [string, string | undefined] => [k, process.env[k]])
.filter((e): e is [string, string] => e[1] !== undefined),
),
resolveDrvPath: () => resolveDrv("bob.example"), // deferred — see the caution
}),
});
2. Pump its frames inward
Implement the mirror surface locally, then run pumpRemoteSurface to fold the
agent’s frames into it. A standalone re-serve serves the agent’s base surface
verbatim.
// Re-serve the agent's base surface verbatim. (SR9: per-host connection health is a
// host-map concept — a `@kolu/surface-map` map's `entries` channel carries the fine
// connection payload, produced by `serveHostMap`; a standalone re-serve like this
// carries no `connection` cell.)
const source = base;
const runtime = implementSurface(source, {
cells: { load: { store: loadStore } },
collections: {
processes: {
readAll: () => processes,
upsert: (k, v) => {
processes.set(k, v);
},
remove: (k) => {
processes.delete(k);
},
},
},
});
// The pump mirrors whatever client the session produces; it holds nothing
// open. A mirror that wants its link up regardless pins the session itself.
void session.pin();
void pumpRemoteSurface({
source,
session,
makeSink: ({ seq: _seq }) => ({
// built per spawn — per-client state resets
cells: { load: (v) => runtime.ctx.cells.load.set(v) },
collections: {
processes: {
upsert: (k, v) => runtime.ctx.collections.processes.upsert(k, v),
remove: (k) => runtime.ctx.collections.processes.remove(k),
},
},
}),
});
makeSink is a factory: it takes { seq } (the spawn counter, not a client),
and the pump rebuilds it on every spawn. No per-client fold survives a
reconnect.
3. Re-serve the same surface locally
The mirror runtime hands you { group, handlers }, the pair any transport
takes. A directDispatch over the runtime is the in-process consumer. A browser
reaches the same pair over a WebSocket, with the app layer’s
acceptSurfaceSocket gating each upgrade and serveSurfaceSocket serving it
(see @kolu/surface-app). The browser consumes the
local copy exactly as if the agent were in-process.
// The mirror runtime's `{ group, handlers }` is what any transport takes; a
// browser consumes the local copy exactly as if the agent were in-process.
const dispatch = directDispatch(runtime);
Package steps 2 and 3 with reServeSurface
For the production path, reServeSurface({ source, policy, session }) wires the
pump and the re-serve for one binding and returns
{ surface, group, handlers, done, close }.
donesettles when the pump exits, and rejects on an unrecoverable fault.close()stops the binding. It aborts the pump without destroying the caller-owned session, and releases the internal runtime’s owned sources. Calling it again does nothing.policymarks each membervalueordelta. Avaluemember is held open and replayed across an upstream drop. Adeltamember (a byte or liveness stream) fails through, so the client re-subscribes end to end and a snapshot only ever leads a fresh stream.
The binding is demand-gated. It pins the session when its first downstream subscriber arrives, and releases it after a short grace when the last one leaves, so nothing is dialled while nobody is reading. Pin the session yourself if you want the link up regardless, for example when you display the link’s own state.
Where connection health comes from
Connection health is state the remote agent cannot report, because it cannot
observe the link to itself. When you serve many hosts as a host map
(serve a map), that health rides each entry as a fine
connection payload. serveHostMap produces the coarse dot and the fine word
from the same session frame in one projection (see
@kolu/surface-remote).
A standalone re-serve like the one above carries no per-host connection state. For the model behind this pump, see The server half.