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
/**
* Sharing a whole machine with other accounts (docs/plans/2026-10-15-share-machine-plan.md), in the edge
* host. Off by default.
*
* `shared_machines` takes `{action}`:
* - `get`: this machine's sharing, `{emails, sameDomain, domain, members}`. `domain` is the owner's, null
* at a public one (gmail.com, …), where "everyone at" is never offered; `members` are who use it now.
* - `set` {emails, sameDomain}: share this machine with these addresses and, or, everyone at the domain.
* Empty and false is "not shared".
* - `add` {machineId}: add a machine shared with this account's domain to its machines; `remove` takes it
* back out.
* - `enable_guests`: turn guest access on (the helper, behind one admin prompt on this computer).
* - `set_folders` {folders: [{path, write}]}: the owner's folders every guest may work in, read or read-write.
* Owner only, like every request that changes this machine. `guest_folders` is a guest's: where it may start a
* harness, its own workspace and the folders shared with it (docs/plans/2026-10-19-guest-machine-sharing-plan.md).
*
* The policy is kept here, on the machine (`shared-machines.json`), and published to the backend, which
* lists the machine to the people it names and lets their relay sessions through. Whom to trust is still
* this machine's to decide: it reads who uses it from the backend, keeps those its own policy names, and
* has the gateway trust their machines' keys (gateway/sharedTrust.ts), as Share's owner keeps its grants.
* The other half is for the machines shared with this account: their keys are pinned, so a window here
* reaches them as it reaches the account's own.
*
* Read again as it starts, when the backend says the machines changed (someone added this machine, the
* sharing of one shared with this account changed), after each change made here, and every few minutes
* while anything is shared either way.
*/
import { homedir } from 'node:os'
import { isAbsolute, join, parse, resolve, sep, win32 } from 'node:path'
import { readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
import type { CoreApi, CorePorts, GuestLaunchInput, ServiceRequests } from '../core/api.js'
import { createGuestAccounts, guestHomeRoot, guestWorkspaceFor, type SharedFolder } from '../lib/guestAccounts.js'
import { guestHelperStatus, installGuestHelper, type GuestHelperInstallResult, type GuestHelperState } from '../lib/guestHelperInstall.js'
import { createWindowsGuestAccounts } from '../lib/windows/windowsGuestAccounts.js'
import { failed, type PortFailure, type ShareMember, type SharedMachinesPort, type SharePolicy,
type SharedTrustPeer } from '../lib/sharedMachinesPort.js'
import { createGuestLaunches, type GuestLaunches } from './guestLaunches.js'
/** The request shared machines answers for the apps, declared in core/api.ts for the core to route. */
export { SHARED_MACHINES_REQUESTS } from '../core/api.js'
/** The most addresses one machine is shared with (the backend's `SHARE_EMAILS_MAX`). */
export const SHARE_EMAILS_MAX = 100
/** The most folders the owner shares with guests. */
export const SHARED_FOLDERS_MAX = 20
/** How often the sharing is read again while anything is shared either way, and while nothing is. */
const BUSY_MS = 2 * 60_000
const IDLE_MS = 15 * 60_000
/** A first read waits for the core and the gateway to settle; a notice is read soon after. */
const START_MS = 5_000
const NOTICE_MS = 1_000
/** The backend's own rule for an address (zod's `email()`): one it refuses is refused here first, by name,
* rather than failing the whole list there (an address typed `name@!gmail.com`, 2026-10-15). */
const EMAIL_RE = /^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$/
/** This machine's sharing as its owner set it. `folders` stay here: the backend never hears of them. */
export interface LocalPolicy { emails: string[]; sameDomain: boolean; folders: SharedFolder[] }
export interface SharedMachinesDeps {
/** The core's `shared_machines` answers, or null signed out: nothing is shared or read. */
port: SharedMachinesPort | null
file: string
setTimer: (fn: () => void, ms: number) => { cancel(): void }
log: (line: string) => void
/** Guests' harnesses (services/guestLaunches.ts): their OS accounts, the owner's folders and the pane's command. */
guests: GuestLaunches
/** Whether guest access is on here (lib/guestHelperInstall.ts), and turning it on: the owner's one admin prompt. */
guestAccess: () => Promise<GuestHelperState>
enableGuests: () => Promise<GuestHelperInstallResult>
/** Where the core's port goes (serviceHost `start`); absent where only the requests are wanted. */
ports?: CorePorts
/** Why the owner may not share [path] with guests, or null when it may (the helper checks it again). */
folderProblem: (path: string) => string | null
}
const OFF: LocalPolicy = { emails: [], sameDomain: false, folders: [] }
export function readPolicy(file: string): LocalPolicy {
try {
const raw = JSON.parse(readFileSync(file, 'utf-8')) as Partial<LocalPolicy>
return { emails: normalizeEmails(raw.emails) ?? [], sameDomain: raw.sameDomain === true, folders: normalizeFolders(raw.folders) ?? [] }
} catch { return OFF }
}
/** Folders as the owner shares them: full paths, each once, never /; null when one is not. One a line in the
* helper's record, so a name may hold no tab or newline. */
export function normalizeFolders(raw: unknown): SharedFolder[] | null {
if (!Array.isArray(raw) || raw.length > SHARED_FOLDERS_MAX) return null
const folders: SharedFolder[] = []
for (const folder of raw) {
const { path, write } = (folder ?? {}) as { path?: unknown; write?: unknown }
if (typeof path !== 'string' || !isAbsolute(path) || path.length > 4096 || /[\t\n\r\0]/.test(path) || typeof write !== 'boolean') return null
const resolved = resolve(path)
if (resolved === parse(resolved).root || folders.some((f) => f.path === resolved)) return null
folders.push({ path: resolved, write })
}
return folders
}
/** Whether two resolved paths name one folder on [platform]: Windows has one spelling per folder, so it ignores
* case there (`c:\\programdata\\harnessguests` must not slip past the guests' root); POSIX paths are exact. */
export function sameSharedPath(a: string, b: string, platform: NodeJS.Platform = process.platform): boolean {
return platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b
}
/** Whether [path] is [root] or inside it, with Windows' one-spelling rule. */
export function withinSharedPath(path: string, root: string, platform: NodeJS.Platform = process.platform): boolean {
if (sameSharedPath(path, root, platform)) return true
const separator = platform === 'win32' ? win32.sep : sep
return platform === 'win32'
? path.toLowerCase().startsWith(`${root.toLowerCase()}${separator}`)
: path.startsWith(`${root}${separator}`)
}
/** The helper's own rules, said here first in words: a folder of the owner's, on this computer, never its whole
* home or a guest's. */
export function ownerFolderProblem(path: string, home = homedir(), guests = guestHomeRoot(), uid = process.getuid?.()): string | null {
let info
try { info = statSync(path) } catch { return `No such folder on this computer: ${path}` }
if (!info.isDirectory()) return `Not a folder: ${path}`
if (sameSharedPath(resolve(path), resolve(home))) return 'Your whole home folder cannot be shared. Choose a folder in it.'
// The guests' own tree: their host homes and records, which the setup task owns (`\` or `/`, by platform).
const guestRoot = resolve(guests)
const resolved = resolve(path)
if (withinSharedPath(resolved, guestRoot)) return `This folder belongs to someone you share with and can't be shared: ${path}`
if (uid !== undefined && info.uid !== uid) return `Only your own folders can be shared: ${path}`
return null
}
function writePolicy(file: string, policy: LocalPolicy): void {
const temp = `${file}.${process.pid}.tmp`
writeFileSync(temp, JSON.stringify(policy, null, 2), { mode: 0o600 })
renameSync(temp, file)
}
/** Addresses trimmed, lower case, each once; null when one is not an address or there are too many. */
export function normalizeEmails(raw: unknown): string[] | null {
if (!Array.isArray(raw)) return null
const emails = [...new Set(raw.map((e) => typeof e === 'string' ? e.trim().toLowerCase() : ''))]
if (emails.length > SHARE_EMAILS_MAX || emails.some((e) => e.length > 254 || !EMAIL_RE.test(e))) return null
return emails
}
type Sharing = Pick<LocalPolicy, 'emails' | 'sameDomain'>
const shares = (policy: Sharing): boolean => policy.emails.length > 0 || policy.sameDomain
const samePolicy = (a: Sharing, b: Sharing): boolean =>
a.sameDomain === b.sameDomain && a.emails.length === b.emails.length && a.emails.every((e) => b.emails.includes(e))
/** Whether this machine's own policy names someone the backend says uses it. */
const names = (local: LocalPolicy, domain: string | null, member: ShareMember): boolean => member.via === 'email'
? local.emails.includes(member.email)
: local.sameDomain && !!domain && member.email.endsWith(`@${domain}`)
/** Whether this machine's own policy still shares it with [email]: by address, or by the owner's domain. */
export function stillShared(local: LocalPolicy, domain: string | null, email: string): boolean {
return local.emails.includes(email) || (local.sameDomain && !!domain && email.endsWith(`@${domain}`))
}
/** The machines of those the backend says use this one, those this machine's own policy names. */
export function trustedKeys(local: LocalPolicy, remote: SharePolicy): SharedTrustPeer[] {
return remote.members
.filter((m) => names(local, remote.domain, m))
.flatMap((m) => m.machines.map((machine) => ({ ...machine, label: `${machine.label || 'Machine'} · ${m.email}`, email: m.email })))
}
const answerFailure = (f: PortFailure): Record<string, unknown> => ({ error: f.failed.code, message: f.failed.message })
/** The real guests: OS accounts through the setup task on Windows, the helper elsewhere, the owner's sign-ins
* read where the engines keep them. Exported with its platform so a test proves both accounts' sides. */
export function machineGuests(log: (line: string) => void, file: string, platform: NodeJS.Platform = process.platform): GuestLaunches {
return createGuestLaunches({
accounts: platform === 'win32'
? createWindowsGuestAccounts({ ownerHome: process.env.USERPROFILE ?? homedir() })
: createGuestAccounts(),
helperState: async () => (await guestHelperStatus()).state,
folders: () => readPolicy(file).folders,
...(process.env.LANG ? { lang: process.env.LANG } : {}),
platform,
log: (line) => log(`guest ${line}`),
})
}
/** A guest launch as the core asks for it; null when it is not one. */
export function guestLaunchInput(payload: Record<string, unknown>): GuestLaunchInput | null {
if (typeof payload.email !== 'string' || typeof payload.engine !== 'string' || typeof payload.bypassPermission !== 'boolean') return null
if (payload.prompt !== undefined && typeof payload.prompt !== 'string') return null
if (payload.cwd !== undefined && typeof payload.cwd !== 'string') return null
// Flags as an engine takes them (`--permission-mode`, `auto`): never a word that is not one.
const flags = payload.permissionFlags
if (flags !== undefined && (!Array.isArray(flags) || flags.length > 4 || !flags.every((f) => typeof f === 'string' && /^-{0,2}[A-Za-z][A-Za-z0-9-]*$/.test(f)))) return null
return { email: payload.email, engine: payload.engine, bypassPermission: payload.bypassPermission,
...(payload.prompt ? { prompt: payload.prompt } : {}), ...(payload.cwd ? { cwd: payload.cwd } : {}),
...(flags ? { permissionFlags: flags as string[] } : {}) }
}
export function startSharedMachines(core: CoreApi, overrides: Partial<SharedMachinesDeps> = {}): ServiceRequests {
const log = overrides.log ?? ((line: string) => console.log(`[shared-machines] ${line}`))
const file = overrides.file ?? join(core.dataDir, 'shared-machines.json')
const deps: SharedMachinesDeps = {
port: overrides.port !== undefined ? overrides.port : null,
file,
setTimer: overrides.setTimer ?? ((fn, ms) => { const t = setTimeout(fn, ms).unref(); return { cancel: () => clearTimeout(t) } }),
log,
guests: overrides.guests ?? machineGuests(log, file),
folderProblem: overrides.folderProblem ?? ((path) => ownerFolderProblem(path)),
guestAccess: overrides.guestAccess ?? (async () => (await guestHelperStatus()).state),
enableGuests: overrides.enableGuests ?? (() => installGuestHelper()),
}
const port = deps.port
const guests = deps.guests
if (overrides.ports) {
overrides.ports.sharedMachines = {
guestLaunch: (input) => guests.launch(input),
stop: () => { timer?.cancel() },
}
}
let timer: { cancel(): void } | null = null
let reading: Promise<void> | null = null
let again = false
/** Whether anything was shared with this account at the last read. */
let sharedWithUs = false
/** Publish this machine's policy and trust whom it names; pin the machines shared with this account. */
const refresh = async (port: SharedMachinesPort): Promise<void> => {
const local = readPolicy(deps.file)
const desired: { pins?: SharedTrustPeer[]; keys?: SharedTrustPeer[] } = {}
const shared = await port.shared()
if (!failed(shared)) {
sharedWithUs = shared.length > 0
desired.pins = shared.filter((m) => m.share.added && m.pub).map((m) => ({
machineId: m.machineId, pub: m.pub!, label: `${m.name || m.hostname || 'Machine'} · ${m.share.ownerEmail || m.share.ownerName}`,
}))
}
let remote = await port.policy()
// The backend is told again what this machine holds, whenever it says otherwise (a write that failed,
// a backend that lost it, the owner's domain now public). What it then holds is kept here, as `set` keeps it:
// it drops an address it never shares with (the owner's own), and a policy still naming one read back as
// different at every read, so it was written again every two minutes and each write had every member's
// apps re-read their machines (Diego's, every 1 to 3 minutes, 2026-10-28).
if (!failed(remote) && !samePolicy(local, remote)) {
remote = await port.publish(local.emails, local.sameDomain && !!remote.domain)
if (!failed(remote) && !samePolicy(local, remote)) {
writePolicy(deps.file, { ...local, emails: remote.emails, sameDomain: remote.sameDomain })
}
}
if (!failed(remote)) desired.keys = shares(local) ? trustedKeys(local, remote) : []
if (desired.pins || desired.keys) {
const held = await port.trust(desired)
if (failed(held)) deps.log(`could not update the trust stores: ${held.failed.message}`)
}
// A guest sharing no longer names keeps none of the owner's folders; every guest it names has the folders
// the owner shares.
if (!failed(remote)) await syncGuests(local, remote.domain, remote.members.map((m) => m.email))
}
const syncGuests = (local: LocalPolicy, domain: string | null, members: string[]): Promise<void> =>
guests.sync((email) => stillShared(local, domain, email), [...new Set([...local.emails, ...members])])
/** One read at a time; one asked for while another runs follows it. Then the next round. */
const read = (port: SharedMachinesPort): Promise<void> => {
if (reading) { again = true; return reading }
reading = (async () => {
do {
again = false
await refresh(port).catch((error: unknown) => deps.log(`read failed: ${error instanceof Error ? error.message : String(error)}`))
} while (again)
})().finally(() => {
reading = null
schedule(port, shares(readPolicy(deps.file)) || sharedWithUs ? BUSY_MS : IDLE_MS)
})
return reading
}
const schedule = (port: SharedMachinesPort, ms: number): void => {
timer?.cancel()
timer = deps.setTimer(() => { timer = null; void read(port) }, ms)
}
if (port) {
schedule(port, START_MS)
// A harness shared or taken back (`harness_shares`) changes no machine's sharing: read again on every one of those, every
// member's daemon followed each Swarm agent's invitations with this read (review of #1977, 2026-10-28).
core.account.onNotice((notice) => { if (notice.type === 'machines_changed' && notice.reason !== 'harness_shares') schedule(port, NOTICE_MS) })
}
const view = async (): Promise<Record<string, unknown>> => {
const local = readPolicy(deps.file)
const remote = port ? await port.policy() : null
if (!remote || failed(remote)) {
return { ...local, domain: null, members: [], ...(remote ? answerFailure(remote) : { error: 'NOT_SIGNED_IN' }) }
}
return { ...local, sameDomain: local.sameDomain && !!remote.domain, domain: remote.domain,
members: remote.members.filter((m) => names(local, remote.domain, m))
.map((m) => ({ email: m.email, name: m.name, via: m.via, machines: m.machines.length })),
guestAccess: await deps.guestAccess().catch(() => 'missing' as const) }
}
return {
shared_machines: async (payload, asker) => {
if (!asker.owner) return { error: 'OWNER_REQUIRED' }
switch (payload.action) {
case 'get': return view()
case 'set': {
const emails = normalizeEmails(payload.emails)
if (!emails || typeof payload.sameDomain !== 'boolean') {
const bad = Array.isArray(payload.emails) && payload.emails.length <= SHARE_EMAILS_MAX
? payload.emails.find((e) => typeof e !== 'string' || !EMAIL_RE.test(e.trim().toLowerCase())) : undefined
return { error: 'BAD_REQUEST', message: typeof bad === 'string' ? `Not an email address: ${bad}` : `Enter up to ${SHARE_EMAILS_MAX} email addresses.` }
}
if (!port) return { error: 'NOT_SIGNED_IN', message: 'Sign in to share this machine.' }
const published = await port.publish(emails, payload.sameDomain)
if (failed(published)) return answerFailure(published)
writePolicy(deps.file, { ...readPolicy(deps.file), emails: published.emails, sameDomain: published.sameDomain })
await read(port)
return view()
}
case 'add':
case 'remove': {
if (typeof payload.machineId !== 'string') return { error: 'BAD_REQUEST' }
if (!port) return { error: 'NOT_SIGNED_IN', message: 'Sign in to add a shared machine.' }
const done = payload.action === 'add' ? await port.add(payload.machineId) : await port.remove(payload.machineId)
if (failed(done)) return answerFailure(done)
await read(port)
return { ok: true }
}
// Guest access: the helper that runs guests' harnesses as their own OS accounts, installed behind
// one admin prompt on this computer (lib/guestHelperInstall.ts). Sharing turns it on first.
case 'enable_guests': {
const installed = await deps.enableGuests()
if (!installed.ok) return { error: installed.code, message: installed.message }
return { ok: true, guestAccess: await deps.guestAccess().catch(() => 'missing' as const) }
}
case 'set_folders': {
const folders = normalizeFolders(payload.folders)
if (!folders) return { error: 'BAD_REQUEST', message: `Choose up to ${SHARED_FOLDERS_MAX} folders, each by its full path.` }
const problem = folders.map((f) => deps.folderProblem(f.path)).find((p) => p !== null)
if (problem) return { error: 'BAD_REQUEST', message: problem }
const local = { ...readPolicy(deps.file), folders }
writePolicy(deps.file, local)
// Given to every guest now (or taken back), not at their next harness.
if (port) await read(port)
else await syncGuests(local, null, [])
return view()
}
default: return { error: 'UNKNOWN_ACTION' }
}
},
// A guest's: where it may start a harness. Its workspace, and the folders the owner shares with guests.
guest_folders: async (_payload, asker) => {
if (!asker.guest && !asker.owner) return { error: 'OWNER_REQUIRED' }
return { workspace: asker.guest ? guestWorkspaceFor(asker.guest) : null, folders: readPolicy(deps.file).folders }
},
}
}