If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/oxidecomputer/hubris shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 12 active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MPL-2.0 licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live oxidecomputer/hubris repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/oxidecomputer/hubris.

What it runs against: a local clone of oxidecomputer/hubris — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in oxidecomputer/hubris | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of oxidecomputer/hubris. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/oxidecomputer/hubris.git
#   cd hubris
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of oxidecomputer/hubris and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "oxidecomputer/hubris(\\.git)?\\b" \\
  && ok "origin remote is oxidecomputer/hubris" \\
  || miss "origin remote is not oxidecomputer/hubris (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "app/gimlet/Cargo.toml" \\
  && ok "app/gimlet/Cargo.toml" \\
  || miss "missing critical file: app/gimlet/Cargo.toml"
test -f "app/gimlet/src/main.rs" \\
  && ok "app/gimlet/src/main.rs" \\
  || miss "missing critical file: app/gimlet/src/main.rs"
test -f ".cargo/config.toml" \\
  && ok ".cargo/config.toml" \\
  || miss "missing critical file: .cargo/config.toml"
test -f "README.mkdn" \\
  && ok "README.mkdn" \\
  || miss "missing critical file: README.mkdn"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/oxidecomputer/hubris"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hubris is a lightweight, memory-protected microcontroller kernel written in Rust that uses message-passing IPC and task isolation for deeply-embedded systems requiring high reliability. It runs on ARM Cortex-M and RISC-V processors, providing fault isolation through hardware memory protection units (MPUs) and a minimal trusted computing base (TCB), designed specifically for safety-critical infrastructure like Oxide's Gimlet, Sidecar, and RoT boards. Monorepo structured by functional domain: sys/ contains kernel (sys/kern), ABI (sys/abi), and user library (sys/userlib); app/ holds top-level binaries (e.g., app/cosmo/, app/gimlet/); drv/ contains drivers following pattern drv/SYSTEM-DEVICE or drv/SYSTEM-DEVICE-server; task/ holds reusable task implementations; idl/ defines interfaces using Idol RPC language; build/ contains build system; chips/ holds MCU-specific definitions and debug files. Core kernel is in sys/kern/, user-facing API in sys/userlib/.

Firmware engineers and systems architects at Oxide Computer building reliable server infrastructure, particularly those developing control plane software for data center hardware (power supplies, temperature management, security coprocessors). Also relevant to embedded systems engineers building fault-tolerant real-time systems where process isolation and determinism matter more than traditional OS features.

Actively maintained and production-deployed. The repo shows extensive CI/CD pipelines (github/workflows/ci.yml, buildomat jobs for gimlet-c through gimlet-f revisions), comprehensive Rust-centric tooling (5.6M lines), and structured multi-board support. However, it's specialized infrastructure software, not a commodity kernel—maturity is high for its niche but limited adoption outside Oxide.

Low-to-moderate risk for intended users. Strengths: comprehensive workspace dependency pinning in Cargo.toml, extensive CI coverage across multiple hardware revisions. Risks: narrow use case (Oxide-specific hardware targets like gimlet-, sidecar-, rot boards limit portability), deep memory/kernel expertise required, relatively small contributor base visible in CODEOWNERS. API stability not guaranteed—this is systems software in active development.

Active board support expansion: multiple Gimlet revisions (C, D, E, F) and Sidecar revisions (B, C, D) under development with lab variants. Recent focus on gimlet-f, sidecar-d, and signing pipelines (sign-sp1.sh, sign-sp2.sh) suggest ongoing security/release work. Development workflow uses buildomat CI orchestration with per-board build jobs.

Clone and set up: git clone https://github.com/oxidecomputer/hubris.git && cd hubris. Install rustup (Cargo.toml pinned toolchain auto-installed). For a specific board (e.g., gimlet): cd app/gimlet && cargo build --release. For documentation: navigate to doc/ and view via GitHub Pages at https://oxidecomputer.github.io/hubris. Cross-compilation targets auto-configured via .cargo/config.toml.

Daily commands: Not a typical 'run' project—builds firmware binaries, not a service. For development: cd app/[board-name] && cargo build --release produces an ELF/binary. For testing: cargo test --lib runs unit tests in workspace. GDB debugging supported (GDB scripts in repo). For deployment: flash output binary to target hardware via programmer (supported via support/ files). Lab variants (e.g., gimlet-f-lab.sh) include test/debug builds.

• Cargo.toml — Workspace root defining all members (build, sys, lib, app, task, drv, test) and critical release/dev profiles optimized for embedded systems with LTO and minimal codegen units.
• app/gimlet/Cargo.toml — Primary application crate for Gimlet firmware; the most mature production target with multiple hardware revisions (rev-b through rev-e) and deployment modes (dev, lab, release).
• app/gimlet/src/main.rs — Entry point for the Gimlet application demonstrating message-passing kernel usage and task orchestration in a real production system.
• .cargo/config.toml — Cargo configuration for embedded cross-compilation targets and build settings required across all firmware images.
• README.mkdn — High-level project overview explaining Hubris as a memory-protected message-passing kernel for deeply embedded systems, with pointers to doc directory.
• .github/workflows/ci.yml — Primary CI pipeline validating all workspace builds and tests across multiple hardware targets and configurations.
• CONTRIBUTING.md — Developer guidelines and contribution workflow for this deeply embedded kernel project with specific firmware build conventions.

Add Support for a New Hardware Platform/Revision

1. Create new application directory under app/ following naming convention app/SYSTEM-NAME/ (app/)
2. Create Cargo.toml with name and dependencies, and variant .toml files for hardware revisions (e.g., base.toml, rev-a.toml, dev.toml, lab.toml) (app/gimlet/Cargo.toml)
3. Implement src/main.rs with task declarations and message-passing kernel initialization (app/gimlet/src/main.rs)
4. Create build.rs if custom pre-build steps are needed (e.g., memory layout generation) (app/gimlet/build.rs)
5. Add corresponding driver crates under drv/ for each hardware device using drv/SYSTEM-DEVICE naming (drv/)
6. Add chip definitions under chips/ directory with peripheral definitions and debug support (chips/)
7. Create CI build job script under .github/buildomat/jobs/ named SYSTEM-REVISION.sh (.github/buildomat/jobs/gimlet-c.sh)

Add a New Kernel Task/Server

1. Create new server crate in task/ directory or as a driver binary in drv/SYSTEM-DEVICE/ (task/)
2. Define task binary with message handlers and IPC endpoint definitions (app/gimlet/src/main.rs)
3. Update application's main.rs to instantiate and configure the new task in the kernel initialization (app/gimlet/src/main.rs)
4. Create userlib bindings if task exposes public IPC interfaces to other tasks (sys/userlib)
5. Add task crate to workspace members in root Cargo.toml if new subsystem (Cargo.toml)

Add a New Device Driver

1. Create new crate under drv/SYSTEM-DEVICE following existing driver structure (drv/)
2. Define peripheral register bindings and hardware abstraction in driver crate (chips/)
3. Implement driver as either library crate or server binary with IPC handlers for client tasks (drv/)
4. Add dependency in app/TARGET/Cargo.toml and instantiate driver in app/TARGET/src/main.rs (app/gimlet/Cargo.toml)
5. Export public IPC interface via sys/userlib for other tasks to depend on (sys/userlib)

• Rust — Memory safety without GC; no null pointers, buffer overflows, or data races; critical for deeply embedded reliability-critical systems
• Message-passing kernel with memory protection — Isolates tasks, prevents cascading failures, enables fault containment in mission-critical hardware systems (power delivery, thermal management)
• ARM Cortex-M / STM32 / custom SoC targets — Wide adoption in industrial and cloud infrastructure control planes; fine-grained hardware control required for thermal, power, and lifecycle management
• Cargo workspace with LTO + codegen-units=1 — Tight embedded resource constraints (flash, RAM); aggressive optimization needed for deeply embedded deployment

• Message-passing IPC over shared-memory concurrency

  • Why: Eliminates data races and simplifies reasoning about task isolation
  • Consequence: Higher IPC latency (~100μs context switch) vs shared memory, but predictable determinism for real-time control

