Skip to content

Add Firecracker control-plane preview - #7133

Merged
lpcox merged 3 commits into
mainfrom
lpcox-firecracker-control-plane
Aug 9, 2026
Merged

Add Firecracker control-plane preview#7133
lpcox merged 3 commits into
mainfrom
lpcox-firecracker-control-plane

Conversation

@lpcox

@lpcox lpcox commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Stack

Layer 2/6 of the Firecracker runtime stack.

What this adds

  • Registers canonical firecracker as a microvm runtime with no Docker OCI runtime or host-agent iptables.
  • Adds a cohesive Firecracker v1.16.1 CLI/config/schema surface for binaries, guest artifacts, machine resources, API timeout, preview acknowledgement, and optional SHA-256 pins.
  • Adds a typed Node HTTP client for the Firecracker Unix-socket API.
  • Adds fail-closed Linux/KVM, architecture, binary/version, ownership/permission, artifact, and checksum preflight.
  • Adds jailer-only manager primitives for unique run jails, bounded API readiness, machine/boot/root-drive configuration, and partial-start cleanup.
  • Recognizes Firecracker in primary enclave runtime typing while explicitly rejecting unsupported enclave integration.

Intentionally unavailable

This layer does not implement networking, workspace images, guest agent/vsock command execution, end-to-end main workflow dispatch, or Firecracker enclave executors. Selecting Firecracker remains an explicit preview and fails closed before a workload or infrastructure starts; there is no Docker/runtime fallback.

Validation

  • npm test -- --runInBand src/container-runtime.test.ts src/external-runtime-backend.test.ts src/enclave/runtime-preflight.test.ts src/commands/main-action.test.ts src/firecracker/config.test.ts src/firecracker/api-client.test.ts src/firecracker/preflight.test.ts src/firecracker/manager.test.ts — 101 tests passed
  • npm run type-check
  • npm run build

Copilot AI balanced review requested due to automatic review settings August 9, 2026 01:39
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 8ce2049

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds the fail-closed Firecracker v1.16.1 control-plane preview.

Changes:

  • Registers Firecracker as an external microVM runtime.
  • Adds CLI, configuration, schema, and documentation surfaces.
  • Adds preflight validation, jail management, API client, and tests.
Show a summary per file
File Description
src/types/runtime-options.ts Defines Firecracker options and defaults.
src/types/index.ts Exports Firecracker configuration types.
src/firecracker/preflight.ts Validates host, binaries, artifacts, and checksums.
src/firecracker/preflight.test.ts Tests Firecracker preflight behavior.
src/firecracker/manager.ts Implements jailer lifecycle and VM configuration.
src/firecracker/manager.test.ts Tests jail paths, startup, and cleanup.
src/firecracker/config.test.ts Tests configuration mapping and validation.
src/firecracker/api-client.ts Implements the Unix-socket API client.
src/firecracker/api-client.test.ts Tests API requests and errors.
src/firecracker-runtime-backend.ts Adds the fail-closed runtime backend.
src/external-runtime-backend.test.ts Tests backend resolution.
src/external-runtime-backend-resolver.ts Registers the Firecracker backend.
src/enclave/runtime-preflight.ts Recognizes and rejects unsupported enclave integration.
src/enclave/runtime-preflight.test.ts Tests enclave rejection behavior.
src/container-runtime.ts Registers Firecracker runtime capabilities.
src/container-runtime.test.ts Tests runtime capability resolution.
src/config-mapper.ts Maps file configuration to CLI options.
src/config-file.ts Adds Firecracker config-file typing.
src/commands/build-config.ts Builds normalized Firecracker configuration.
src/cli-options.ts Adds Firecracker CLI flags.
src/awf-config-schema.json Adds runtime schema validation.
docs/awf-config.schema.json Updates the published schema.
docs/awf-config-spec.md Documents the preview configuration.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

  • Files reviewed: 23/23 changed files
  • Comments generated: 7
  • Review effort level: Balanced

