Skip to content

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.

cli: install grid with its own public installer when a machine has none

Timff928bdd2621
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index f9fc4f585..2cc7a4ab7 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -53,6 +53,7 @@ import { readOrMintComputerId } from './lib/computerIdentity.js'
import { renderLoginSuccessHtml } from './lib/loginPage.js'
import { AuthSessionError, AuthSessionManager, clearAuthSession, readAuthSession, writeAuthSession, type AuthSession } from './lib/authSession.js'
import { handOffToGrid } from './lib/gridHandoff.js'
+import { ensureGridInstalled } from './lib/gridInstall.js'
import { ensureHarnessGrid } from './lib/gridEnsure.js'
import { passThroughToGridLogout } from './lib/gridLogout.js'
import { clearGridMcpUrlCache } from './lib/gridMcpUrl.js'
@@ -520,6 +521,13 @@ type SignInOutcome =
*/
async function attachGridToSignIn(token: string, json: boolean): Promise<Record<string, unknown>> {
const note = (line: string): void => { if (!json) console.error(` · ${line}`) }
+ // A machine with no `grid` gets one first, from grid's own installer — the sign-in that follows
+ // is what makes it useful, and "install the grid CLI yourself" was the sentence every fresh
+ // machine used to stop at. Best-effort: a failed install is a note, and the hand-off below then
+ // reports the missing binary exactly as before.
+ const install = await ensureGridInstalled()
+ if (install.status === 'installed') note(install.message)
+ else if (install.status !== 'present') note(install.message)
const handoff = await handOffToGrid(token, { json: true })
if (handoff.code !== 'OK') {
note(handoff.message)
@@ -3460,6 +3468,12 @@ async function runForeground(session: AuthSession): Promise<void> {
installCursorHooks(hookPort)
installOpencodePlugin(hookPort)
installOpencodeHarnessComputeSkill()
+ // The `grid` CLI the Harness Compute skill shells out to, for a machine that signed in before
+ // this existed or whose sign-in could not fetch it. In the background: a download must not hold
+ // the daemon's own start, and nothing here waits on it.
+ void ensureGridInstalled().then((result) => {
+ if (result.status !== 'present') console.log(`[grid] ${result.message}`)
+ })
installKiloPlugin(hookPort)
installPiExtension(hookPort)
// A self-update refreshes plugin files here; running engine processes pick them up according to each
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index 6a7bf2942..f54577568 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -257,6 +257,9 @@ const envSchema = z.object({
ADAPTER_COMPUTER_ID_FILE: z.string().default(computerIdFile),
// Set to 'true' to skip auto-installing lifecycle hooks for every supported engine.
DISABLE_HOOK_INSTALL: z.string().default('false').transform((v) => v === 'true'),
+ // `harness start` and `harness login` install the `grid` CLI when the machine has none (see
+ // lib/gridInstall.ts). Off for tests and for a machine whose grid is managed some other way.
+ DISABLE_GRID_INSTALL: z.string().default('false').transform((v) => v === 'true'),
// Additive terminal capability. Order controls deterministic primary-route tie breaking.
//
// UNSET MEANS AUTO — every backend that is actually usable here, which is what makes `herdr` then an
diff --git a/cli/src/lib/gridExec.ts b/cli/src/lib/gridExec.ts
index 0263f31c7..4ea21b3a8 100644
--- a/cli/src/lib/gridExec.ts
+++ b/cli/src/lib/gridExec.ts
@@ -18,6 +18,7 @@
*/
import { spawn } from 'node:child_process'
import { accessSync, constants, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
import { join, sep } from 'node:path'
import { env } from '../config/env.js'
import { binaryOnPath } from './binaryOnPath.js'
@@ -90,6 +91,12 @@ export function gridBinaryPath(processEnv: NodeJS.ProcessEnv = process.env): str
} catch {
// absent, unreadable, or not executable → fall through to PATH
}
+ if (binaryOnPath(GRID_BINARY, processEnv)) return GRID_BINARY
+ // Where grid's own installer puts it (`lib/gridInstall.ts`), which a daemon started from a launcher
+ // with launchd's bare PATH does not have. Named absolutely rather than by extending PATH, so the
+ // fallback reaches exactly one known file and never whatever else that directory holds.
+ const installed = join(homedir(), '.local', 'bin', GRID_BINARY)
+ try { accessSync(installed, constants.X_OK); return installed } catch { /* not there either */ }
return GRID_BINARY
}
diff --git a/cli/src/lib/gridHandoff.ts b/cli/src/lib/gridHandoff.ts
index df4f72dd2..d3cd4e851 100644
--- a/cli/src/lib/gridHandoff.ts
+++ b/cli/src/lib/gridHandoff.ts
@@ -13,6 +13,7 @@
*/
import { spawn } from 'node:child_process'
import { binaryOnPath } from './binaryOnPath.js'
+import { gridBinaryPath } from './gridExec.js'
/** The command, and the flag on it that means "read the token off stdin" (autonomous-grid's
* `cli/parser.py`). Located on PATH with no environment override: tests control PATH directly, so an
@@ -84,12 +85,16 @@ export async function handOffToGrid(
// one, not a spawn error the caller has to recognise. This process's own environment, inherited —
// there is nothing to override, and a parameter for one would be the knob with no user the ticket
// refuses.
- if (!binaryOnPath(GRID_BINARY)) {
+ // Resolved the way every other grid call is (`gridExec.gridBinaryPath`): a managed runtime, PATH,
+ // or the directory grid's installer uses — so a `grid` that `lib/gridInstall.ts` just put in
+ // `~/.local/bin` is found by the sign-in that follows, whatever the daemon's PATH says.
+ const binary = gridBinaryPath()
+ if (!binaryOnPath(binary)) {
return { code: 'GRID_CLI_MISSING', exitCode: 1, message: MISSING_MESSAGE, stdout: '', stderr: '' }
}
const args = ['login', GRID_HANDOFF_FLAG, ...(opts.json ? ['--json'] : [])]
return await new Promise<GridHandoffResult>((resolve) => {
- const child = spawn(GRID_BINARY, args, {
+ const child = spawn(binary, args, {
stdio: ['pipe', opts.json ? 'pipe' : 'inherit', opts.json ? 'pipe' : 'inherit'],
})
let stdout = ''
diff --git a/cli/src/lib/gridInstall.spec.ts b/cli/src/lib/gridInstall.spec.ts
new file mode 100644
index 000000000..ed596b501
--- /dev/null
+++ b/cli/src/lib/gridInstall.spec.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ensureGridInstalled, GRID_INSTALL_URL, type GridInstallDeps } from './gridInstall.js'
+
+function deps(overrides: Partial<GridInstallDeps> = {}): GridInstallDeps & { runs: string[] } {
+ const runs: string[] = []
+ return {
+ runs,
+ available: () => false,
+ curlOnPath: () => true,
+ enabled: true,
+ run: async (script) => { runs.push(script); return { exitCode: 0, output: '✓ grid installed' } },
+ ...overrides,
+ }
+}
+
+describe('ensureGridInstalled', () => {
+ it('runs nothing on a machine that already has grid', async () => {
+ const d = deps({ available: () => true })
+ expect(await ensureGridInstalled(d)).toMatchObject({ status: 'present' })
+ expect(d.runs).toEqual([])
+ })
+
+ it("pipes grid's own public installer to bash, and reports installed once grid resolves", async () => {
+ let installed = false
+ const runs: string[] = []
+ const d = deps({
+ available: () => installed,
+ run: async (script) => { runs.push(script); installed = true; return { exitCode: 0, output: 'ok' } },
+ })
+ const result = await ensureGridInstalled(d)
+ expect(result.status).toBe('installed')
+ expect(runs).toEqual([`curl -fsSL ${GRID_INSTALL_URL} | bash`])
+ })
+
+ it('is skipped, not failed, when switched off or when there is no curl', async () => {
+ expect((await ensureGridInstalled(deps({ enabled: false }))).status).toBe('skipped')
+ const noCurl = deps({ curlOnPath: () => false })
+ expect((await ensureGridInstalled(noCurl)).status).toBe('skipped')
+ expect(noCurl.runs).toEqual([])
+ })
+
+ it('reports a failed installer with its last lines, colour stripped', async () => {
+ const d = deps({ run: async () => ({ exitCode: 1, output: 'downloading\nERROR: no release' }) })
+ const result = await ensureGridInstalled(d)
+ expect(result.status).toBe('failed')
+ expect(result.message).toContain('exited 1')
+ expect(result.message).toContain('ERROR: no release')
+ expect(result.message).not.toContain('')
+ })
+
+ it('reports failure when the installer succeeds but grid is still not resolvable', async () => {
+ const d = deps({ run: async () => ({ exitCode: 0, output: 'done' }) })
+ const result = await ensureGridInstalled(d)
+ expect(result.status).toBe('failed')
+ expect(result.message).toContain('left no `grid`')
+ })
+
+ it('shares one in-flight install between concurrent callers', async () => {
+ let installed = false
+ const run = vi.fn(async () => {
+ await new Promise((r) => setTimeout(r, 10))
+ installed = true
+ return { exitCode: 0, output: '' }
+ })
+ const d = deps({ available: () => installed, run })
+ const [a, b] = await Promise.all([ensureGridInstalled(d), ensureGridInstalled(d)])
+ expect(a.status).toBe('installed')
+ expect(b.status).toBe('installed')
+ expect(run).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/cli/src/lib/gridInstall.ts b/cli/src/lib/gridInstall.ts
new file mode 100644
index 000000000..7a6ba0618
--- /dev/null
+++ b/cli/src/lib/gridInstall.ts
@@ -0,0 +1,133 @@
+/**
+ * Put `grid` on a machine that has none, with grid's own public installer.
+ *
+ * `harness login` used to CHECK for `grid` and, finding none, print "install the grid CLI yourself"
+ * and skip the grid half of sign-in. Every fresh install — a new machine, a colleague's laptop —
+ * landed there, and everything the Harness Compute skill does shells out to `grid`, so on those
+ * machines the Local model manager could only report that nothing was installed. The plan's answer
+ * (`docs/plans/2026-09-14-004-harness-grid-plan.md`, Change 2c) is a signed, pinned managed
+ * runtime, which is release-pipeline work nobody has done. This is the interim that closes the gap
+ * today: run the installer grid itself publishes and maintains, `https://grid.autonomous.ai/install.sh`
+ * — on macOS it installs `uv` if needed and `uv tool install`s the release wheel to
+ * `~/.local/bin/grid`; on Linux it downloads the sha256-verified release binary to the same place.
+ * Exactly the by-hand steps, run for the person.
+ *
+ * ⚠️ Best-effort, never a reason `harness start` or `harness login` fails. No `curl`, no network, a
+ * refused download — every one is a sentence in the log and a daemon that runs as before. A
+ * machine that already has `grid` is never touched; nothing here updates a binary that exists.
+ *
+ * Idempotent and serialised: two callers (start and a login that follows it) share one in-flight
+ * install rather than racing two installers into the same directory.
+ */
+import { spawn } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { env } from '../config/env.js'
+import { binaryOnPath } from './binaryOnPath.js'
+import { gridAvailable } from './gridExec.js'
+
+export const GRID_INSTALL_URL = 'https://grid.autonomous.ai/install.sh'
+
+/** Where grid's installer puts the binary on both platforms — the reason `gridBinaryPath` falls
+ * back to this directory when `~/.local/bin` is not on the daemon's PATH. */
+export const GRID_INSTALL_DIR = join(homedir(), '.local', 'bin')
+
+/** A download plus, on macOS, a `uv` bootstrap and a wheel install: minutes on a slow link, never
+ * hours. Past this the installer is killed and reported, not waited on forever. */
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000
+
+const MAX_CAPTURED_CHARS = 16 * 1024
+
+export type GridInstallStatus =
+ /** `grid` was already there; nothing ran. */
+ | 'present'
+ /** The installer ran and `grid` is now resolvable. */
+ | 'installed'
+ /** Not attempted: switched off, or no `curl` to fetch the installer with. */
+ | 'skipped'
+ /** The installer ran and failed, or ran and left no `grid` behind. */
+ | 'failed'
+
+export interface GridInstallResult {
+ status: GridInstallStatus
+ /** One sentence for the log or stderr. Never contains a credential — the installer takes none. */
+ message: string
+}
+
+export interface GridInstallDeps {
+ available: () => boolean
+ curlOnPath: () => boolean
+ /** Run the installer; resolves with its exit code and bounded output. Injected for the tests. */
+ run: (script: string, timeoutMs: number) => Promise<{ exitCode: number; output: string }>
+ enabled: boolean
+}
+
+function capped(sofar: string, chunk: Buffer): string {
+ return sofar.length >= MAX_CAPTURED_CHARS ? sofar : (sofar + chunk.toString()).slice(0, MAX_CAPTURED_CHARS)
+}
+
+/** The installer, piped to bash the way its README says, with `~/.local/bin` ahead on PATH so the
+ * `uv` it may have just installed is found by the same run. */
+export function runInstaller(script: string, timeoutMs: number): Promise<{ exitCode: number; output: string }> {
+ return new Promise((resolve) => {
+ const child = spawn('bash', ['-c', script], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: { ...process.env, PATH: `${GRID_INSTALL_DIR}:${process.env.PATH ?? ''}` },
+ })
+ let output = ''
+ let settled = false
+ const settle = (exitCode: number): void => {
+ if (settled) return
+ settled = true
+ clearTimeout(timer)
+ resolve({ exitCode, output })
+ }
+ const timer = setTimeout(() => {
+ output = capped(output, Buffer.from(`\n(installer killed after ${Math.round(timeoutMs / 60_000)} minutes)`))
+ child.kill('SIGKILL')
+ settle(124)
+ }, timeoutMs)
+ child.stdout?.on('data', (chunk: Buffer) => { output = capped(output, chunk) })
+ child.stderr?.on('data', (chunk: Buffer) => { output = capped(output, chunk) })
+ child.on('error', (err) => { output = capped(output, Buffer.from(err.message)); settle(1) })
+ child.on('close', (code) => settle(code ?? 1))
+ })
+}
+
+export const defaultGridInstallDeps: GridInstallDeps = {
+ available: () => gridAvailable(),
+ curlOnPath: () => binaryOnPath('curl'),
+ run: runInstaller,
+ enabled: !env.DISABLE_GRID_INSTALL,
+}
+
+let inFlight: Promise<GridInstallResult> | null = null
+
+/**
+ * Make sure this machine has `grid`, installing it when it does not. Safe to call from anywhere and
+ * as often as wanted: a machine that has it answers at once, and concurrent callers share one run.
+ */
+export function ensureGridInstalled(deps: GridInstallDeps = defaultGridInstallDeps): Promise<GridInstallResult> {
+ if (deps.available()) return Promise.resolve({ status: 'present', message: '`grid` is installed' })
+ if (!deps.enabled) return Promise.resolve({ status: 'skipped', message: 'grid install is switched off (DISABLE_GRID_INSTALL)' })
+ if (!deps.curlOnPath()) {
+ return Promise.resolve({ status: 'skipped', message: 'no `grid` on this machine and no `curl` to fetch its installer with — install it from ' + GRID_INSTALL_URL })
+ }
+ if (inFlight) return inFlight
+ inFlight = (async (): Promise<GridInstallResult> => {
+ try {
+ const { exitCode, output } = await deps.run(`curl -fsSL ${GRID_INSTALL_URL} | bash`, INSTALL_TIMEOUT_MS)
+ const tail = output.trim().split('\n').slice(-3).join(' · ').replace(/\[[0-9;]*m/g, '')
+ if (exitCode !== 0) {
+ return { status: 'failed', message: `grid installer exited ${exitCode}${tail ? ` · ${tail}` : ''}` }
+ }
+ if (!deps.available()) {
+ return { status: 'failed', message: `grid installer finished but left no \`grid\` in ${GRID_INSTALL_DIR}${tail ? ` · ${tail}` : ''}` }
+ }
+ return { status: 'installed', message: `installed \`grid\` to ${GRID_INSTALL_DIR}` }
+ } finally {
+ inFlight = null
+ }
+ })()
+ return inFlight
+}