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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The gateway in its own process (`harness __service gateway`; the core's side is core/gatewayLink.ts):
* the relay, the E2EE sessions and every key this machine holds, where a crash, a hang, a leak or a
* hostile frame costs the remote clients and nothing else (docs/design/2026-10-06-core-boundary-next.md,
* step 10, R2). Network, crypto and WebRTC in pure JavaScript all run here, off the core's event loop.
*
* It does nothing until a core takes its link and says `start`: a core that does not run the gateway out
* of its process (an older one, under a newer master) keeps its own relay, and two links to the backend
* for one machine would fight over its claim. Each `start` builds the gateway afresh (gateway/start.ts),
* and the core going away stops it: a core's restart is the relay's, as it always was, so a remote client
* that kept its socket opens a new session, as it did when both ran in one process.
*/
import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'
import type { ProductUsageMetric } from '../lib/productUsageContract.js'
import type { GatewayAccount, GatewayEvents, WindowRelaySession } from '../core/api.js'
import { localWindowsOf, windowSurfaceOf } from '../lib/windowSurfaces.js'
import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
import { answerTabKey } from '../lib/tabKeyWire.js'
import { answerTabRelay } from '../lib/tabRelayWire.js'
import { accountLink } from '../services/accountLink.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess } from '../services/process.js'
import { startGateway, type StartedGateway } from './start.js'
import { sharedPeers } from './sharedTrust.js'
type Payload = Record<string, unknown>
export interface GatewayServiceOptions {
dataDir: string
socketPath: string
machineId: string
token: string
/** Swapped in tests for one that does not touch the real socket or process. */
run?: typeof runServiceProcess
/** Swapped in tests for a gateway that dials nothing. */
start?: typeof startGateway
}
const text = (value: unknown): string => (typeof value === 'string' ? value : '')
const record = (value: unknown): Payload => (value && typeof value === 'object' && !Array.isArray(value) ? value as Payload : {})
export function runGatewayService(options: GatewayServiceOptions): ServiceProcess {
let core: CoreConnection | null = null
let running: StartedGateway | null = null
/** The windows on the core's side working on other machines through this gateway, by the core's id. */
const windows = new Map<string, WindowRelaySession>()
const notice = (kind: string, payload: Payload = {}): void => { core?.notice?.(kind, payload) }
const events: GatewayEvents = {
frame: (connId, frame, transport, role) => notice('frame', { connId, frame, transport, role }),
binary: (connId, clear) => {
const local = encodeTerminalLocal(clear)
const bytes = local && encodeGatewayBinary(GatewayBinary.remote, connId, local)
if (bytes) core?.sendBinary?.(bytes)
},
client: (connId, client) => notice('client', { connId, client }),
disconnected: (connId) => notice('disconnected', { connId }),
observer: (connId, type, payload) => notice('observer', { connId, type, payload }),
toLocal: (connId, frame) => notice('toLocal', { connId, frame }),
status: (connected) => notice('status', { connected }),
linkDown: () => notice('linkDown'),
commanders: (count, active, recheck) => notice('commanders', { count, active, recheck: recheck === true }),
commanderJoined: () => notice('commanderJoined'),
meta: (meta) => notice('meta', { meta }),
notice: (backendNotice) => notice('notice', { notice: backendNotice }),
revoked: () => notice('revoked'),
busy: () => notice('busy'),
device: (connId, frame, opened) => notice('device', { connId, frame, opened }),
deviceRevoked: (identity) => notice('deviceRevoked', { identity }),
toWindows: (frame) => notice('toWindows', { frame }),
tabFrame: (event) => notice('tabFrame', { event }),
}
/** The account's tokens, from the core (`core.account`, services/accountLink.ts): a refusal comes back as
* the session's own error. */
const { accessToken } = accountLink((query, payload) => (core ? core.query(query, payload) : Promise.reject(new Error('not connected to the core'))))
/** The gateway stopped: its link closed, its windows' sessions let go. Not waited on here: what comes after it
* on the link (a new `start`) must not wait for the old link's goodbye. The process's own stop waits for it. */
let pendingStart: Payload | null = null
const stop = (): Promise<void> => {
pendingStart = null
const was = running
running = null
for (const session of windows.values()) session.detach()
windows.clear()
return was ? was.stop().catch((error: unknown) => console.warn(`[gateway] stopping: ${error instanceof Error ? error.message : String(error)}`)) : Promise.resolve()
}
const begin = (payload: Payload): void => {
void stop()
const started = (options.start ?? startGateway)({
events,
machineId: text(payload.machineId),
computerId: text(payload.computerId),
autonomousEnv: text(payload.autonomousEnv) || 'prod',
signedIn: payload.signedIn === true,
tokens: { accessToken },
machineName: text(payload.machineName), hostname: text(payload.hostname),
machines: (state) => notice('machines', { ...state }),
account: (payload.account as GatewayAccount | null) ?? { machineId: null, signIn: null },
})
running = started
// Held first, so that nothing the link brings in is answered before the core is ready.
if (payload.requestsOpen === false) started.port.holdRequests()
started.port.localClients(localWindowsOf(payload.localClients))
if (Array.isArray(payload.reachable)) started.ops.reachable(payload.reachable as string[])
if (payload.wifiService === true) started.ops.wifiService(true)
if (payload.dial === 'connect') started.port.connect()
else if (payload.dial === 'local') started.port.serveThisComputerOnly()
}
const openWindow = async (payload: Payload): Promise<void> => {
const id = text(payload.id)
const pool = running?.windowRelay
try {
if (!pool) throw new RelayConnectError('the relay is restarting', 1013)
const sink = {
sendFrame: (frame: Payload) => { notice('windowFrame', { id, frame }); return true },
sendBinary: (bytes: Uint8Array) => {
const framed = encodeGatewayBinary(GatewayBinary.window, id, bytes)
return !!framed && !!core?.sendBinary?.(framed)
},
}
const onClosed = (code: number, reason: string): void => {
windows.delete(id)
notice('windowClosed', { id, code, reason })
}
const machineId = text(payload.machineId)
const acquire = typeof payload.share === 'string' ? () => pool.acquireShare(machineId, text(payload.share), sink, onClosed)
: payload.isolated === true ? () => pool.acquireIsolated(machineId, text(payload.autonomousEnv), record(payload.frame), sink, onClosed)
: () => pool.acquire(machineId, text(payload.autonomousEnv), record(payload.frame), sink, onClosed)
const session = await acquire()
windows.set(id, session)
notice('windowOpened', { id })
} catch (error) {
notice('windowFailed', {
id,
...(error instanceof RelayConnectError && error.closeCode ? { code: error.closeCode } : {}),
reason: error instanceof Error ? error.message : 'relay failed',
})
}
}
/**
* What the core tells the gateway (`service_event`). Each is taken as it arrives, in order: the service
* link hands them on without waiting on the last, so nothing here waits either, or a later frame would
* overtake it. What takes time (a window's dial) runs on, and says when it is done.
*/
const onEvent = (payload: Payload): void => {
const kind = text(payload.kind)
// The core says start as it takes the link, a frame before it says `connected`: started then, the first
// dial would ask the core for a token on a link this process does not know is up yet, and wait a second
// to try again. Started once it knows.
if (kind === 'start') { if (core) begin(payload); else pendingStart = payload; return }
if (kind === 'stop') { void stop(); return }
if (kind === 'windowOpen') { void openWindow(payload); return }
const gateway = running
if (!gateway) return
const { port, ops } = gateway
const connId = text(payload.connId)
switch (kind) {
case 'usageLaunch': port.usageLaunch?.(payload.signal as ProductUsageLaunchSignal); return
case 'usageCounter': port.usageCounter?.(payload.metric as ProductUsageMetric); return
case 'connect': port.connect(); return
case 'thisComputerOnly': port.serveThisComputerOnly(); return
case 'hold': port.holdRequests(); return
case 'open': port.openRequests(); return
case 'broadcast': {
// A guest's harness's event goes to the group (which cannot open it) and sealed to that guest's sessions.
const guest = text(payload.guest)
if (guest) port.broadcast(record(payload.frame), guest)
else port.broadcast(record(payload.frame))
return
}
case 'commander': port.commander(record(payload.frame)); return
case 'user': port.user(record(payload.frame)); return
case 'reply': port.reply(connId, text(payload.type), payload.requestId, record(payload.payload)); return
case 'target': port.target(connId, text(payload.type), record(payload.payload)); return
case 'terminal': port.terminal(connId, text(payload.type), record(payload.payload)); return
case 'observer': port.observer(connId, text(payload.type), record(payload.payload)); return
case 'windowOpened': port.windowOpened(windowSurfaceOf(payload.surface)); return
case 'localClients': port.localClients(localWindowsOf(payload.windows)); return
case 'localFrame': void port.local(connId, record(payload.frame)); return
case 'device': port.device(connId, text(payload.type), record(payload.payload)); return
case 'deviceClient': port.deviceClient(connId, typeof payload.identity === 'string' ? payload.identity : null); return
case 'wifiService': ops.wifiService(payload.on === true); return
case 'revokeIdentity': ops.revokeIdentity(text(payload.identity)); return
case 'account': ops.account(payload.account as GatewayAccount); return
case 'reachable': ops.reachable(Array.isArray(payload.machineIds) ? payload.machineIds as string[] : null); return
case 'windowSend': void windows.get(text(payload.id))?.send(record(payload.frame)); return
case 'windowDetach': { const id = text(payload.id); windows.get(id)?.detach(); windows.delete(id); return }
case 'windowInvalidate':
if (payload.isolated === true) gateway.windowRelay.invalidateIsolated(text(payload.machineId))
else gateway.windowRelay.invalidate(text(payload.machineId))
return
default:
console.warn(`[gateway] an unknown event from the core was ignored: ${JSON.stringify(kind).slice(0, 80)}`)
}
}
/** The core's terminal bytes for a remote client, or for a window's session on another machine. */
const onBinary = (raw: Uint8Array): void => {
const decoded = decodeGatewayBinary(raw)
const clear = decoded && decodeTerminalLocal(decoded.bytes)
if (!decoded || !clear) return
if (decoded.kind === GatewayBinary.window) void windows.get(decoded.id)?.sendBinary(clear)
else running?.port.terminalBinary(decoded.id, clear)
}
/** The core's commands about the keys (`GatewayOps`), answered as their routes answer them. */
const ops = () => {
if (!running) throw new Error('the gateway has not started')
return running.ops
}
const requests = {
[GATEWAY_CALLS.backend]: async (p: Payload) => ({ ...await ops().backend(text(p.method), text(p.path), p.body) }),
[GATEWAY_CALLS.machines]: async (p: Payload) => ({ ...await ops().machines(p.fallback === true) }),
[GATEWAY_CALLS.mintGridName]: async () => ({ name: await ops().mintGridName() }),
[GATEWAY_CALLS.status]: async () => ({ ...await ops().status() }),
[GATEWAY_CALLS.pair]: async (p: Payload) => ({ ...await ops().pair(text(p.code)) }),
[GATEWAY_CALLS.listPairs]: async () => ({ ...await ops().listPairs() }),
[GATEWAY_CALLS.revoke]: async (p: Payload) => ({ ...await ops().revoke(text(p.id)) }),
[GATEWAY_CALLS.revokeAll]: async () => ({ ...await ops().revokeAll() }),
[GATEWAY_CALLS.setRemotePassword]: async (p: Payload) => ({ ...await ops().setRemotePassword(text(p.password)) }),
[GATEWAY_CALLS.clearRemotePassword]: async () => ({ ...await ops().clearRemotePassword() }),
[GATEWAY_CALLS.remotePasswordStatus]: async () => ({ ...await ops().remotePasswordStatus() }),
[GATEWAY_CALLS.trustLinkedPeer]: async (p: Payload) => ({ ...await ops().trustLinkedPeer(record(p.peer) as { pub: string; machineId: string; label: string }) }),
[GATEWAY_CALLS.groupList]: async () => ({ ...await ops().groupList() }),
[GATEWAY_CALLS.groupSync]: async () => ({ ...await ops().groupSync() }),
[GATEWAY_CALLS.groupRemove]: async (p: Payload) => ({ ...await ops().groupRemove(text(p.selector)) }),
[GATEWAY_CALLS.devicesList]: async () => ({ ...await ops().devicesList() }),
[GATEWAY_CALLS.devicesRemove]: async (p: Payload) => ({ ...await ops().devicesRemove(text(p.pub)) }),
[GATEWAY_CALLS.devicesHistory]: async () => ({ ...await ops().devicesHistory() }),
[GATEWAY_CALLS.devicesDismiss]: async (p: Payload) => ({ ...await ops().devicesDismiss(record(p.body)) }),
[GATEWAY_CALLS.devicesRebaseline]: async (p: Payload) => ({
...await ops().devicesRebaseline(p.confirm === true, p.head as { seq: number; hash: string } | undefined),
}),
[GATEWAY_CALLS.wifi]: async (p: Payload) => ({
...await ops().wifi({ op: text(p.op) as 'discover' | 'pair' | 'pairStatus' | 'list' | 'revoke', device: text(p.device), code: text(p.code), id: text(p.id) }),
}),
// The fleet's lane's sessions (gateway/lane.ts). Each is answered from what it holds at once, so they
// are taken in the order the core sent them.
[GATEWAY_CALLS.lane]: async (p: Payload): Promise<Payload> => {
const lane = ops().lane
const machineId = text(p.machineId)
switch (p.op) {
case 'hello': return { frame: await lane.hello(machineId, text(p.peerPub)) }
case 'welcome': return { ok: await lane.welcome(machineId, record(p.payload)) }
case 'rekey': await lane.rekey(machineId, record(p.payload)); return {}
case 'seal': return { ...await lane.seal(machineId, record(p.frame)) }
case 'open': return { ...await lane.open(machineId, record(p.frame)) }
case 'drop': lane.drop(machineId); return {}
default: return { error: 'UNKNOWN_OP' }
}
},
// Share's owner's key (gateway/observerKey.ts): its public half, or a welcome signed.
[GATEWAY_CALLS.observerKey]: async (p: Payload): Promise<Payload> => {
const key = ops().observerKey
try {
if (p.op === 'public') return { key: await key.publicKey() }
return { key: await key.signWelcome(text(p.machineId), text(p.shareId), text(p.peer), text(p.ephemeral)) }
} catch (error) {
return { error: error instanceof Error ? error.message : String(error) }
}
},
// Shared tabs' keys (gateway/tabKey.ts): one of the nine `TabKey` methods, answered `{ result }` or `{ error }`,
// and `UNKNOWN_METHOD` for any other name (lib/tabKeyWire.ts). Taken in the order the core sent them, as the lane's.
[GATEWAY_CALLS.tabKey]: (p: Payload): Promise<Payload> => answerTabKey(ops().tabKey, p),
// Shared tabs' relay (gateway/tabRelay.ts): `open`, `send` or `close`, and `UNKNOWN_METHOD` for any other name
// (lib/tabRelayWire.ts).
[GATEWAY_CALLS.tabRelay]: (p: Payload): Promise<Payload> => answerTabRelay(ops().tabRelay, p),
// Machines shared across accounts (gateway/sharedTrust.ts): the stores made to hold what was asked.
[GATEWAY_CALLS.sharedTrust]: async (p: Payload): Promise<Payload> => {
try {
return { ...await ops().sharedTrust({ ...(p.pins !== undefined ? { pins: sharedPeers(p.pins) } : {}), ...(p.keys !== undefined ? { keys: sharedPeers(p.keys) } : {}) }) }
} catch (error) {
return { error: error instanceof Error ? error.message : String(error) }
}
},
// The account's connected services (lib/e2ee/connectorVault.ts): an envelope sealed, or one opened.
[GATEWAY_CALLS.connectorVault]: async (p: Payload): Promise<Payload> => {
const vault = ops().connectorVault
try {
if (p.op === 'seal') return { envelope: await vault.seal(text(p.plaintext)) }
if (p.op === 'open') { const opened = await vault.open(p.envelope); return opened === null ? {} : { ...opened } }
return { error: 'UNKNOWN_OP' }
} catch (error) {
return { error: error instanceof Error ? error.message : String(error) }
}
},
}
const service = (options.run ?? runServiceProcess)({
name: 'gateway',
socketPath: options.socketPath,
machineId: options.machineId,
token: options.token,
requests,
onEvent,
onBinary,
onConnected: (connection) => {
core = connection
const start = pendingStart
pendingStart = null
if (start) begin(start)
},
onDisconnected: () => {
core = null
void stop()
},
})
return {
// The process is going (the master's SIGTERM, the master gone, services/process.ts `leave`): the gateway and its
// usage collector stop first, while the link is still up, and the process waits for them. Closing the link alone
// left them to its close event, which the exit came before: the collector never wrote its clean exit, and
// `harness stop`, updates, sign-in restarts, service installs and OS logouts all counted as unclean restarts
// (health_cli_unclean_restart, 69 to 170 on 2026-10-16, production counters).
stop: async () => {
const stopping = stop()
await service.stop()
await stopping
},
}
}