Comment on lines +40 to +42
readonly start: WorkflowDependencies['startContainers'] = async () => {
await this.preflight();
throw new Error(FIRECRACKER_INCOMPLETE_CAPABILITY_ERROR);
Comment thread src/firecracker/preflight.ts Outdated
const defaultDependencies: FirecrackerPreflightDependencies = {
platform: process.platform,
arch: process.arch,
uid: process.getuid?.() ?? -1,
Comment on lines +81 to +85
const stat = await dependencies.lstat(filePath);
if (stat.isSymbolicLink() || !stat.isFile()) {
throw new Error(`${label} must be a regular file and not a symbolic link: ${filePath}`);
}
if ((stat.mode & 0o022) !== 0) {
Comment thread src/firecracker/manager.ts Outdated
Comment thread src/firecracker/api-client.ts Outdated
Comment on lines +195 to +199
request.setTimeout(this.timeoutMs, () => {
request.destroy(new Error(
`Firecracker API ${method} ${requestPath} timed out after ${this.timeoutMs}ms`,
));
});
'Content-Length': Buffer.byteLength(body),
},
}, (response) => {
const chunks: Buffer[] = [];
Comment thread src/firecracker/manager.ts Outdated
Comment on lines +227 to +231
if (this.process?.exitCode !== null) {
throw new Error(
`Firecracker jailer exited before API readiness with code ${this.process?.exitCode}`,
);
}
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

✅ Copilot review passed with no inline comments.

@lpcox Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric Base PR Delta
Lines 94.11% 93.61% 📉 -0.50%
Statements 93.10% 92.61% 📉 -0.49%
Functions 94.54% 92.57% 📉 -1.97%
Branches 86.31% 85.41% 📉 -0.90%
📁 Per-file Coverage Changes (3 files)
File Lines (Before → After) Statements (Before → After)
src/commands/build-config.ts 97.2% → 90.0% (-7.22%) 97.2% → 90.4% (-6.84%)
src/enclave/runtime-preflight.ts 64.7% → 67.6% (+2.86%) 66.7% → 70.0% (+3.34%)
src/log-directory-setup.ts 96.2% → 100.0% (+3.78%) 96.3% → 100.0% (+3.71%)
✨ New Files (5 files)
  • src/firecracker-runtime-backend.ts: 82.3% lines
  • src/firecracker/api-client.ts: 76.9% lines
  • src/firecracker/manager.ts: 75.3% lines
  • src/firecracker/preflight.ts: 72.3% lines
  • src/types/runtime-options.ts: 100.0% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

1 similar comment
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric Base PR Delta
Lines 94.11% 93.61% 📉 -0.50%
Statements 93.10% 92.61% 📉 -0.49%
Functions 94.54% 92.57% 📉 -1.97%
Branches 86.31% 85.41% 📉 -0.90%
📁 Per-file Coverage Changes (3 files)
File Lines (Before → After) Statements (Before → After)
src/commands/build-config.ts 97.2% → 90.0% (-7.22%) 97.2% → 90.4% (-6.84%)
src/enclave/runtime-preflight.ts 64.7% → 67.6% (+2.86%) 66.7% → 70.0% (+3.34%)
src/log-directory-setup.ts 96.2% → 100.0% (+3.78%) 96.3% → 100.0% (+3.71%)
✨ New Files (5 files)
  • src/firecracker-runtime-backend.ts: 82.3% lines
  • src/firecracker/api-client.ts: 76.9% lines
  • src/firecracker/manager.ts: 75.3% lines
  • src/firecracker/preflight.ts: 72.3% lines
  • src/types/runtime-options.ts: 100.0% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

@lpcox
lpcox force-pushed the lpcox-firecracker-control-plane branch from 634fde9 to 3f2eb33 Compare August 9, 2026 16:33
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric Base PR Delta
Lines 94.11% 93.61% 📉 -0.50%
Statements 93.10% 92.61% 📉 -0.49%
Functions 94.54% 92.57% 📉 -1.97%
Branches 86.31% 85.41% 📉 -0.90%
📁 Per-file Coverage Changes (3 files)
File Lines (Before → After) Statements (Before → After)
src/commands/build-config.ts 97.2% → 90.0% (-7.22%) 97.2% → 90.4% (-6.84%)
src/enclave/runtime-preflight.ts 64.7% → 67.6% (+2.86%) 66.7% → 70.0% (+3.34%)
src/log-directory-setup.ts 96.2% → 100.0% (+3.78%) 96.3% → 100.0% (+3.71%)
✨ New Files (5 files)
  • src/firecracker-runtime-backend.ts: 82.3% lines
  • src/firecracker/api-client.ts: 76.9% lines
  • src/firecracker/manager.ts: 75.3% lines
  • src/firecracker/preflight.ts: 72.3% lines
  • src/types/runtime-options.ts: 100.0% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

@lpcox

lpcox commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator Author

@copilot address review feedback and resolve merge conflicts

Copilot AI commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

@copilot address review feedback and resolve merge conflicts

Addressed and pushed in 2312538. I resolved the merge conflicts and implemented the Firecracker review fixes (early backend preflight gate, trusted sudo UID handling, parent-path trust checks, jailer ID validation, absolute API timeout + response error handling, and signal-aware jailer readiness exit handling), with targeted tests updated and passing.

@lpcox

lpcox commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator Author

@copilot resolve merge conflicts

Copilot AI commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve merge conflicts

Resolved the merge conflicts and pushed the merge commit (99847160).

Base automatically changed from lpcox-runtime-backend-abstraction to main August 9, 2026 18:34
@lpcox

lpcox commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator Author

@copilot resolve merge conflicts

Copilot AI commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve merge conflicts

I checked and there are no active merge conflicts now. The branch is mergeable (PR merge ref pull/7133/merge resolves successfully), so no additional conflict-resolution commit is needed.

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Build Test Suite completed successfully!

Generated by Build Test Suite for #7133

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Contribution Check failed. Please review the logs for details.

Generated by Contribution Check for #7133

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

🔌 Smoke Services — All services reachable! ✅

🔌 Service connectivity validated by Smoke Services

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Claude passed

Generated by Smoke Claude for #7133

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

🛡️ Smoke Copilot Network Isolation confirmed the egress allowlist is enforced. ✅

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

  • example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

🛡️ Egress verdict from Smoke Copilot Network Isolation

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Copilot BYOK AOAI (Entra) reports failed. AOAI BYOK (Entra) mode investigation needed...

🪪 BYOK (AOAI Entra) report filed by Smoke Copilot BYOK AOAI (Entra)

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Copilot BYOK AOAI (api-key) reports failed. AOAI BYOK (api-key) mode investigation needed...

🔑 BYOK (AOAI api-key) report filed by Smoke Copilot BYOK AOAI (api-key)

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Copilot BYOK (Direct) Mode

Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY) via api-proxy → api.githubcopilot.com

Overall: PASS

cc @lpcox

🔑 BYOK report filed by Smoke Copilot BYOK
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Claude Engine Validation

Check Status
API ✅ PASS
gh CLI ✅ PASS
File ✅ PASS

Overall result: PASS

Generated by Smoke Claude for #7133 · haiku45 · 59.7 AIC · ⊞ 3.6K ·
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Copilot Engine@lpcox

Overall: PASS

📰 BREAKING: Report filed by Smoke Copilot
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

EGRESS_RESULT allow=pass deny=pass

✅ Allowed domain (github.com) reachable: allowed=200
✅ Blocked domain (example.com) denied: CONNECT 403, blocked as expected

Overall status: PASS

cc @lpcox

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

  • example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

🛡️ Egress verdict from Smoke Copilot Network Isolation
Add label ready-for-aw to run again

@github-actions github-actions Bot added the smoke-copilot-network-isolation Copilot network-isolation egress smoke test label Aug 9, 2026
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test Results

  • Redis PING: ❌ (Temporary failure in name resolution)
  • PostgreSQL pg_isready: ❌ (no response)
  • PostgreSQL SELECT 1: ❌ (could not translate host name)

Overall: FAILhost.docker.internal did not resolve from the AWF sandbox.

🔌 Service connectivity validated by Smoke Services
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Gemini Engine Smoke Test Results:

Overall status: FAIL

💎 Faceted by Smoke Gemini
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: API Proxy OTel Tracing — all scenarios pass ✅

  • Module Loading: otel.js loads successfully, isEnabled() → true, exports include startRequestSpan, setTokenAttributes, setBudgetAttributes, endSpan, endSpanError, shutdown, isEnabled, plus internal helpers (_provider, _ProxyAwareOtlpExporter, _FileSpanExporter, _FanOutSpanExporter, _parseEndpoints, _parseOtlpHeaders, _buildResourceSpans, _createOtlpWorkloadIdentity).
  • Test Suite: 3 suites / 68 tests passed (otel.test.js, otel-fanout.test.js, otel-workload-identity.test.js).
  • Env Var Forwarding: env-passthrough.ts forwards GITHUB_AW_OTEL_TRACE_ID/GITHUB_AW_OTEL_PARENT_SPAN_ID to the agent; api-proxy-env-config.ts forwards GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_ENDPOINT, and the same trace context vars to the api-proxy container.
  • Token Tracker Integration: token-tracker-http.js contains the onUsage callback hook point (4 references) used by OTEL to set gen_ai.usage.* span attributes.
  • OTEL Diagnostics: no otel.jsonl span file present (expected — no OTLP endpoint configured for this run, so tracing gracefully no-oped); token-usage.jsonl present with 6 records, confirming baseline token tracking is unaffected.

No regressions or unexpected failures detected.

📡 OTel tracing validated by Smoke OTel Tracing
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Chroot Version Comparison

Runtime Host Version Chroot Version Match?
Python Python 3.12.13 Python 3.12.13 ✅ YES
Node.js v24.18.0 v22.23.2 ❌ NO
Go go1.22.12 go1.22.12 ✅ YES

Overall: FAILED — Node.js version mismatch between host and chroot environment. smoke-chroot label not applied.

Tested by Smoke Chroot
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

🏗️ Build Test Suite Results

Ecosystem Project Build/Install Tests Status
Bun elysia 1/1 passed ✅ PASS
Bun hono 1/1 passed ✅ PASS
C++ fmt N/A ✅ PASS
C++ json N/A ✅ PASS
Deno oak N/A 1/1 passed ✅ PASS
Deno std N/A 1/1 passed ✅ PASS
.NET hello-world N/A ✅ PASS
.NET json-parse N/A ✅ PASS
Go color passed ✅ PASS
Go env passed ✅ PASS
Go uuid passed ✅ PASS
Java gson passed ✅ PASS
Java caffeine passed ✅ PASS
Node.js clsx passed ✅ PASS
Node.js execa passed ✅ PASS
Node.js p-limit passed ✅ PASS
Rust fd 1/1 passed ✅ PASS
Rust zoxide 1/1 passed ✅ PASS

Overall: 8/8 ecosystems passed — PASS

All 18 projects across all 8 language ecosystems built and tested successfully through the AWF firewall.

Note: Java builds initially failed due to a stale ~/.m2/settings.xml from a prior run missing proxy config; regenerating it with the required Squid proxy entries resolved the issue and both gson and caffeine compiled and tested successfully afterward.

Generated by Build Test Suite for #7133 · auto · 47.8 AIC · ⊞ 11.5K ·
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Docker Sbx@lpcox

  • ✅ GitHub MCP connectivity (PR list fetched)
  • ✅ github.com connectivity (HTTP 200)
  • ✅ File write/read test (file confirmed on disk)

Overall: PASS

📰 BREAKING: Report filed by Smoke Docker Sbx
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Smoke test: FAIL

PR titles:

  • Drive Google provider adapters (Gemini, Vertex) from declarative specs
  • Confirm --allow-host-ports works standalone with --enable-host-access in strict security mode
  • [docs] auth: Mark gh-aw#50053 MCP OIDC boundary work as resolved
  • Complete Firecracker preview rollout coverage and distribution

GitHub reads ✅ | Playwright ✅ | File write/read ✅ | Discussion comment ❌ | Build ❌
Overall status: FAIL
Build notes: npm ci hits Squid 403 on npm audit; npm run build fails on missing jest/node types and removed moduleResolution=node10.

Warning

Firewall blocked 5 domains

The following domains were blocked by the firewall during workflow execution:

  • msfeed12.pkgs.visualstudio.com
  • msfeed17.pkgs.visualstudio.com
  • msfeed2.pkgs.visualstudio.com
  • msfeed25.pkgs.visualstudio.com
  • registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "msfeed12.pkgs.visualstudio.com"
    - "msfeed17.pkgs.visualstudio.com"
    - "msfeed2.pkgs.visualstudio.com"
    - "msfeed25.pkgs.visualstudio.com"
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
Add label ready-for-aw to run again

@lpcox
lpcox merged commit 8da01a6 into main Aug 9, 2026
136 of 142 checks passed
@lpcox
lpcox deleted the lpcox-firecracker-control-plane branch August 9, 2026 19:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants