The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
Services
A service is a feature the core can run without. It may fail; the core may not. These rules are what let several people build features at once without touching the core or each other.
Adding a service
- Write
start<Name>(core: CoreApi, ports: CorePorts)insrc/services/<name>.ts. Read the core only throughcore(src/core/api.ts). IfCoreApilacks something you need, add it toCoreApiin a separate, reviewed change; never import a core module, the registry,cli.tsorbackendSocket.ts. - If the apps call it, declare its requests and answer them from start. Declare the frame types in
src/core/api.ts,export const <NAME>_REQUESTS = ['<name>_list', …] as const, re-export them from your module, and return their handlers from start:{ <name>_list: (payload, asker) => reply }. The core routes them from that list alone, so a service in its own process is never loaded into the core's to learn them. A handler returns the reply (or a promise of it); the core routes the request to it, replies under the asker's request id, and never waits in line for it. Never add a case tobackendSocket.ts's switch or a slot toBackendSocket.- Trust
asker, never the payload:if (!asker.owner) return { error: 'OWNER_REQUIRED' }. - While the service is off, its requests are answered
SERVICE_UNAVAILABLE, neverUNSUPPORTED(the apps read that as "update the CLI"). That is why the types are declared up front. - A handler that throws or rejects is answered
SERVICE_FAILEDand counts against the service. - Work that belongs to the connection that asked (a limit on how many at once per connection, work to
stop when the asker goes) is keyed by
asker.connectionand stops onclosed, the handler's third argument: it is aborted when that connection closes, or when the core that routed it goes, wherever the service runs (serviceHost.closeConnection,serviceLinks.closeConnection,process.ts). A request held while an experiment's process starts is never sent once its connection has closed.
- Trust
- If the core must call the service, give it a port. Add
<Name>Portand its fallbacks (<NAME>_FALLBACKS) tosrc/core/api.ts. A fallback is what the core does while the service is off or failing:undefinedfor nothing, a value, orFAILto answer that one requestSERVICE_UNAVAILABLE. The core only ever calls the port, never the service. Most features need no port: only the apps call them. - Start it in
src/core/main.tsthrough the host, never directly:serviceHost.serve('<name>', start<Name>, coreApi, <NAME>_REQUESTS)for a service with no port, orserviceHost.start('<name>', start<Name>, coreApi, <NAME>_FALLBACKS, <NAME>_REQUESTS)for one with a port. The host leaves a service off when its start throws, guards every call and request, and switches it off after five failures in a minute. - Test it to 100% with
fakeCore()(src/testing/fakeCore.ts);npm run test:corecovers this folder. Prove failure isolation end to end withHARNESSD_TEST_FAULTS=<name>(its start fails),<name>.<member>(one port call fails) and<name>.<request type>(one request fails); seee2e/services.e2e.ts. The same names work in a service's own process, where<name>.<event kind>fails an event;<name>.crashand<name>.leakexist only there (src/services/process.ts).
store.ts (the Harness Store: no port, four requests) is the example to copy for a feature;
search.ts for a service the core also calls.
Running in its own process
A service that can crash natively, hang or leak should run in a process of its own, where it costs only
that process. A process per risk, not per feature (SERVICE_HOSTS in src/harnessd/services.ts):
| Process | Services | Why its own | Started |
|---|---|---|---|
engine-claude, engine-codex |
history, live parsers, runtime profiles, screens, submission readings, model control, question navigation and Codex's app-server connection (src/engines/worker/) |
engine behavior outside core; snapshots and revocable model- and question-control grants | on demand |
search |
search | native node:sqlite, the index's memory |
always |
viewers |
viewers, store | the viewer servers, the remote viewer streams and rendered surfaces, minutes-long installs | on demand |
edge |
workspaces, usage, monitor, projects, handoff, recaps, windowNames, shell, connectors, sharedMachines, agentCleanup, messages, osDevice | light pure-JS services: isolated from the core, not from each other | always |
gateway |
gateway | network, crypto and pure-JS WebRTC: the attack surface | on demand |
models |
models | grid's installs, downloads and commands | on demand |
devices |
devices, wifi | the dials' serial ports, the fleet's lane, the voice router's worker, the Wi-Fi device | on demand |
orchestrator |
orchestrator | an experiment | on demand |
sharing |
sharing | an experiment: Share | on demand |
memory |
memory | an experiment: Memories across machines | on demand |
router |
router | an experiment: where ⌘B sends a task, decided by Jev | on demand |
cloud |
cloud | an experiment: cloud agents (Fo, Devin Cloud, Cursor Cloud), harnesses on their makers' servers | on demand |
A fault in one of the edge host's services can cost the others in it, never the core. Every service in
KNOWN_SERVICES runs out of the core's process by default, unless HARNESSD_SERVICES names a subset, by
service (search,usage) or by process (edge). HARNESSD_SERVICES=none runs them all inside the core's
process (for debugging or a quick way back). The shell service runs in the edge host too.
The updater is not in SERVICE_HOSTS: the core neither routes to it nor runs it, and HARNESSD_SERVICES does
not turn it off. The master runs it (UPDATER_HOST, src/services/updaterProcess.ts) for the installed copy,
with updates on. It stages a new build and tells the master, which has the core hand over. A core under a
master too old to run it starts it beside itself, still in its own process (src/core/updaterBeside.ts).
src/harnessd/services.tsruns it (SERVICE_HOSTS: each process, the services it hosts and its memory budget, one heartbeat for all of them). The core routes the requests it declared (its<NAME>_REQUESTS) to its process, and the same handlers answer them there.src/serviceProcess.tsstarts it (SERVICE_RUNNERS, which must name every service inKNOWN_SERVICES): a process imports only the runners it is named (__service workspaces,usage), and a service whose start throws there is left off while the others in its process run. The core's in-process starts are ininline.ts, which the core loads only when a service runs in its process: a service in its own leaves the core's import closure (src/architecture.spec.ts). From a release, it runs on the lean bundle cli.js carries for the master and the services, built apart from the core's own entry (src/harnessd/leanBundle.ts,src/leanCoreEntry.ts), split so that a service loads its own code and nothing else: 61 to 77 MiB resident at idle (20 to 35 MiB physical footprint), against 118 to 131 (54 to 90) when each started on cli.js (2026-10-05). It is only an optimisation: the master starts a service from cli.js whenever the lean bundle cannot be used (src/harnessd/leanServices.ts), and the release script refuses one that does not load (scripts/check-lean-bundle.mjs).- What a service imports is what its process costs. Import from small modules: one schema module
pulled in for a constant brought zod to search and workspaces, 8 MiB each (
src/dsh/id.ts). A failing import fails the service's start, loudly, and the master parks it.src/leanEntry.spec.tsholds each process to its own code, and the master, search, the updater and the edge host to no zod. It also keeps the nativenode:sqlitebinding out of the edge host until a service there reads a store that opencode, kilo, hermes or devin keeps a conversation in.lib/sqliteRead.tsimports the binding (lib/sqliteBuiltin.ts) only at the first read, so importsqliteReadAlland never the binding itself. src/services/process.tsis the process's side:hostServicesbeats to the master and stops every service before the process exits;runServiceProcessis each service's own connection to the core, with the master's token, reconnecting after core restarts.<host>.crashand<host>.leak, or a service's own, crash or leak the whole process: it is one process.src/core/serviceLinks.tsis the core's side: it routes those requests to the process, answersSERVICE_UNAVAILABLEwhile it is down, and holds what the service must not miss. The Store's requests (waitsThroughRestart) wait for its process to come back instead, bounded as a first start's wait is.src/services/searchProcess.tsis the example to copy.e2e/serviceProcesses.e2e.tsis the proof to copy: killed, hung (SIGSTOP), leaking, crashing on every start.- A port the core calls asynchronously, answered when it is read, can be a request to the process: the
monitor shows how (
src/services/monitorProcess.ts,src/core/monitorLink.ts). The core asks withserviceLinks.call, under types only it sends (the port's member names, so a test's fault names the same member either way), and reads an answer that does not come as the port's fallbacks. A light service that reads the agents asks for them as each request starts (service_query liveoradvertised,src/core/agentQueries.ts;src/services/processCoreApi.ts). The change-agent handoff asks for each conversation fact as it needs it (core.conversations,src/core/conversationQueries.ts,src/services/handoffProcess.ts) and keeps no copy of the registry. - A port the core calls in line (while it builds a frame, say) cannot wait on another process. The
viewers show how (
src/services/viewersProcess.ts,src/core/viewersLink.ts): the process tells the core its answers whenever they change (aservice_querykind the core answers), the core keeps the last ones and its port answers from them, or from the fallbacks before it has heard any. The process asks the core for everything it should hold each time it connects, which a restarted process needs anyway.e2e/viewersProcess.e2e.tsproves it with a real harness agent's viewer. - Both at once, and a service that asks the core for what only the core holds: models
(
src/services/modelsProcess.ts,src/core/modelsLink.ts). What a frame and a keystroke read (an agent's grid note, whether its grid sleeps) is told to the core as a glance at every grid whenever it changes; grid's set-up and where an agent on a grid model sends its inference are asked when needed, each with a wait long enough for what it does (LONG_ANSWERSinsrc/core/api.ts: the half minute any other answer gets would cut a grid install short). Models asks the core for the sign-in each time it needs it, and work that belongs to one connection's request (a Grid harness's command) is keyed by the connection and request id the core gives every request (Asker).e2e/serviceProcesses.e2e.tsproves it: a create on a grid model while models is killed answers GRID_UNAVAILABLE, and every agent works on. - A service the core only gives commands to needs nothing kept for it while it is down. Workspaces
(
src/services/workspacesProcess.ts,src/core/workspacesLink.ts) is told to name branches and when to sweep. A command that destroys something is never held or replayed, and what it must know (the folders in use) is asked for when it starts, never sent ahead where it could go stale.e2e/workspacesProcess.e2e.tsproves it. - A service that is transport rather than requests: the gateway (src/gateway/gatewayProcess.ts,
src/core/gatewayLink.ts) carries every remote client's traffic, so it tells the core without asking
(
service_notice) and carries terminal bytes as binary frames on its link. The core drops what would pile up on a gateway that reads nothing, and the gateway gone is the relay gone: every remote client with it, never a window on this computer.e2e/gatewayProcess.e2e.tsproves it, with a phone. - The shell service (
shellProcess.ts) owns validation, setup replies and durable creation receipts in the edge host. It asks the core to launch literal argv or read live terminal identity throughcore.terminals(core/shellQueries.ts). A lost launch reply leaves an unconfirmed receipt and is never retried as a new launch.e2e/shell.e2e.tskeeps an attached terminal working across an edge crash. - The gateway owns account/backend HTTP and the single writer of
machines.json(gateway/accountHttp.ts). The core retains its reported list for stale replies during a restart, bound to the current account. The Store prepares bundled harnesses before reportingprepared; package agents wait held until preparation is available, after the core reports ready. The lean bundle shares one asset file, loaded by the Store and never by the core. - A service that writes turns into agents (Agent Messages' typed messages, the orchestrator's guidance) delivers
each under an id of its own through
core.turns.deliver, hears what became of it throughonDelivery, and takes one back withcancelDelivery(core/deliveries.ts). In its own processservices/turnsLink.tsasks the core over its link, in order, and hears only its own deliveries; the core lets a process deliver only whenTURN_DELIVERERS(src/core/api.ts) names it: the experiments (below) and Agent Messages. - A service that graduates from an experiment keeps the same questions to the core and is answered by a link of its
own, for what it uses alone, never by the experiments' hooks: Agent Messages in the edge host
(
src/core/messagesLink.ts,MESSAGES_QUERIESinsrc/core/api.ts) is shown the agents, told how this daemon is reached and whether it is signed in, calls the backend only throughMESSAGES_BACKEND_ROUTES(the account's tabs, and shared tabs' shares, rosters, invitations, members and moves), sends the windows its log's change notice and nothing else, and hearsdesk_changedandmachines_changed. It holds no credential: the core signs each backend call, and the gateway signs and seals shared tabs' rosters and frames (core.account.tabKey, asked astab_key) and holds their sockets (tab_relay).accountreads the account signed in here, andobserverstells the core that a roster changed, which it hands to Share, so that a removed member stops watching at once. A core from beforeaccountanswersUNKNOWN_QUERY, and shared tabs are then unavailable while the rest runs. Between the owner's computers it answerstab_pub,tab_pin,tab_pin_changedandtab_keychange(src/messages/service.ts), only from another computer of the same account. It never creates an agent, stops a turn or watches a terminal. Off for the account (Settings ▸ Experimental, off by default), or signed out, it runs no timer: the core wakes it when its copy of the switch changes (MessagesPort.settingsChanged, fromcreateAgentSettingsSyncinsrc/core/experiments.ts), so does a watch on the setting's file when there is one (src/messages/settingWatch.ts), and so does a core it reconnects to signed in. - A service that drives hardware: the devices (src/services/devicesProcess.ts, src/core/devicesLink.ts).
The dial reads a dozen facts in line while it builds each frame, so the process keeps a copy of what it
reads (this computer's agents, its name, the sign-in, whether a window is there), asked of the core as
the dial's tick or ⌘K builds a list; the core keeps what the windows said and says it again each time
the process connects, and a dial attaching is shown the open questions and the working tiles. Inside,
one device failing is that device's alone: its session's faults and a flood on its port drop it, and
its port is looked at again later (src/cable/cableFleet.ts).
e2e/devicesProcess.e2e.tsproves it, with fake dials on pseudo-terminals. The Wi-Fi device runs beside them on a link of its own (src/services/wifiProcess.ts, src/core/wifiLink.ts): its sessions are the gateway's, so the core hands their requests on in order and checks where each answer goes, and keeps what it reads in line of the service (who said hello, which transcripts and streams it follows, the focus revision) from what the service tells it (src/core/wifi.ts).e2e/wifiDevice.e2e.tsproves it, with a fake device on the relay. Their process runs only once there is a device (onDemand, asked for since protocol 4): a dial's port in /dev, a paired Wi-Fi device or its session, or a request for them (src/core/devicesWake.ts); what a Wi-Fi device sends while it starts is held by the core.e2e/devicesOnDemand.e2e.tsproves it. - A service the core tells what happens and never waits on: the recaps (
src/services/recapsProcess.ts,src/core/recapsLink.ts) hear each turn's lifecycle as a notification, and one they miss costs that turn its recap, nothing else; what would pile up on a hung process is dropped. What they put in front of a person goes back as a notice the core checks the type of (clients.turnCard,turnSummary), and what the core reads back in line it reads from what they last said of each session.e2e/recapsProcess.e2e.tsproves turns end on time with them killed, hung or slow, ande2e/recapsCompat.e2e.tsthat the dial and the windows hear the same cards and recaps as before. The agent cleanup (src/services/agentCleanupProcess.ts,src/core/agentCleanupLink.ts) is told the same way (a harness stopped, the person typing into one another agent started), and acts on the core only through what the core lets it:closeStartedcloses a harness another agent started and refuses any other.
On demand
A process with onDemand: true in SERVICE_HOSTS is not started with the others. The master starts it when
the core asks for one of its services (harnessd:want, sent by coreLink.want), and then keeps it running
like any other. Named in HARNESSD_SERVICES, it starts with the others.
- What asks. A request for a service that has not connected yet (
serviceLinksonDemand, insrc/core/main.ts) asks for it and waits for it, within the request's own wait. The service is welcomed before its queued requests are delivered. Each experiment with saved state in the data folder is asked for as the core starts (src/core/experiments.ts). So is Agent Messages, which starts nothing under this build's master (it is in the edge host) and starts its own process under a master from before it moved there (src/core/messagesLink.ts). The devices are asked for once there is a device: a dial's port in /dev, a paired Wi-Fi device, or its session (src/core/devicesWake.ts). Models is asked for as the core starts when grid is in use here: a managed grid, whose pin it follows, saved grid pictures, which agents' grid notes are read from, or local models (src/core/modelsWake.ts); otherwise its first request asks for it. The gateway is asked for as the core starts, before it binds, when this machine is signed in or has anything paired or linked directly (src/core/gatewayWake.ts), so the relay comes up beside the core as before; otherwise by what needs it (src/core/gatewayLink.ts): a pairing, a window's E2EE request or session to another machine, which wait for its first start, a key or device command, or the Wi-Fi device's service./api/statusnever starts it. The viewers' process (the viewers and the Store) is asked for by a harness here, as the core starts or as one is attached (created, forked, restored, found), by a request (the Store's, a harness's create or restore, a client's viewer stream or rendered frame, which wait for it), and as the core starts when the release's own harnesses are not in the installed index as this build ships them (src/dsh/builtinIds.tsbundledRevisions) or the viewers' ledger names viewer servers an earlier process left running (src/core/viewersWake.ts). A stream before it has first connected is held, bounded, until it does (src/core/viewersLink.ts). - Older cores.
askedSinceis the core protocol (HARNESSD_PROTOCOL,src/harnessd/protocol.ts) from which a core asks for this process. A core that speaks an older one never asks, so the master starts the process as that core binds (ServiceSupervisor.unasked). It is 3 by default, the experiments'; the devices, models and the gateway became on demand at protocol 4, which may also ask before it binds; the viewers at protocol 5. Making another process on demand needs a protocol bump, and that number in itsaskedSince. A newer core under an older master asks for a process that master started with the others, which changes nothing. - Proof.
e2e/experiments.e2e.ts,e2e/devicesOnDemand.e2e.ts,e2e/modelsOnDemand.e2e.ts,e2e/gatewayOnDemand.e2e.tsande2e/viewersOnDemand.e2e.ts: off, it has no process; asked for, it starts and answers.
Experiments
An experiment (the orchestrator, Share, memory, the router, cloud agents) is a service that costs nothing until it is
on: its own process, which the master starts only when the core asks for it (want), when one of its requests arrives
or, as the core starts, when its saved state is in the data folder. Off, nothing of it runs or is loaded anywhere; one
failing costs its own process and nothing else. e2e/experiments.e2e.ts proves it: off, on by request, on by saved
state, killed, hung and crashing on every start.
Agent Messages was one until 2026-10-12: a process of its own on every computer it was on, 62 MiB resident at idle for a few MiB of messaging. It is a service in the edge host now (above), off costing nothing there.
To add one:
- Its service,
start<Name>(core, ports)insrc/services/<name>.ts, returning its requests' handlers, and its process's runner (src/services/<name>Process.ts,run<Name>Service; copysrc/services/orchestratorProcess.ts). ItsCoreApiin its process isprocessCoreApiwithask, which gives it what an experiment acts on the core through (src/core/experimentQueries.ts): the agents as the apps are shown them, creating an agent, stopping a turn, delivering turns (services/turnsLink.ts), a change notice for the windows (<name>_changed) and how an agent's shell reaches this daemon; Share also reads the backend as the account (core.account.backend) and has its welcomes signed by the gateway (core.account.observerKey), so it holds no credential, and watches terminals read-only (core.terminals.watch,services/watchLink.ts). - Its entry in
EXPERIMENTS(src/core/api.ts): its requests and its saved state. - Its process in
SERVICE_HOSTS(src/harnessd/services.ts) withonDemand: true, and its runner inSERVICE_RUNNERS(src/serviceProcess.ts). - Its start for the core's own process, in
services/inline.ts, and one line incore/main.tsthat starts it there whenHARNESSD_SERVICESkeeps it in (serviceHost.serve, orstartwith a port).
Removing one is deleting those. Cloud agents (src/services/cloud.ts, src/cloud/) show an experiment that owns
agents with no pane: it tells the core its harnesses and their questions through core.cloud (asked over its link
out of process, core/experimentQueries.ts), and the core lists them, shows their questions and hands a New Harness,
words, an answer, a rename and Stop Harness for one to its port (core/agents/cloud.ts, core/cloudLink.ts). A port member is
never called stop: the service host reads that as stopping the service. A port the core calls in line (the orchestrator's roleOf) is answered
from what the process last reported (src/core/orchestratorLink.ts), as the viewers' are. Agent Messages
(src/services/messages.ts) shows the rest: whether one of its typed deliveries may still be written, which
the core asks as it writes it, is reported for a few seconds at a time, so a process that stops reporting
leaves none writable (messagesProcess.ts, core/messagesLink.ts).
Graduating one to a service is moving it into a host that is always running (SERVICE_HOSTS), taking it out of
EXPERIMENTS and answering what it asks with a link of its own, as Agent Messages did. Where it runs is the master's
to say, by service name (serviceProcessesEnv), so a core of either build routes it to the one process that runs it
and runs none of it itself; the new core still asks for it as it starts, which starts its old process under a master
from before (src/harnessd/services.spec.ts, e2e/messagesSkew.e2e.ts).
Do not
- Do not keep state the core needs. If the core would break without your data, it is not a service.
- Do not hold credentials. Ask
core.account: a token (accessToken, with one forced refresh after a- or, to seal for one of the owner's other machines, the gateway's session with it (
lane, as the fleet's lane does:src/device/deviceLink.ts). This machine's E2EE identity is the gateway's alone.
- or, to seal for one of the owner's other machines, the gateway's session with it (
- Do not write to tmux, the registry or another service's files.