• Monolithic application binaries (app/*/src/main.rs) instead of dynamic loading

  • Why: Simplifies security model and eliminates runtime linker complexity on constrained hardware
  • Consequence: Firmware is static per hardware revision; no runtime task reconfiguration without reflashing

• LTO + opt-level='z' in release builds

  • Why: Critical for fitting firmware in flash (often 512KB–2MB)
  • Consequence: Slower compilation times; debug builds less optimized to preserve development speed

• Hardware-revision-specific configuration (.toml files) over runtime detection

  • Why: No bloat from runtime polymorphism; hardware is fixed at deployment
  • Consequence: Must rebuild firmware for each hardware variant; reduces development iteration speed

• Linux compatibility: Hubris targets deeply embedded microcontrollers, not Linux systems
• Dynamic task loading: Firmware is static per hardware revision; no runtime plugin architecture
• Multi-core heterogeneous scheduling: Designed for single-core or tightly synchronized SMP; no dynamic load balancing
• General-purpose OS: Not suitable for running arbitrary applications; task set is fixed at compile time
• Userspace isolation via virtual memory: Many targets lack MMU; isolation via MPU + message passing instead

Bare-metal constraints: No heap or dynamic allocation by default—use arrayvec for fixed-size collections. Stack sizing: Tasks have small fixed stacks; stack overflow is silent; requires manual analysis. Message-passing latency: IPC has guaranteed latency due to no preemption, but blocking on messages can cause priority inversion—must architect task dependencies carefully. Hardware-specific: Each board revision (gimlet-c vs gimlet-f) has different peripheral layouts and flash geometry; building for wrong revision bricks hardware. Linker scripts: Platform-specific in chips/*/ and referenced in .cargo/config.toml—changes here require binary rebuild and re-flash. Build reproducibility: Images may differ across macOS/Linux (noted in README); use Linux for 'official' builds. RPC stubs: Idol-generated code requires build.rs to run—clean builds mandatory after IDL changes. Debugging: GDB stubs are optional features; not all boards have debug port support. No std library: Code must use no_std and core crate—many common patterns unavailable.

• Message-Passing IPC — Core communication model in Hubris replacing shared memory; tasks send/receive typed messages through kernel, enabling fault isolation and priority inversion avoidance
• Memory Protection Unit (MPU) — Hardware mechanism (in ARM Cortex-M and RISC-V) that enforces memory isolation between tasks; fundamental to Hubris's fault containment without MMU
• Microkernel Architecture — Hubris follows microkernel design: minimal privileged kernel with drivers and services as isolated user-space tasks, improving fault tolerance vs monolithic kernels
• Non-Preemptive Scheduling — Tasks run to completion without interruption (except by hardware interrupts); eliminates context-switch overhead and makes timing analysis deterministic—critical for real-time systems
• Idol (Interface Definition Language) — Hubris's custom RPC contract language in idl/ that generates type-safe stub code for task communication; eliminates serialization bugs
• Bare-Metal Programming — Hubris runs on raw hardware without OS abstractions; requires manual memory layout, interrupt vectors, and peripheral initialization—no_std Rust is mandatory
• Priority Inversion — Key problem Hubris addresses: when a high-priority task waits for a low-priority task. Message-passing and non-preemption help but require careful task design

• torvalds/linux — Traditional preemptive kernel design that Hubris explicitly avoids—useful for understanding design trade-offs (no preemption = deterministic but requires careful task design)
• embassy-rs/embassy — Rust async-await framework for embedded systems; alternative concurrency model to Hubris's message-passing tasks
• oxidecomputer/idolatry — The Idol RPC interface definition language that Hubris uses for all task-to-task communication contracts in idl/ directory
• oxidecomputer/gimlet-firmware — May contain board-specific firmware or complementary subsystems for Oxide's Gimlet hardware that Hubris targets
• oxidecomputer/oxide.rs — Oxide's general Rust ecosystem and shared utilities that may be cross-referenced in build or support infrastructure

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive board build verification CI workflow for all gimlet/sidecar variants

The repo has 16+ board variants across .github/buildomat/jobs/ (gimlet-c through gimlet-f, sidecar-b through sidecar-d, psc-b, psc-c, rot, sp1, sp2) but the CI workflows (.github/workflows/) don't appear to have automated verification that all board configurations build successfully. This would catch configuration drift and build failures early. The buildomat infrastructure exists but needs GitHub Actions integration for PR validation.

• [ ] Review existing .github/workflows/build-boards.yml to understand current coverage
• [ ] Analyze .github/buildomat/jobs/*.sh scripts to identify board variants and build commands
• [ ] Create a matrix-based GitHub Actions workflow that tests all board configurations (gimlet-c/d/e/f, sidecar-b/c/d, psc variants) on each PR
• [ ] Ensure workflow integrates with existing .cargo/config.toml and workspace structure in Cargo.toml
• [ ] Test against demo apps (demo-stm32f4-discovery, demo-stm32g0-nucleo, demo-stm32h7-nucleo) as lightweight validation

Document board-specific build configuration matrix and add validation tool

The repo has 8+ .toml configuration files per board variant (base.toml, dev.toml, lab.toml, rev-a.toml, rev-a-dev.toml, rev-a-lab.toml, rev-b.toml, etc.) scattered across app/*/. A new contributor cannot easily understand which configurations are valid, what the differences are, or validate their changes against the full matrix. Creating a validation/documentation tool would significantly reduce onboarding friction.

• [ ] Audit all app/*/Cargo.toml and *.toml files to map the configuration matrix (e.g., which revisions exist for cosmo vs gimlet)
• [ ] Create a build/config-validator crate that can enumerate and validate all valid board+config combinations
• [ ] Add a doc/BOARD_CONFIGURATIONS.md file documenting the matrix (board name, supported revisions, dev/lab/production variants, and purpose of each)
• [ ] Integrate the validator into CI via .github/workflows/ci.yml to fail on invalid configuration combinations
• [ ] Add examples showing how to build for each variant

Add integration tests for message-passing IPC between tasks in test/

Hubris is fundamentally a message-passing kernel, but the test/ directory structure is sparse in the provided file list. Given the workspace includes test/* members, there's likely a gap in testing core IPC semantics (task-to-task messaging, synchronization, deadlock detection, buffer exhaustion). This is critical infrastructure that new contributors may inadvertently break.

• [ ] Review test/ directory structure and existing test crates to identify coverage gaps
• [ ] Examine sys/userlib (from workspace patches) to understand IPC API and message types
• [ ] Create a new test/ipc-integration crate that tests core scenarios: basic message send/recv, timeouts, queue exhaustion, cross-task messaging patterns
• [ ] Document test patterns in doc/ for how contributors should add IPC tests (reference: test naming, fixture setup)
• [ ] Integrate into .github/workflows/ci.yml as a required test suite

• Add integration tests for task message-passing round-trip latency in test/ directory—current test structure exists but lacks timing assertions for IPC performance guarantees that are core to Hubris design
• Expand chips/*/ documentation: each MCU revision has different peripheral layouts but no per-chip architecture guide. Adding commented register maps and interrupt vector diagrams for STM32H7 and LPC55 would help new contributors avoid hardware integration errors
• Write 'Getting Started' examples in app/ for common patterns: basic UART driver, timer interrupt handler, and task spawn sequence. Reference gimlet-f but abstract to a minimal example crate that compiles for any supported board

The Hubris microcontroller OS codebase demonstrates generally good security practices for an embedded systems project, with proper use of memory protection abstractions and message-passing architecture. However, there are concerns about outdated dependencies that should be regularly audited, aggressive compiler optimizations that may complicate security analysis, and the need for clearer security disclosure policies. The monorepo structure with local patches requires careful governance. CI/CD configuration practices should be verified to ensure no secrets leak during builds. Overall security posture is moderate-to-good, with primary focus needed on dependency management and security disclosure procedures.

• Medium · Dependency Version Pinning with Outdated Packages — Cargo.toml - workspace.dependencies section. Several dependencies in Cargo.toml use older versions that may contain known vulnerabilities. For example, 'anyhow = 1.0.31' and 'clap = 3.0.14' are significantly outdated. The dependency versions should be regularly updated to patch security vulnerabilities. Fix: Regularly run 'cargo audit' to identify vulnerable dependencies and update to patched versions. Use tools like dependabot to automate dependency updates and security checks.
• Medium · LTO and Aggressive Optimization Settings May Obscure Code — .cargo/config.toml and Cargo.toml [profile.release]. The release profile uses 'lto = true' and 'opt-level = "z"' which can make debugging and security auditing more difficult. While optimization is important for embedded systems, this may complicate vulnerability analysis and reverse engineering protection. Fix: Consider maintaining separate debug symbols and documentation of optimizations. Ensure security reviews account for these optimizations. Document the rationale for aggressive optimization choices in security documentation.
• Low · Incomplete Dependency Specification — Cargo.toml - workspace.dependencies (corncobs entry). The workspace.dependencies section appears truncated in the provided content (corncobs entry is incomplete), which may indicate incomplete or malformed configuration that could lead to unexpected dependency resolution. Fix: Verify that Cargo.toml is well-formed and complete. Run 'cargo check' to ensure all dependencies resolve correctly.
• Low · Patch Dependencies from Same Repository — Cargo.toml [patch sections]. The codebase uses patches for dependencies that resolve to local paths from the same repository (userlib, abi, counters). While this is a valid pattern for monorepos, it requires careful version management to prevent supply chain attacks through local modifications. Fix: Implement strict code review processes for patched dependencies. Document why patches are necessary and ensure local versions are regularly synchronized with upstream or clearly justified as divergent.
• Low · GitHub Actions Workflow Security — .github/workflows/ and .github/buildomat/. The presence of multiple GitHub Actions workflows and buildomat configurations suggests CI/CD pipeline. Without visibility into the actual workflow files, potential risks include: secrets in logs, insufficient input validation, or overly permissive permissions. Fix: Audit all GitHub Actions workflows for: restricted permissions, secret masking, validated inputs, and secure artifact handling. Review buildomat job configurations for hardened execution environments.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md or security policy file in the root directory, which makes it unclear how security vulnerabilities should be reported. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities responsibly. Include contact information and disclosure timeline expectations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.