Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Changelog

## 0.6.14

- Linux x64: Firecracker v1.17.0 ships inside `@gildforge/cli-linux-x64` next to `gild` (Apache-2.0; LICENSE, NOTICE and THIRD-PARTY in `vendor/firecracker/`), checked against a pinned sha256 and the one Firecracker publishes. gild uses `vm.firecracker` from isolation.json, then the bundled one, then `firecracker` on PATH.
- `gild spawn --vm --detach` output reaches `output.log` and `gild attach`: the guest terminal fed only its last listener, so the log stayed empty. Output from before the first listener and an exit before anyone listened are kept too.
- A detached session's output outlives it as `~/.gild/sessions/<id>.output.log` (0600, newest 10 kept), and `gild attach --watch <id>` prints it after the session ended. Short `--vm --detach` runs no longer vanish without a trace.
- Git works in a Firecracker guest: `/workspace` keeps the host uid while the agent runs as root, which stopped every git command at "detected dubious ownership"; the guest now trusts `/workspace`.
- docs/VM.md: which VM `--vm` uses where (Multipass on macOS by default, vz only with a `vm` block in isolation.json), and that Firecracker guests have no network by default, so the agent edits in the VM and the host commits and pushes.

## 0.6.13

- `gild spawn --vm` works on Apple silicon: gild publishes a linux-arm64 build (`@gildforge/cli-linux-arm64`, with its node-pty prebuild), so the agent inside the arm64 Multipass VM has its own `gild` for git credentials and pull requests. Before, every `gild` call in that VM failed with "no build for linux-arm64".
Expand Down
25 changes: 14 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,24 +248,27 @@ for `attach` to replay and appends everything to
`~/.gild/sessions/<id>/output.log` (0600, 8 MiB, one rotation to `output.log.1`).
Keystrokes from `attach` go through the same input tracking as an attached
spawn, so an unsent draft still holds injected messages. Detaching never stops
the agent; `gild stop` does, and removes the socket, settings and log with it.
the agent; `gild stop` does, and removes the socket and settings with it. The
output outlives the session as `~/.gild/sessions/<id>.output.log` (0600; the
newest 10 ended sessions are kept), and `gild attach --watch <id>` prints it
once the session has ended.

`--detach` combines with `--vm`: `gild spawn --vm --detach --name bob claude`
runs the child in a microVM with no terminal, and `send`, `attach`, `sync` and
`stop` work as above; `stop` brings the guest's last changes back to the host.

### microVM sessions (`--vm`)

`gild spawn --vm` runs the agent in a Firecracker microVM on a copy of the
working directory (`gild sync <id>` brings changes back; exit does too). Build
the guest image once per gild version on an x86_64 Linux host with Docker:

```sh
bun run vm:image # in a gildforge/cli checkout; writes ~/.config/gild/vm/
```

A guest image built for another gild version is refused at boot with that same
command as the fix. Details: [docs/VM.md](docs/VM.md).
`gild spawn --vm` runs the agent in a VM: Firecracker on Linux, Multipass on
macOS and Windows (vz on macOS only when isolation.json sets up a `vm`). On
Linux the npm package ships Firecracker next to `gild`, and the guest image is
downloaded on first use; you need `/dev/kvm` and `mke2fs`. The guest works on a
copy of the working directory with no network by default: the agent edits
there, its file changes come back to the host (`gild sync <id>`, and at exit),
and the host commits and pushes. Commits made in the guest stay in the guest
(host Git metadata is protected). Multipass VMs push from inside. Details, and
building the guest image yourself: [docs/VM.md](docs/VM.md). A guest image
built for another gild version is refused at boot.

Automatic sync protects host Git metadata and retains incomplete work for
recovery. Published images currently cover Linux x64 and Apple Silicon; they
Expand Down
71 changes: 64 additions & 7 deletions docs/VM.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,63 @@
# microVM guest image

`gild spawn --vm` and `gild runner start --isolation vm` boot a microVM
(Firecracker on Linux, Virtualization.framework on macOS) from a kernel and a
read-only ext4 root filesystem holding `gild-guest-agent` and `/init-gild.sh`.
All of it comes out of this repository.
`gild spawn --vm` and `gild runner start --isolation vm` boot a microVM from a
kernel and a read-only ext4 root filesystem holding `gild-guest-agent` and
`/init-gild.sh`. All of it comes out of this repository.

Which VM `--vm` uses:

| host | backend |
|---|---|
| Linux x64 | Firecracker (shipped with gild, below) |
| macOS, Windows | Multipass: one Ubuntu VM, made on first use and kept |
| macOS with a `vm` block in `<config dir>/isolation.json` | Virtualization.framework (`vz`), the guest image below |

## Firecracker ships with gild (Linux x64)

`@gildforge/cli-linux-x64`, the package npm installs for `gildforge` on Linux
x64, carries `bin/firecracker` next to `bin/gild`: Firecracker v1.17.0
(Apache-2.0; its `LICENSE`, `NOTICE` and `THIRD-PARTY` are in
`vendor/firecracker/`). `scripts/vendor-firecracker.mjs` takes it from the
upstream release tarball when the packages are built, and refuses it unless
the tarball matches both the pin in `scripts/firecracker.json` and the sha256
Firecracker publishes beside it.

gild runs, in this order: `vm.firecracker` from `isolation.json`, the
`firecracker` next to the gild executable, then `firecracker` on `PATH`. The
host still needs `/dev/kvm` (read and write for your user) and `mke2fs`
(e2fsprogs).

## Network, git and getting work out

A Firecracker guest has **no network device** unless the owner ran
`sudo scripts/vm-network-setup.sh` once (a `gildbr0` bridge and tap devices
that allow the internet and deny the host, the LAN and metadata addresses);
`gild spawn --vm` prints which one applies:

```
gild: vm network: none, egress blocked (no gildbr0 bridge; enable with: sudo scripts/vm-network-setup.sh)
```

So on Linux the agent **edits in the VM and the host commits and pushes**:

- The working directory, `.git` included, is copied into the guest at
`/workspace`. Git works there (gild sets `safe.directory=/workspace` for the
guest, whose files keep your uid while the agent runs as root), so the agent
can diff, branch and commit locally.
- File changes come back to the host at exit and with `gild sync <id>`,
three-way against what was copied in; a file you changed on the host
meanwhile is kept and the guest's copy saved aside.
- Changes under `.git` never come back (host Git metadata is protected): a
commit made in the guest stays in the guest, and the session keeps its VM
workspace for recovery (`~/.gild/sessions/<id>.vm-*`, `recovery.json`) and
exits nonzero. Have the agent leave its changes uncommitted, then commit,
push and open the pull request on the host (`gild pr create … --agent <label>`).
- No token, gild key or `gild` binary enters a Firecracker guest; the clone's
credential helper points at the host's gild and is not usable inside.

Multipass on macOS and Windows differs: the agent's own gild key and
repo-scoped token are copied into the VM, it has network, and the agent
pushes and opens pull requests from inside; nothing is copied back.

## Published images (nothing to build)

Expand Down Expand Up @@ -40,11 +94,13 @@ isolation: container (oci), requested by flag (vm image unavailable, fell back t
Nothing is downloaded when isolation.json points `vm` at your own kernel and
rootfs, when `vm/image.json` is a local build (`bun run vm:image`), or when
the host cannot run the backend anyway (no Firecracker, `/dev/kvm` or
`mke2fs`; a Mac without a hypervisor). Firecracker itself is not shipped.
`mke2fs`; a Mac without a hypervisor). Firecracker comes with the Linux x64
package (above).

## Build it yourself

On an x86_64 Linux host with `/dev/kvm`, Firecracker, `mke2fs` and Docker
On an x86_64 Linux host with `/dev/kvm`, Firecracker (the bundled one or your
own), `mke2fs` and Docker
(BuildKit), from a checkout of the gild version you run:

```sh
Expand All @@ -69,7 +125,8 @@ packs to the same bytes; apt packages still follow the Ubuntu mirror.

## macOS (`vz`)

The Virtualization.framework backend boots an arm64 guest built by
Used only when `<config dir>/isolation.json` has a `vm` block; otherwise macOS
runs `--vm` in Multipass. The Virtualization.framework backend boots an arm64 guest built by
`scripts/build-vm-guest.sh <dir>` (docker or Colima); it compiles the same
guest agent from this checkout, so the handshake below applies to both.

Expand Down
11 changes: 11 additions & 0 deletions scripts/firecracker.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"version": "1.17.0",
"tarball": "https://github.com/firecracker-microvm/firecracker/releases/download/v1.17.0/firecracker-v1.17.0-x86_64.tgz",
"sha256": "06094a1108ae9e82aa4c23a775aa92758f53f1175d422270d9d6162cb9ade558",
"files": {
"firecracker-v1.17.0-x86_64": "99ad0f5cd0514a88aad0e9ae8cfdb3cc3b4ab9d190e1194602406c786b5de7a5",
"LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
"NOTICE": "0f443af83ca8226c7ec44e2ade3a09fa3eed8c9b923b6c014b6d439816b6f1c2",
"THIRD-PARTY": "a6d3ebd1c2f37d4fd83d0676621f695fc0cc2d8c6e646cdbb831b46e0650c208"
}
}
6 changes: 6 additions & 0 deletions scripts/fixtures/detach-harness.py
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,12 @@ def states():
check(not (SESSIONS / 'stubborn').exists() and not (SESSIONS / 'stubborn.sock').exists(), 'stubborn left files')
r = cli('stop', 'stubborn')
check(r.returncode == 1 and b'No live session stubborn' in r.stderr, r)
# The output outlives the session: private, and readable with attach --watch.
kept = SESSIONS / 'stubborn.output.log'
check(kept.exists() and b'"ready": true' in kept.read_bytes(), 'output not kept')
check(kept.stat().st_mode & 0o777 == 0o600, oct(kept.stat().st_mode))
r = cli('attach', '--watch', 'stubborn')
check(r.returncode == 0 and b'"ready": true' in r.stdout and b'stubborn has ended' in r.stderr, r)
else:
raise SystemExit(f'unknown case {CASE}')
print(json.dumps({'case': CASE, 'passed': True}))
Expand Down
14 changes: 12 additions & 2 deletions scripts/pack.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// packages/gildforge — the umbrella (bin launcher + optionalDependencies)
// packages/gild-darwin-arm64 — the compiled binary per platform
// packages/gild-darwin-x64
// packages/gild-linux-x64
// packages/gild-linux-x64 (plus bin/firecracker, Apache-2.0)
// packages/gild-linux-arm64 — the CLI inside an arm64 Linux VM (Multipass on Apple silicon)
// No postinstall anywhere: npm's optionalDependencies + os/cpu fields pick the
// right package, and the launcher just execs the binary it finds.
Expand All @@ -16,6 +16,7 @@ import {
import { join } from 'node:path'
import pkg from '../package.json'
import { vendorPty } from './vendor-pty.mjs'
import { vendorFirecracker } from './vendor-firecracker.mjs'

const ROOT = new URL('..', import.meta.url).pathname
const TARGETS = [
Expand All @@ -26,7 +27,13 @@ const TARGETS = [
cpu: 'arm64',
},
{ name: 'cli-darwin-x64', bun: 'bun-darwin-x64', os: 'darwin', cpu: 'x64' },
{ name: 'cli-linux-x64', bun: 'bun-linux-x64', os: 'linux', cpu: 'x64' },
{
name: 'cli-linux-x64',
bun: 'bun-linux-x64',
os: 'linux',
cpu: 'x64',
firecracker: true,
},
// No gild-server build for linux-arm64 yet: no server optionalDependency.
{
name: 'cli-linux-arm64',
Expand Down Expand Up @@ -86,6 +93,9 @@ for (const t of TARGETS) {
}

await vendorPty(ROOT, TARGETS)
for (const t of TARGETS)
if (t.firecracker)
await vendorFirecracker(ROOT, join(ROOT, 'packages', t.name))

const launcher = (family, bin) => `#!/usr/bin/env node
// Picks the platform binary installed via optionalDependencies and execs it.
Expand Down
18 changes: 17 additions & 1 deletion scripts/packed-packages.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { join, resolve } from 'node:path'
import { createServer } from 'node:http'
import pin from './node-pty.json' with { type: 'json' }
import { ptyFiles, sha256 } from './vendor-pty.mjs'
import { firecrackerFiles, firecrackerHash } from './vendor-firecracker.mjs'

export const root = resolve(new URL('..', import.meta.url).pathname)
export const npm = process.env.TEST_NPM_CLI
Expand Down Expand Up @@ -62,7 +63,10 @@ export function packPackages() {
const [packed] = Array.isArray(result) ? result : Object.values(result)
const tarball = join(dest, packed.filename)
const read = (file) =>
execFileSync('tar', ['-xOf', tarball, `package/${file}`])
execFileSync('tar', ['-xOf', tarball, `package/${file}`], {
// bin/firecracker is 3.6 MB; the default 1 MiB buffer fails.
maxBuffer: 64 * 1024 * 1024,
})
for (const { path } of packed.files) {
if (path.endsWith('package.json'))
noInstallScripts(JSON.parse(read(path)), `${packed.name}/${path}`)
Expand All @@ -84,6 +88,18 @@ export function packPackages() {
(!helper || (helper.mode & 0o111) !== 0o111)
)
throw new Error(`${name}: packed spawn-helper is not executable`)
// Linux x64 ships Firecracker next to gild, with its license files.
const firecracker = packed.files.find(
(file) => file.path === 'bin/firecracker',
)
if (name === 'cli-linux-x64') {
for (const file of Object.keys(firecrackerFiles))
if (sha256(read(file)) !== firecrackerHash(file))
throw new Error(`${name}: packed ${file} hash mismatch`)
if ((firecracker.mode & 0o111) !== 0o111)
throw new Error(`${name}: packed firecracker is not executable`)
} else if (firecracker)
throw new Error(`${name}: firecracker is for linux-x64 only`)
}
packages.set(pkg.name, { pkg, tarball, integrity: packed.integrity })
console.log(
Expand Down
61 changes: 61 additions & 0 deletions scripts/vendor-firecracker.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
// Firecracker (Apache-2.0) ships inside @gildforge/cli-linux-x64 as
// bin/firecracker, next to gild, with its LICENSE, NOTICE and THIRD-PARTY in
// vendor/firecracker/. Only pinned upstream bytes are shipped: the release
// tarball must match both the pin and the sha256 Firecracker publishes for it.
import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
import { join } from 'node:path'
import { execFileSync } from 'node:child_process'
import pin from './firecracker.json' with { type: 'json' }
import { sha256 } from './vendor-pty.mjs'

/** Packaged path -> pinned upstream file in the release tarball. */
export const firecrackerFiles = {
'bin/firecracker': `firecracker-v${pin.version}-x86_64`,
'vendor/firecracker/LICENSE': 'LICENSE',
'vendor/firecracker/NOTICE': 'NOTICE',
'vendor/firecracker/THIRD-PARTY': 'THIRD-PARTY',
}
export const firecrackerHash = (packaged) =>
pin.files[firecrackerFiles[packaged]]

async function download(url) {
const response = await fetch(url)
if (!response.ok) throw new Error(`${url}: ${response.status}`)
return Buffer.from(await response.arrayBuffer())
}

export async function vendorFirecracker(root, packageDir) {
const cache = join(root, '.tmp', `firecracker-${pin.version}`)
mkdirSync(cache, { recursive: true })
const bytes = await download(pin.tarball)
const published = (await download(pin.tarball + '.sha256.txt'))
.toString()
.trim()
.split(/\s+/)[0]
if (published !== pin.sha256)
throw new Error(
`firecracker ${pin.version}: published sha256 ${published} is not the pin`,
)
if (sha256(bytes) !== pin.sha256)
throw new Error(`firecracker ${pin.version}: tarball sha256 mismatch`)
const archive = join(cache, 'release.tgz')
writeFileSync(archive, bytes)
const dir = `release-v${pin.version}-x86_64`
execFileSync('tar', [
'-xzf',
archive,
'-C',
cache,
...Object.keys(pin.files).map((file) => `${dir}/${file}`),
])
for (const [packaged, file] of Object.entries(firecrackerFiles)) {
const content = readFileSync(join(cache, dir, file))
if (sha256(content) !== pin.files[file])
throw new Error(`firecracker ${pin.version}: ${file} hash mismatch`)
const dest = join(packageDir, packaged)
mkdirSync(join(dest, '..'), { recursive: true })
writeFileSync(dest, content)
if (packaged === 'bin/firecracker') chmodSync(dest, 0o755)
}
console.log(`verified firecracker ${pin.version}: linux-x64`)
}
28 changes: 27 additions & 1 deletion src/isolation/firecracker.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { expect, test } from 'bun:test'
import { workImageBytes } from './firecracker'
import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
import { join, resolve } from 'node:path'
import { defaultFirecracker, workImageBytes } from './firecracker'
import { hostConfigSchema } from './index'

test('workspace image sizing stays positive across the signed 32-bit boundary', () => {
expect(workImageBytes(0)).toBe(256 * 1024 ** 2)
Expand All @@ -10,3 +13,26 @@ test('workspace image sizing stays positive across the signed 32-bit boundary',
for (const n of [-1, 0.5, NaN, Infinity, Number.MAX_SAFE_INTEGER])
expect(() => workImageBytes(n)).toThrow()
})

test('Firecracker: isolation.json first, then the one shipped next to gild, then PATH', async () => {
await mkdir(resolve('.tmp'), { recursive: true })
const dir = await mkdtemp(resolve('.tmp/fc-bundled-'))
try {
const gild = join(dir, 'gild')
// Nothing next to gild: PATH.
expect(defaultFirecracker(gild)).toBe('firecracker')
// Present but not executable: still PATH.
await writeFile(join(dir, 'firecracker'), '', { mode: 0o644 })
expect(defaultFirecracker(gild)).toBe('firecracker')
// The npm package's layout: bin/gild and bin/firecracker.
await chmod(join(dir, 'firecracker'), 0o755)
expect(defaultFirecracker(gild)).toBe(join(dir, 'firecracker'))
// isolation.json's own choice wins over the default.
const { vm } = hostConfigSchema(dir).parse({
vm: { firecracker: '/opt/fc/firecracker' },
})
expect(vm!.firecracker).toBe('/opt/fc/firecracker')
} finally {
await rm(dir, { recursive: true, force: true })
}
})
17 changes: 16 additions & 1 deletion src/isolation/firecracker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import {
readFile,
} from 'node:fs/promises'
import { existsSync, accessSync, constants } from 'node:fs'
import { join } from 'node:path'
import { dirname, join } from 'node:path'
import { bootNetArgs, networkState, planNetwork } from './network'
import {
checkGuestProtocol,
Expand Down Expand Up @@ -50,6 +50,21 @@ export interface FirecrackerConfig {

export const GUEST_WORK = '/workspace'

/**
* The Firecracker to run when isolation.json names none: the one shipped next
* to the gild executable (@gildforge/cli-linux-x64 bundles it), else
* `firecracker` on PATH. `vm.firecracker` in isolation.json wins over both.
*/
export function defaultFirecracker(execPath = process.execPath) {
const bundled = join(dirname(execPath), 'firecracker')
try {
accessSync(bundled, constants.X_OK)
return bundled
} catch {
return 'firecracker'
}
}

/** /dev/kvm, Firecracker and mke2fs: what this host needs besides the guest image. */
export function firecrackerHostReady(firecracker: string) {
try {
Expand Down
Loading
Loading