Royal Red：自带验证引擎与审计回执的智能体操作系统

An agentic operating system that lives on your machine, verifies its own work, and hands you honest receipts for everything it builds.

Royal Red is not a chat window. It is a full agent kernel with a verification engine, a browser, a provider matrix, a consent system, an audit log, and a Settings cockpit that puts every integration in one place. It builds websites, WordPress themes, and vector PDFs, then proves the result in a real browser before it claims success. When a receipt carries the gold crown seal, the work actually passed. When it does not, the receipt tells you exactly what failed.

The 30-second proof

No cuts. The install command, the launcher, the boot screen, INITIALIZE, a typed prompt, the build, and the receipt.

Install

One line (Ubuntu, Debian, Fedora, Windows 11 via WSL2)

curl -fsSL https://raw.githubusercontent.com/muhammadwhizz-web/royal-red/main/install.sh | bash

The installer: installs Bun if missing, clones the app to ~/.local/share/royal-red/app, puts your data in ~/.local/share/royal-red/data, creates the royal-red command, adds a desktop entry with a crown icon, and starts the console.

Step by step (what the one-liner does, and how to do it by hand)

Ubuntu or Debian

# 1. install Bun (the only hard dependency)
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# 2. get the app
git clone https://github.com/muhammadwhizz-web/royal-red.git
cd royal-red

# 3. dependencies and database
bun install
cp .env.example .env
nano .env                       # set DATABASE_URL to an absolute path, for example:
                                # DATABASE_URL="file:$HOME/royal-red-data/royal-red.db"
bun run db:push

# 4. run it
bun run dev                     # console on http://localhost:3000

Fedora or RHEL

Identical to Ubuntu, plus first: sudo dnf install -y git unzip. Everything else is the same because Bun ships its own toolchain.

Windows 11 (WSL2)

1. Open PowerShell as Administrator and run wsl --install, then reboot.
2. Open the Ubuntu app (it installs with WSL2).
3. Follow the Ubuntu steps above inside that terminal.
4. Run royal-red start; the console opens in your Windows browser.

Full walkthrough with the verified limits: docs/INSTALL.md.

macOS

Community-supported. The steps are the same as Ubuntu (brew install git first). The launcher and desktop entry parts of install.sh target Linux paths, so on macOS use the manual steps and bun run dev.

Requirements

First run: what you will see

1. Run royal-red (or bun run dev in the repo). The browser opens the boot screen.
2. Click INITIALIZE.
3. If you have not added an API key yet, a calm banner appears above the composer: "Royal Red is running on the built-in fallback. Add an API key in Settings to unlock the full model roster." You can still chat and build with the fallback; nothing crashes.
4. Click Open Settings on that banner (or the gear icon). Go to Providers, pick any provider, click ADD KEY, paste your key, save. Royal Red tests the connection in the background and shows Connected in green or an honest failure reason in amber. Saving always works, even when the test fails, so a typo never blocks you.
5. The banner disappears the moment one key is saved. That is the whole ritual.

Your keys are encrypted at rest with AES-256-GCM before they touch the disk, are never returned by any API surface, and every save, rotation, and deletion writes an audit row.

What you get

Full architecture: ROYAL-RED.md. Service catalog: docs/SERVICES-CATALOG.md.

Architecture

flowchart TB
    B["Console (browser): chat, panels, SSE"] --> K["Kernel: conversation loop, tool bus"]
    K --> P["Provider matrix: 96 providers, 1,728 routes, cost-aware router"]
    K --> V["Verification engine: real browser, structure gate, overlap probe"]
    K --> S["Sub-agents: planner, builder, 66-role roster, shared Box"]
    K --> T["Unified tool layer: native + connector + MCP + skills, consent gate"]
    S --> Q["Consent queue + undo journal + path prison"]
    K --> D[("SQLite: sessions, receipts, audit, events, memory")]

Loading

One kernel process runs everything. Sub-agents share one sandboxed workspace under a path prison, one consent queue, one undo journal, and one append-only event log with per-run budgets. Every provider decision, consent answer, tool call, and key change lands in the audit log.

Screenshots

Boot screen	Console (dark)	Verified receipt

Troubleshooting

Roadmap

Royal Red is under active development on this main branch. Shipped and next, on the record:

Updating and uninstalling

royal-red update     # pulls the latest main, reinstalls dependencies, keeps your data
royal-red stop       # stop the background service
royal-red uninstall  # removes the app, command, and desktop entry; asks before touching data

Honest status

The engine, the verification tests, the provider key flows, the MCP handshake, the connector credential flow, and the fresh-clone boot were all verified in this repository's own QA rounds (15 suites, 324 checks). Three paths are structurally verified but still need real-machine confirmation, and the project says so rather than pretending:

Details and exact next steps: docs/INSTALL.md, section Verified limits. Connector status per service: docs/SERVICES-CATALOG.md. Provider cost metadata and its sources: docs/PROVIDERS.md.

Documentation

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first: it lists the project laws (no emojis, no em dashes, no overlap, honest receipts) that every change must keep.

License

MIT. See LICENSE. You can use, copy, change, merge, publish, and sell Royal Red and things built with it. The only condition is keeping the copyright notice. The open-source patterns the design learned from are credited in docs/LICENSE-AUDIT.md.

Acknowledgments

Royal Red's design borrows patterns, always cited, from open-source agent projects including cline, continue, aider, browser-use, agent-browser, bytebot, Agent S, and the deepseek-harness. The audit table that maps every pattern to its source and license: docs/LICENSE-AUDIT.md.