Red Bear OS
Microkernel operating system in Rust — based on Redox OS
---
Red Bear OS is a derivative of [Redox OS](https://www.redox-os.org) — a general-purpose, Unix-like, microkernel-based operating system written in Rust. It is a full fork based on frozen Redox snapshots, adding custom drivers, filesystems, and hardware support.
RedBearOS is a **full fork** of Redox OS — based on frozen, archived source snapshots at release 0.1.0.
- Redox is upstream
- Red Bear carries integration, packaging, validation, and subsystem release fork on top
- upstream-owned source trees are immutable archived release snapshot
- durable Red Bear state belongs in `local/patches/`, `local/recipes/`, `local/docs/`, and tracked
Red Bear configs
Operational resilience policy:
- package/source usage is local-first by default,
- local copies are used continuously for builds and recovery workflows,
- upstream package immutable archived is performed only when explicitly requested.
For **upstream WIP recipes specifically**, Red Bear uses a stricter rule:
1. once an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a local project
2. we copy, fix, validate, and ship that work from our local release fork until it is stable enough for us
3. we continue updating our local copy from upstream WIP work when useful, but we do not rely on the
upstream WIP recipe itself as our shipped source of truth
4. once upstream removes the WIP status and the recipe/subsystem becomes a first-class supported
part of Redox, Red Bear reevaluates and should prefer the upstream version over the local copy
That policy exists so the project can pull immutable archived upstream sources regularly and still rebuild
predictably from the Red Bear-owned release fork.
## What's New
- KWin Wayland is now treated as the only intended Red Bear desktop direction in the tracked plans, build defaults, live profile wiring, and profile guidance.
- KDE bring-up moved forward: the `redbear-full` desktop-capable surface carries the Qt6/KDE stack in-tree, and the KDE recipe tree is now populated.
- Native Red Bear runtime tooling expanded with `redbear-info`, `redbear-hwutils` (`lspci`, `lsusb`), and a Redox-native `netctl` flow.
- Build and status docs were immutable archived to distinguish current in-tree progress from older historical roadmap text.
See [CHANGELOG.md](./CHANGELOG.md) for the running user-visible change log.
The current public roadmap and execution model live in the
[Red Bear OS Implementation Plan](./docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md).
For readers landing on GitHub, the most useful entry points are:
- [Documentation Index](./docs/README.md) — canonical map of current vs historical docs
- [Console to KDE Desktop Plan](./local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — **canonical comprehensive implementation plan**: kernel→DRM→Mesa→Wayland→KDE, all blockers, honest assessment
- [Kernel IPC Credential Plan](./local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md) — kernel credential syscalls, IPC, RLIMIT (Phases K1-K2,K4 complete)
- [relibc IPC Assessment and Improvement Plan](./local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md) — IPC-focused companion plan for bounded relibc compatibility layers
- [Script Behavior Matrix](./local/docs/SCRIPT-BEHAVIOR-MATRIX.md) — what the main sync/fetch/apply/build scripts do and do not guarantee
Current subsystem-specific plans also include:
- [USB Implementation Plan](./local/docs/USB-IMPLEMENTATION-PLAN.md)
- [Wi-Fi Implementation Plan](./local/docs/WIFI-IMPLEMENTATION-PLAN.md)
- [Bluetooth Implementation Plan](./local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md)
- [IRQ and Low-Level Controllers Enhancement Plan](./local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) — canonical plan for PCI interrupt plumbing, IRQ delivery quality, MSI/MSI-X follow-up, and low-level controller runtime proof
Red Bear OS now treats AMD and Intel machines as equal-priority hardware targets. Older AMD-first
language in historical integration notes should be read as earlier sequencing context, not as the
current platform policy.
The tracked desktop-capable target surface is `redbear-full`, and
runtime support claims remain evidence-qualified until compositor/session proof is stronger.
## Historical Phase Snapshot
The table below is a legacy P0-P6 snapshot retained for historical continuity with older Red Bear
status notes.
It is **not** the canonical execution-order source for current subsystem planning. For the current
repo-wide order of implementation — including low-level controllers, USB, Wi‑Fi, and Bluetooth as
first-class subsystem workstreams — use
[docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md](./docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) together
with the subsystem plans listed above.
| Phase | Status | Notes |
|---|---|---|
| P0 ACPI boot | ✅ Materially complete (historical boot baseline) | In-tree; remaining work tracked in `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| P1 driver infra | ✅ Complete (compile-oriented) | shared driver infrastructure is present, but low-level PCI/IRQ robustness and runtime proof remain governed by `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` |
| P2 DRM / display | 🚧 Partial | redox-drm + bounded AMD display glue build; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); hardware validation still pending |
| P3 POSIX + input | 🚧 In progress | relibc now has strict Redox-target runtime proof for `signalfd` / `timerfd` / `eventfd` through the repaired test runner; broader desktop/runtime hardening still continues |
| P4 Wayland runtime | 🚧 In progress | bounded Wayland runtime validation builds to a bootable image and reaches its packaged runtime entrypoint in QEMU/UEFI |
| P5 desktop/network plumbing | 🚧 In progress | `redbear-full` now carries the native VirtIO networking path plus D-Bus system-bus plumbing as a broader integration slice, and the guest-side runtime check reaches `DBUS_SYSTEM_BUS=present` |
| P6 KDE Plasma | 🚧 In progress | Mix of real builds, blocked by QML gates, and stubs |
There is no distinct first-class **P7** artifact in this older historical numbering. The canonical
current execution plan uses the newer phased/workstream ordering documented in `docs/07`.
## First-class subsystem order and blockers
The current subsystem order is not arbitrary.
- **Low-level controllers / IRQ quality** are first-class because they block reliable driver/runtime validation.
- **USB** is first-class because Bluetooth and wider device support depend on controller and hotplug maturity.
- **Wi-Fi** is first-class because Red Bear still lacks any native wireless driver/control plane.
- **Bluetooth** is first-class because broad support is still incomplete, depends on USB maturity or
another controller path, and currently exists only as one bounded BLE-first experimental slice
rather than broad desktop parity.
The current blocker chain is:
`low-level controllers -> USB -> Bluetooth`
and, separately:
`low-level controllers -> Wi-Fi driver bring-up -> native wireless control plane -> desktop compatibility later`
These subsystems are all intended to be implemented in full, but they must be executed in this order
to avoid building desktop-facing layers on top of missing runtime substrate.
The current total order is: low-level controllers first, then USB, then Wi-Fi, then Bluetooth, and
only after those runtime services are credible should heavier desktop/session compatibility layers
expand on top of them.
For PCI, IRQ, MSI/MSI-X, and IOMMU quality specifically, the canonical current plan is
`local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`.
Current validation language should be read this way:
- compile-visible infrastructure is not the same as runtime proof,
- bounded QEMU/runtime proof is not the same as hardware validation,
- and PCI/IRQ robustness claims should stay evidence-qualified until broader hardware proof exists.
## What's Different from Upstream Redox
| Component | Status | Detail |
|-----------|--------|--------|
| AMD GPU driver (amdgpu) | 🚧 Bounded path builds | redox-drm + Red Bear AMD display glue compile; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); quirk-aware MSI-X/MSI/legacy IRQ fallback present (no HW validation) |
| Intel GPU driver | ✅ Compiles | Display pipe modesetting + quirk-aware MSI-X/MSI/legacy IRQ fallback (no HW validation) |
| ext4 filesystem | ✅ Compiles | Read/write ext4 alongside RedoxFS |
| ACPI boot baseline | ✅ Materially complete (historical boot baseline) | x2APIC, MADT, FADT shutdown/reboot, explicit `RSDP_ADDR` forwarding into `acpid`, x86 BIOS-search AML fallback, power methods, and bounded AML-backed power enumeration exist; the explicit AML bootstrap producer contract, shutdown robustness, sleep-state scope, and validation depth still remain open — see `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| Wired networking | 🚧 Improved | native net stack present, Redox-native `netctl` shipped, RTL8125 autoload wired through the existing Realtek path |
| Custom branding | ✅ | Boot identity, hostname, os-release |
| POSIX gaps (relibc) | 🚧 In progress | the active relibc recipe patch chain provides bounded Wayland-facing and IPC-facing compatibility layers, but broad runtime trust and several completeness gaps remain open |
## Project Structure
```
├── config/ # Build configs (TOML) — desktop, minimal, redbear-*
├── recipes/ # Package recipes (~100+ packages, 26 categories)
├── mk/ # Makefile build orchestration
├── src/ # Cookbook Rust tool (repo binary, cook logic)
├── local/ # ← Red Bear OS custom work (survives source provisioning)
│ ├── patches/ # Kernel, base, relibc patches
│ ├── recipes/ # Custom packages (drivers, GPU, system, branding)
│ ├── scripts/ # provision-release.sh, check-upstream-releases.sh
│ ├── Assets/ # Branding (icon, boot background)
│ └── docs/ # Integration documentation
├── docs/ # Architecture guides
├── scripts/ # Helper scripts
└── Makefile # Root build orchestrator
```
## Build
Requires a Linux x86_64 host with Rust nightly, QEMU, and standard build tools. See the [Redox Build Instructions](https://doc.redox-os.org/book/podman-build.html) for full prerequisites.
```bash
# Non-live (harddrive.img for QEMU / development)
make all CONFIG_NAME=redbear-full # Desktop/graphics target
make all CONFIG_NAME=redbear-mini # Text-only console/recovery target
# Live ISO (for real bare metal)
make live CONFIG_NAME=redbear-full # Full desktop live ISO
make live CONFIG_NAME=redbear-mini # Text-only mini live ISO for recovery
make live CONFIG_NAME=redbear-grub # Text-only mini live ISO with GRUB
# Or use the helper script
scripts/build-iso.sh redbear-full # Full desktop live ISO
scripts/build-iso.sh redbear-mini # Text-only mini (default)
scripts/build-iso.sh redbear-grub # Text-only + GRUB
# QEMU (uses harddrive.img, not live ISO)
make qemu CONFIG_NAME=redbear-full # Boot the desktop target in QEMU
```
Live `.iso` outputs are for real bare-metal boot and install workflows. They are not the virtual/QEMU target surface; use `make qemu` and `harddrive.img`-based flows for virtualization.
### GRUB Boot Manager (optional)
Red Bear OS can use GNU GRUB as an alternative boot manager with Linux-compatible CLI:
```bash
make all CONFIG_NAME=redbear-grub # Build text-only target with GRUB chainload
./local/scripts/grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img
./local/scripts/grub-mkconfig -o local/recipes/core/grub/grub.cfg
```
## Native hardware listing tools
Red Bear configs now include a small native `redbear-hwutils` package that ships `lspci` and
`lsusb`. `lspci` reads the existing `/scheme/pci/.../config` surface, while `lsusb` walks the
native `usb.*` schemes exposed by `xhcid`, so there is no dependency on the unfinished WIP
`pciutils` or `usbutils` ports.
## Networking
Red Bear ships the existing native Redox wired networking path (`pcid-spawner` → NIC daemon →
`smolnetd`/`dhcpd`/`netcfg`) together with a small Redox-native `netctl` compatibility command and
the `redbear-netctl-console` ncurses client for the bounded Wi‑Fi profile flow. Profiles live under
`/etc/netctl`, the shipped examples live under `/etc/netctl/examples`, live Wi‑Fi actions go
through `/scheme/wifictl`, and the boot service applies the enabled profile with `netctl --boot`.
RTL8125 is wired into the existing native Realtek autoload path by matching `10ec:8125` in the
`rtl8168d` driver config. This keeps the implementation in the Redox userspace driver model rather
than introducing a separate Linux netdevice compatibility layer.
## Runtime diagnostics
Red Bear ships `redbear-info` as the canonical runtime integration/debugging command. It is a
passive report over live system surfaces and is intended to help answer questions like:
- which Red Bear integrations are merely installed versus actually active,
- whether the networking stack is up, with current IP, DNS, and default route,
- whether hardware discovery surfaces such as PCI, USB, DRM, and RTL8125 are visible.
Use `redbear-info --verbose` for evidence-backed human output, `redbear-info --json` for machine-
readable diagnostics, and `redbear-info --test` for suggested follow-up commands.
## Release Model (Full Fork)
Red Bear OS is a **full fork** based on frozen Redox OS snapshots. Sources are immutable and never auto-immutable archived from upstream. The current baseline is **0.1.0** (Redox snapshot at `f55acba68`). Build-dependent sources are archived in `sources/redbear-0.1.0/` (216 BLAKE3-verified archives).
Builds are offline by default — no network access during compilation.
```bash
# Build from archived sources (offline by default)
./local/scripts/build-redbear.sh redbear-full
# Check for newer Redox snapshots (read-only, zero side effects)
./local/scripts/check-upstream-releases.sh
# Provision a new release (explicit, human-initiated only)
./local/scripts/provision-release.sh --ref= --release=0.2.0 --dry-run
```
The `local/` directory is never touched by any source immutable archived. Recipe patches are symlinked from `local/patches/` — protected from `make clean` and `make distclean`.
## Resources
- [Upstream Redox website](https://www.redox-os.org)
- [Redox Book](https://doc.redox-os.org/book/)
- [Hardware Support](https://doc.redox-os.org/book/hardware-support.html)
- [Contributing](CONTRIBUTING.md)
## AI Policy
We welcome contributions made with the assistance of LLMs and AI tools. If you use AI to help write code, documentation, or patches, that's great — we care about the quality of the result, not how it was produced.
## License
[MIT](./LICENSE) — same as upstream Redox OS.