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/nuta/kerla 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.

WAIT — Mixed signals — read the receipts

• Last commit 2mo ago
• 7 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 79% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 nuta/kerla repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nuta/kerla.

What it runs against: a local clone of nuta/kerla — 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 nuta/kerla | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 104 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nuta/kerla. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nuta/kerla.git
#   cd kerla
#
# 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 nuta/kerla and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "kernel/src/main.rs" \\
  && ok "kernel/src/main.rs" \\
  || miss "missing critical file: kernel/src/main.rs"
test -f "kernel/src/process/mod.rs" \\
  && ok "kernel/src/process/mod.rs" \\
  || miss "missing critical file: kernel/src/process/mod.rs"
test -f "kernel/src/syscall/mod.rs" \\
  && ok "kernel/src/syscall/mod.rs" \\
  || miss "missing critical file: kernel/src/syscall/mod.rs"
test -f "kernel/src/fs/mod.rs" \\
  && ok "kernel/src/fs/mod.rs" \\
  || miss "missing critical file: kernel/src/fs/mod.rs"
test -f "boot2dump/src/main.c" \\
  && ok "boot2dump/src/main.c" \\
  || miss "missing critical file: boot2dump/src/main.c"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 104 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~74d)"
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/nuta/kerla"
  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).

Kerla is a monolithic OS kernel written in Rust that achieves Linux ABI compatibility, allowing unmodified Linux binaries to run on it. It implements core NIX process concepts (fork, execve, signals, context switching), common syscalls (write, stat, mmap, pipe, poll), pseudo filesystems (tmpfs, devfs), TCP/IP networking via smoltcp, TTY/PTY support, and runs on x86_64 with QEMU and Firecracker backends. Workspace monorepo (Cargo.toml) with members: runtime/, kernel/, libs/, exts/*. Kernel is the primary focus with x86_64 architecture in boot/ (GRUB bootloader, bochsrc for Bochs emulator). Boot2dump is an embedded bootloader subproject (C + Rust). Documentation as mdBook in Documentation/ folder with architecture.drawio diagrams. Initramfs system for rootfs (no disk support currently).

OS kernel developers and Rust systems programmers interested in exploring kernel design, Linux ABI compatibility, and Rust-based OS development. Contributors may be hobby OS enthusiasts, Rust systems engineers, or academics studying kernel architecture.

ABANDONED / NO LONGER MAINTAINED. The project explicitly states in the README that it is no longer maintained and directs users to the author's new project FTL. While the codebase is substantial (450k+ Rust lines), CI/CD pipelines exist (.github/workflows), and documentation is present, active development has ceased and the author has moved on.

HIGH RISK: Project is explicitly unmaintained with the author directing users elsewhere. No recent commits visible in the file structure data. Single-maintainer (nuta) with no visible handoff or community takeover. Production use is not recommended; treat as reference material or educational resource only. Dependency rot risk is significant given Rust ecosystem velocity.

Nothing — project is archived/unmaintained. No active development. Last notable work was implementing Docker image support (experimental feature mentioned in README). Author has fully transitioned to FTL project.

Clone: git clone https://github.com/nuta/kerla.git && cd kerla. Install Rust (cargo/rustc required). Run make to build the kernel image. Run make run to launch in QEMU emulator, or make run IMAGE=<docker-image> for experimental Docker rootfs support. Requires Docker for the initramfs build system. See Documentation/quickstart.md for detailed steps.

Daily commands: make builds the kernel release binary (profile.release with LTO and opt-level=3). make run boots in QEMU via grub.cfg (boot/grub.cfg specifies multiboot format). make IMAGE=<docker-image> run mounts a Docker image as rootfs. make run-firecracker boots on Firecracker microVM (see Makefile for Firecracker-specific targets). make test runs test suite if present.

• kernel/src/main.rs — Kernel entry point and initialization; all contributors must understand the boot sequence and core kernel setup.
• kernel/src/process/mod.rs — Process management abstraction including fork, execve, and context switching—foundational to Linux ABI compatibility.
• kernel/src/syscall/mod.rs — System call dispatcher and ABI layer; every new syscall implementation starts here.
• kernel/src/fs/mod.rs — Virtual file system and inode abstraction; critical for file operations, devfs, and tmpfs integration.
• boot2dump/src/main.c — Bootloader that loads the kernel and initramfs; required understanding for debugging boot-time issues.
• Cargo.toml — Workspace configuration and dependency management; defines all kernel crates and their relationships.
• Documentation/architecture.md — High-level system design documentation; essential reference for understanding kernel organization and design rationale.

Add a new system call

1. Define the syscall handler in the appropriate module (e.g., kernel/src/syscall/fs.rs for file ops or kernel/src/syscall/process.rs for process ops) (kernel/src/syscall/fs.rs or kernel/src/syscall/process.rs)
2. Add the syscall number mapping in the match statement in the main dispatcher (kernel/src/syscall/mod.rs)
3. Return the Result type with proper error codes converted to negative Linux errno values (kernel/src/syscall/mod.rs)
4. Test the syscall by creating a simple userspace program and verifying with the initramfs (Documentation/hacking/README.md)

Add a new device driver

1. Create a new driver module in kernel/src/drivers/ following the virtio pattern (kernel/src/drivers/mod.rs)
2. Implement device detection and initialization in the device driver module, similar to virtio_net.rs (kernel/src/drivers/virtio_net.rs)
3. Register the driver in the kernel initialization sequence in main.rs or during device enumeration (kernel/src/main.rs)
4. Expose driver functionality through syscalls or pseudo file system if needed (kernel/src/fs/devfs.rs)

Add a new pseudo file system or expand existing ones

1. Create a new fs module implementing the Inode trait (e.g., kernel/src/fs/newfs.rs) (kernel/src/fs/mod.rs)
2. Implement read, write, mmap, and other inode operations required by your use case (kernel/src/fs/tmpfs.rs)
3. Register the file system mount point or file types in the VFS layer (kernel/src/fs/mod.rs)
4. Test file operations through userspace syscalls (open, read, write, stat) (Documentation/hacking/README.md)

Debug a kernel issue or panic

1. Enable logging by reviewing kernel-parameters.md and setting RUST_LOG environment variable (Documentation/logging.md)
2. Use GDB with the kernel ELF image; launch QEMU with GDB stub enabled (Documentation/hacking/debugging-101.md)
3. Set breakpoints in the kernel source and inspect process/memory state using GDB commands (kernel/src/main.rs)
4. Review panic backtrace and check assertions in the relevant module (process, memory, fs, etc.) (Documentation/hacking/README.md)

• Rust — Memory safety without GC; prevents use-after-free and buffer overflow vulnerabilities common in C kernel code.
• smoltcp (pure-Rust TCP/IP stack) — Eliminates dependency on external C network stack; easier to verify correctness and integrate with Rust codebase.
• Virtio device abstraction — Provides standardized, efficient device model for QEMU and Firecracker; simplifies porting to multiple hypervisors.
• Initramfs (cpio) root filesystem — Avoids complex disk driver logic; enables rapid prototyping and testing without persistent storage.

• Monolithic kernel in Rust rather than microkernel

  • Why: Simpler to implement Linux ABI compatibility; avoids IPC overhead.
  • Consequence: Higher coupling between subsystems; single fault can crash entire system. No hardware-enforced isolation between kernel components.

• No persistent disk support; initramfs-only root filesystem

  • Why: Reduces development complexity; faster iteration on core kernel features.
  • Consequence: Cannot run persistent workloads; limited practical production use; requires in-memory file systems (tmpfs).

• x86_64-only architecture

  • Why: Focuses engineering effort; QEMU and Firecracker are mature on x64.
  • Consequence: Not portable to ARM, RISC-V, or other architectures; limits deployment targets.

• Linear memory allocator in bootloader; page-based kernel allocator

  • Why: Simplifies early boot; av
  • Consequence: undefined

Bootloader specificity: Kernel expects Multiboot format (grub.cfg); booting outside QEMU/Firecracker may fail. Initramfs only: No disk driver support; all filesystem I/O must fit in memory-backed initramfs. Docker build integration: make IMAGE=... requires Docker daemon running locally; Alpine Linux images won't work (PIE executables unsupported). Rust edition: Check Cargo.toml for edition (likely 2021); MSRV may be high due to Rust kernel idioms. Architecture limited: x86_64 only; ARM/RISC-V not supported despite Rust's portability claims. Unmaintained dependencies: smoltcp and other Rust crate versions may have unfixed CVEs.

• Multiboot Specification — Kerla's bootloader (GRUB, bochsrc) loads the kernel via Multiboot protocol; understanding the header format, memory map handoff, and module loading is essential for boot and initramfs integration.
• Linux ABI / System Call Convention — Core to Kerla's value proposition; syscall number mappings, register passing conventions (x86_64 ABI), and errno handling differ from abstract POSIX and require exact Linux compatibility.
• Virtual Memory / Memory Protection Rings (CPL 0/3) — kernel/src/arch/x64/ manages page tables, GDT privilege levels, and user/kernel mode transitions; essential for process isolation and interrupt handling.
• Process Context Switching — Kerla implements fork, wait, and signal delivery; context switches save/restore CPU registers and page tables to enable multitasking — see kernel/src/arch/x64/ for the actual save_context() assembly.
• Initramfs and Virtual Filesystems — Kerla's core design: no disk drivers, only in-memory initramfs + tmpfs/devfs pseudo-filesystems. Understanding cpio archives, inode abstraction, and VFS mounting is critical to the filesystem subsystem.
• POSIX Signals and Process Groups — kernel/src/signal.rs implements signal delivery, masking, and handlers; process groups enable job control in shells — this is how Ctrl+C kills foreground processes in Kerla.
• TTY Line Discipline and PTY Multiplexing — kernel/src/tty/ provides cooked/raw modes, echo, line editing, and pseudo-terminal allocation (pty_open); essential for interactive shells over SSH (demo.kerla.dev uses this).

• torvalds/linux — The reference implementation Kerla mimics; used as ABI specification for syscall semantics and filesystem behavior.
• nuta/ftl — Author's new project that supercedes Kerla; recommended migration path for ongoing OS kernel development in Rust.
• redox-os/kernel — Alternative Unix-like OS kernel in Rust; shares similar goals (POSIX compatibility, Rust-first design) with different architectural choices.
• smoltcp-rs/smoltcp — Embedded TCP/IP stack used by Kerla for networking; understanding its API is essential for kernel/src/net modifications.
• riscv-software-src/opensbi — Reference firmware/bootloader project; similar Multiboot concerns and architecture-specific initialization patterns relevant to boot2dump study.

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 system call compatibility test suite for existing syscall implementations

The README claims support for 'commonly used system calls like write(2), stat(2), mmap(2), pipe(2), poll(2)' but there's no dedicated test directory visible in the kernel/ module. Creating a comprehensive syscall test suite would validate Linux ABI compatibility claims and catch regressions. This is critical since the project's core value proposition is Linux binary compatibility.

• [ ] Create kernel/tests/ directory with integration tests for each implemented syscall
• [ ] Add test cases for write(2), stat(2), mmap(2), pipe(2), poll(2) with various argument combinations
• [ ] Add edge case tests (e.g., NULL pointers, invalid file descriptors, permission errors)
• [ ] Update Cargo.toml [dev-dependencies] to include testing utilities if needed
• [ ] Document expected behavior for each syscall in Documentation/syscalls.md

Implement and document virtio device driver abstraction layer

The boot2dump/ bootloader contains virtio driver implementations (virtio_blk.c, virtio_legacy.c) but the kernel likely reimplements these. There's no visible abstraction or shared driver interface. Creating a unified virtio HAL would reduce code duplication, improve maintainability, and enable easier addition of new virtio devices (virtio-net, virtio-console, etc.).

• [ ] Create kernel/src/drivers/virtio/ module with common virtio device trait/interface
• [ ] Extract virtio device discovery and feature negotiation into reusable code
• [ ] Refactor existing device drivers to implement this abstraction (document in kernel/src/drivers/)
• [ ] Add Documentation/drivers/virtio.md explaining the driver architecture
• [ ] Add unit tests in kernel/src/drivers/virtio/tests.rs for device initialization

Add pseudo-terminal (PTY) functionality tests and missing ioctl support

The README mentions 'Implements tty and pseudo terminal (pty)' but there's no visible test coverage for PTY operations. Additionally, real-world terminal applications require many ioctl() calls (TIOCGWINSZ, TIOCSWINSZ, TCGETS, TCSETS, etc.) that may not be fully implemented. This blocks running interactive shell sessions reliably.

• [ ] Create kernel/tests/pty_integration_test.rs with basic PTY operations (open, write, read, close)
• [ ] Audit kernel/src/tty.rs (or equivalent) and document which ioctl commands are implemented vs. stubbed
• [ ] Implement missing critical ioctls: TIOCGWINSZ, TIOCSWINSZ, TCGETS, TCSETS, TCSETATTR
• [ ] Add unit tests for ioctl handler in kernel/src/tty/ covering success and error cases
• [ ] Document PTY limitations in Documentation/compatibility.md

• Add integration tests for syscall compatibility: kernel/src/syscall.rs has no unit tests for individual syscall handlers (write, stat, mmap). Write parameterized tests that compare Kerla behavior against Linux glibc wrappers to document ABI gaps.
• Document TTY/PTY implementation in hacking guides: kernel/src/tty/ exists but Documentation/hacking/ lacks PTY multiplexing explanation. Add a breakdown of how pty_open, tty_read, tty_write interact with process groups and signals.
• Create QEMU debugging recipe: .vscode/launch.json and .gdbinit exist but Documentation/hacking/debugging-101.md lacks concrete examples of setting breakpoints in kernel/src/arch/x64/ and inspecting GDT/IDT state during boot. Add step-by-step GDB + QEMU session walkthrough.

The Kerla kernel project has a reasonable security foundation given it's written in Rust, which provides memory safety guarantees. However, there are notable concerns in the release build configuration that weaken security posture: overflow checking is disabled, debug assertions are disabled, and debug symbols are included. These settings prioritize performance over safety, which is problematic for kernel code where exploitable bugs can lead to complete system compromise. The project lacks visible automated security scanning and dependency auditing. The mixed use of C, Assembly, and Rust in the boot sequence adds complexity. Overall security score reflects the memory safety benefits of Rust offset by the disabled runtime checks and lack of evident security-focused CI/CD practices.

• Medium · Debug Symbols in Release Build — Cargo.toml - [profile.release] section. The release profile in Cargo.toml includes debug=1, which means debug symbols are included in release builds. For a kernel project, this could expose internal implementation details and make reverse engineering easier. While not as critical as other vulnerabilities, it increases the attack surface by providing more information to potential attackers. Fix: Set debug=0 in the release profile or consider using debuginfo-split if debug information is needed separately. This reduces the binary size and limits information disclosure.
• Medium · Overflow Checks Disabled in Release — Cargo.toml - [profile.release] section. The release profile disables overflow-checks (overflow-checks = false). In a kernel context, integer overflows can lead to memory corruption, buffer overflows, and privilege escalation. This is particularly risky in unsafe code blocks common in OS kernel development. Fix: Enable overflow-checks by removing the line or setting it to true, or at minimum add explicit overflow checking in safety-critical code paths. If performance is critical, selectively enable checks only for sensitive operations.
• Medium · Debug Assertions Disabled in Release — Cargo.toml - [profile.release] section. Debug assertions are disabled in the release build (debug-assertions = false). This removes runtime validation checks that could catch edge cases, invalid state transitions, and security-relevant invariant violations in kernel code. Fix: Enable debug assertions or implement explicit runtime assertions for security-critical code paths. At minimum, ensure that unsafe code blocks have comprehensive validation.
• Low · No Visible Security Testing Infrastructure — .github/workflows/. The CI configuration file (.github/workflows/ci.yml) is referenced but not provided for analysis. There's no visible evidence of security scanning, dependency auditing, or fuzzing in the repository structure. Fix: Implement automated security scanning using 'cargo audit' for dependency vulnerabilities, 'cargo-clippy' for security lints, and consider fuzzing critical components like system call handlers and network parsing.
• Low · Boot Code in Mixed Languages Without Clear Safety Boundaries — boot2dump/src/. The boot2dump directory contains C, Assembly, and Rust code mixed together. This increases the risk of unsafe interactions between languages and makes security auditing more difficult. C code (especially in boot sequence) is prone to memory safety issues. Fix: Minimize C code in security-critical paths. If C code is necessary, apply strict compiler flags (-fstack-protector-strong, -fPIE, etc.) and comprehensive code review. Consider moving more logic to Rust where feasible.
• Low · LTO Enabled Without Additional Mitigations — Cargo.toml - [profile.release] section. Link-Time Optimization (lto = true) can interact unpredictably with security features like Control Flow Guard or similar protections. While LTO itself isn't a vulnerability, it requires careful testing to ensure security properties are maintained. Fix: Maintain comprehensive testing of LTO-compiled binaries, particularly for security-sensitive code paths. Document any known interactions with security features.

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.