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 owner's one-time step that lets guests run here (docs/plans/2026-10-19-guest-machine-sharing-plan.md):
* one admin prompt installs the guest helper, the sudoers drop-in that lets the owner's daemon run it
* without a password, a Node runtime guests' engines can use, and the hook script their engines report
* through. Guests are never prompted.
*
* One privileged script does all of it, staged in a private temp folder and run once: on macOS through
* `osascript … with administrator privileges` (the system's own password or Touch ID sheet), on Linux
* through `pkexec`, else `sudo` in the terminal. It is idempotent: running it again replaces each piece.
*/
import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir, userInfo } from 'node:os'
import { dirname, join, sep } from 'node:path'
import { env } from '../config/env.js'
import { HOOK_SCRIPT } from '../engines/kit/notifyHooks.js'
import { GUEST_HELPER_PATH, runGuestCommand, type GuestRunner } from './guestAccounts.js'
import { guestHelperScript, guestSudoersTemplate, helperScriptVersion } from './guestHelperAssets.js'
import { managedNodePath } from './nodeRuntime.js'
import type { RunAdmin } from '../team/admin.js'
export const GUEST_SUDOERS_PATH = '/etc/sudoers.d/harness-guests'
export const GUEST_NODE_DIR = '/usr/local/lib/harness/node'
export const GUEST_HOOK_DIR = '/usr/local/lib/harness/hook'
/** The helper version this CLI ships: an installed one older than it is installed again. */
export const GUEST_HELPER_VERSION = helperScriptVersion(guestHelperScript()) ?? 0
const OWNER = /^[A-Za-z_][A-Za-z0-9_.-]{0,31}$/
/** The sudoers drop-in for [owner]. */
export function sudoersFor(owner: string): string {
if (!OWNER.test(owner) || owner === 'root' || owner.startsWith('hg_')) throw new Error(`not an owner account: ${owner}`)
return guestSudoersTemplate().replaceAll('{{OWNER}}', owner)
}
/** POSIX single quotes. */
function sh(word: string): string {
return `'${word.replaceAll("'", `'\\''`)}'`
}
/** The managed Node runtime's folder (`~/.harness/runtime/node-…`), or null on a machine with none. */
export function managedNodeRuntimeDir(): string | null {
const node = managedNodePath()
if (!node.startsWith(env.ADAPTER_RUNTIME_DIR + sep)) return null
return dirname(dirname(node))
}
export interface InstallScriptInput {
/** The private folder holding `guest-helper`, `sudoers` and, when there is one, `notify.mjs`. */
stageDir: string
/** The Node runtime to copy for guests' engines; null leaves the installed one as it is. */
nodeRuntimeDir: string | null
hookScript: boolean
}
/** The one script run as root. Every target's parent must be root's alone: a helper sudo runs without a
* password, in a folder the owner (or anyone) could write, would be root for whatever replaced it. */
export function buildInstallScript(input: InstallScriptInput): string {
const stage = sh(input.stageDir)
const lines = [
'#!/bin/sh',
'# Harness guest helper install (cli/src/lib/guestHelperInstall.ts), run once as root.',
'set -eu',
'die() { printf "harness: %s\\n" "$1" >&2; exit "${2:-1}"; }',
// A parent another account could write is refused, not repaired: chown-ing a system folder is not ours.
'owned_by_root() {',
' [ -e "$1" ] || return 0',
// (GNU `stat -f` is the file system's status and answers anything: the platform decides.)
' if [ "$(uname -s)" = Darwin ]; then uid=$(stat -f %u "$1"); mode=$(stat -f %Lp "$1")',
' else uid=$(stat -c %u "$1"); mode=$(stat -c %a "$1"); fi',
' [ "$uid" = 0 ] || die "$1 is not owned by root" 6',
' [ $((0$mode & 022)) -eq 0 ] || die "$1 can be written by others" 6',
'}',
'for dir in / /usr /usr/local /usr/local/libexec /usr/local/lib /etc /etc/sudoers.d; do owned_by_root "$dir"; done',
// sudo must read drop-ins; editing /etc/sudoers itself is not ours to do either.
"grep -Eq '^[#@]includedir[[:space:]]+(/private)?/etc/sudoers\\.d' /etc/sudoers || die 'sudo does not read /etc/sudoers.d on this computer' 5",
`visudo -cf ${stage}/sudoers >/dev/null || die 'the sudoers drop-in is not valid' 5`,
`mkdir -p ${sh(dirname(GUEST_HELPER_PATH))} ${sh(GUEST_HOOK_DIR)}`,
`chown 0:0 ${sh(dirname(GUEST_HELPER_PATH))} ${sh(dirname(GUEST_HOOK_DIR))} ${sh(GUEST_HOOK_DIR)}`,
`chmod 755 ${sh(dirname(GUEST_HELPER_PATH))} ${sh(dirname(GUEST_HOOK_DIR))} ${sh(GUEST_HOOK_DIR)}`,
// The helper before the drop-in that names it: sudo never allows a path that is not in place yet.
`install -o 0 -g 0 -m 0755 ${stage}/guest-helper ${sh(GUEST_HELPER_PATH)}`,
]
if (input.nodeRuntimeDir) {
const next = sh(`${GUEST_NODE_DIR}.new`)
// Node and npm, which a guest's engine installs need: `bin`, `lib` and `include`, about 190 MB. Never the
// runtime's `libexec`, the daemon's own process images (a renamed node per process, 1.2 GB on 2026-10-19).
const parts = ['bin', 'lib', 'include'].map((part) => sh(`${input.nodeRuntimeDir}/${part}`)).join(' ')
lines.push(
`rm -rf ${next}`,
`mkdir -p ${next}`,
`for part in ${parts}; do [ ! -e "$part" ] || cp -R "$part" ${next}/; done`,
`chown -R 0:0 ${next}`,
`chmod -R a+rX,go-w ${next}`,
`rm -rf ${sh(GUEST_NODE_DIR)}`,
`mv ${next} ${sh(GUEST_NODE_DIR)}`,
)
}
if (input.hookScript) lines.push(`install -o 0 -g 0 -m 0644 ${stage}/notify.mjs ${sh(`${GUEST_HOOK_DIR}/notify.mjs`)}`)
lines.push(`install -o 0 -g 0 -m 0440 ${stage}/sudoers ${sh(GUEST_SUDOERS_PATH)}`, '')
return lines.join('\n')
}
/** The osascript line that runs [scriptPath] as root behind the system's admin prompt. */
export function adminAppleScript(scriptPath: string, prompt: string): string {
const quote = (text: string) => `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`
return `do shell script "/bin/sh " & quoted form of ${quote(scriptPath)} with prompt ${quote(prompt)} with administrator privileges`
}
export const GUEST_HELPER_PROMPT =
'Harness wants to let people you share this computer with run their harnesses as separate accounts, so they cannot see your files.'
export type GuestHelperInstallResult =
| { ok: true }
| { ok: false; code: 'CANCELLED' | 'FAILED' | 'UNSUPPORTED'; message: string }
export interface GuestHelperInstallOptions {
/** The account the drop-in allows: this one, by default. */
owner?: string
runner?: GuestRunner
platform?: NodeJS.Platform
nodeRuntimeDir?: string | null
hookScript?: string | null
/** Whether `pkexec` and a desktop session are there (Linux). */
graphical?: boolean
/** A test's stand-in for the Windows UAC runner. */
admin?: RunAdmin
/** Windows: the owner's profile, `%USERPROFILE%`. */
ownerHome?: string
}
export async function installGuestHelper(options: GuestHelperInstallOptions = {}): Promise<GuestHelperInstallResult> {
const platform = options.platform ?? process.platform
// Windows's script builders (and the Team imports they bring) are loaded only there: every other platform, and
// every service sharing the edge host's process, must not carry them (src/leanEntry.spec.ts).
if (platform === 'win32') {
const { installWindowsGuestHelper } = await import('./windows/guestHelperInstallWin.js')
return installWindowsGuestHelper(options, GUEST_HELPER_PROMPT)
}
if (platform !== 'darwin' && platform !== 'linux') {
return { ok: false, code: 'UNSUPPORTED', message: 'Sharing this computer needs macOS or Linux.' }
}
const runner = options.runner ?? runGuestCommand
const owner = options.owner ?? userInfo().username
let sudoers: string
try {
sudoers = sudoersFor(owner)
} catch (error) {
return { ok: false, code: 'FAILED', message: (error as Error).message }
}
const nodeRuntimeDir = options.nodeRuntimeDir === undefined ? managedNodeRuntimeDir() : options.nodeRuntimeDir
const hookScript = options.hookScript === undefined ? (existsSync(HOOK_SCRIPT) ? HOOK_SCRIPT : null) : options.hookScript
// Private to this account until root copies it (mkdtemp is 0700): nobody else can swap a file in between.
const stageDir = mkdtempSync(join(tmpdir(), 'harness-guest-'))
try {
writeFileSync(join(stageDir, 'guest-helper'), guestHelperScript(), { mode: 0o700 })
writeFileSync(join(stageDir, 'sudoers'), sudoers, { mode: 0o600 })
if (hookScript) writeFileSync(join(stageDir, 'notify.mjs'), readFileSync(hookScript), { mode: 0o600 })
const script = join(stageDir, 'install.sh')
writeFileSync(script, buildInstallScript({ stageDir, nodeRuntimeDir, hookScript: !!hookScript }), { mode: 0o700 })
chmodSync(stageDir, 0o700)
let result
if (platform === 'darwin') {
result = await runner('osascript', ['-e', adminAppleScript(script, GUEST_HELPER_PROMPT)], { timeoutMs: 10 * 60_000 })
// -128 is the sheet's Cancel.
if (result.code !== 0 && /-128|User canceled/i.test(result.stderr)) {
return { ok: false, code: 'CANCELLED', message: 'Sharing was not turned on: the admin prompt was cancelled.' }
}
} else {
const graphical = options.graphical ?? (existsSync('/usr/bin/pkexec') && !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY))
result = graphical
? await runner('pkexec', ['/bin/sh', script], { timeoutMs: 10 * 60_000 })
: await runner('sudo', ['/bin/sh', script], { interactive: true, timeoutMs: 10 * 60_000 })
// pkexec: 126 is a dismissed dialog, 127 a refused authorization.
if (graphical && (result.code === 126 || result.code === 127)) {
return { ok: false, code: 'CANCELLED', message: 'Sharing was not turned on: the admin prompt was cancelled.' }
}
}
if (result.code !== 0) {
// osascript's `do shell script` ends the script's stderr lines with CR, not LF: split on both, or a reason after an
// earlier line is never found, and the CR left in it makes a terminal print the line over itself.
const said = result.stderr.trim().split(/[\r\n]+/).pop()?.replace(/^.*harness: /, '') ?? ''
return { ok: false, code: 'FAILED', message: said || 'Sharing could not be set up on this computer.' }
}
return { ok: true }
} finally {
rmSync(stageDir, { recursive: true, force: true })
}
}
export type GuestHelperState =
| 'ready' // installed, current, and this account may run it without a password
| 'missing'
| 'outdated' // older than this CLI's: install again
| 'not-authorized' // installed, but sudo asks this account for a password
export interface GuestHelperStatus { state: GuestHelperState; version: number | null }
export interface GuestHelperStatusDeps {
runner?: GuestRunner
platform?: NodeJS.Platform
helperPath?: string
/** The installed helper's text, or null when there is none (no sudo needed: it is 0755). */
read?: (path: string) => string | null
}
export async function guestHelperStatus(deps: GuestHelperStatusDeps = {}): Promise<GuestHelperStatus> {
const helperPath = deps.helperPath ?? GUEST_HELPER_PATH
const read = deps.read ?? ((path: string) => {
try {
return statSync(path).isFile() ? readFileSync(path, 'utf8') : null
} catch {
return null
}
})
const platform = deps.platform ?? process.platform
if (platform === 'win32') {
const { windowsGuestHelperStatus } = await import('./windows/guestHelperInstallWin.js')
return windowsGuestHelperStatus(deps, read)
}
const text = read(helperPath)
if (text === null) return { state: 'missing', version: null }
const version = helperScriptVersion(text)
if (version === null || version < GUEST_HELPER_VERSION) return { state: 'outdated', version }
// `sudo -n -l <command>` answers 0 only when this account may run it without a password.
const allowed = await (deps.runner ?? runGuestCommand)('sudo', ['-n', '-l', helperPath], { timeoutMs: 10_000 })
return { state: allowed.code === 0 ? 'ready' : 'not-authorized', version }
}