Pre-alpha · Phase 9 active
Blossom
OS
An open-source, local-first, agent-native Linux desktop. Arch and Hyprland at the base, a replaceable local model above, and a capability broker in between that no model can talk its way past.
Scroll
The initial user promise
Your computer can understand itself, work locally, and show you what it intends to do before sensitive changes happen.
VISION.md
Scope
Drawn as tightly as the security model.
Blossom is specified by what it refuses to become as much as by what it builds. Both lists are read straight from the project’s vision contract.
What Blossom is
- An Arch-based Linux desktop built initially around Hyprland and Quickshell.
- A coherent shell and system-services layer with structured desktop context.
- A replaceable local-model runtime with a deterministic tool protocol.
- A capability broker, policy engine, sandboxed executor, and minimal privileged helper.
- An open-source system whose security claims are backed by tests and evidence.
What Blossom is not
- A general-purpose model with sudo bash.
- A Linux theme or an assistant installed on an otherwise unrelated desktop.
- A system whose safety depends on a prompt telling the model to behave.
- A cloud service disguised as a local operating system.
- A promise that every Linux action can be safely automated.
Architecture
One route from intent to execution.
The shell collects approval but cannot forge a policy decision. The broker and policy engine run without root. The executor only ever receives an approved, normalized request. Model text, tool output and file contents are untrusted data — never authorization.
request pathtyped boundaryaudit tap
The vertical slice
Nothing runs until you say so — exactly once.
Phase 1 is complete and deliberately boring: one typed request mapped only to /usr/bin/uname -s, with no LLM anywhere near it. It exists to prove the boundary, not to be useful.
- Deny-by-default: no matching rule means the answer is ask, never allow.
- Approval binds to that exact request. Change an argument and it is void.
- Grants expire, resist replay, and are never persisted by the model.
- Bubblewrap runs it read-only, with no network, cleared environment and dropped capabilities.
- The result is verified against its schema before Blossom claims success.
- Every step lands in a hash-chained, content-redacted audit record.
Capability model
Verb and scope. Nothing wider.
Tools declare their capabilities statically. Runtime arguments may only narrow the scope, never widen it. Wildcards require an accepted ADR and a threat review, and a model can neither create nor extend a grant.
system.read:os.identityshipped
Bounded native os-release parsing.
system.read:uptimeshipped
A bounded native /proc/uptime read.
system.read:memory.summaryshipped
A bounded native /proc/meminfo read.
system.read:storage.summaryshipped
Native root-filesystem statvfs.
process.read:selfshipped
Native calling-process identity APIs.
process.read:listshipped
With once-only approval, same-effective-user scope, bounded /proc/<pid>/status reads, and redacted audit counts.
6capabilities implemented and tested today
0generic root or shell paths anywhere in the design
denythe default answer for any capability without a matching rule
Product principles
Ten commitments the code has to keep.
01
The agent is a participant in the desktop architecture, not a chat widget.
02
The model and inference provider are replaceable.
03
Structured capabilities are preferred over arbitrary shell commands.
04
No model receives unrestricted root or sudo access.
05
Sensitive actions are previewed, permission-checked, and auditable.
06
Security boundaries are enforced in code outside the model.
07
The shell, agent runtime, broker, executor, and privileged helper are separate components with explicit interfaces.
08
Local memory is visible, controllable, exportable, and erasable.
09
Results are verified before Blossom reports success.
10
Components fail closed when policy or identity cannot be established.
Roadmap
Thirteen phases, each with an exit gate.
Later work is never used to postpone the security or test requirements of an earlier phase. A phase closes when its evidence document says it does.
Phase 0
Preserve and baseline
Exit Clean published history, approved internally consistent foundation documents, accepted license, accurate implementation inventory, private security reporting, branch/release policy, and explicitly defined baseline quality gates.
11 of 11 complete
- ✓Preserve the original prototype unchanged in Git and tag it as prototype-pre-agent-architecture.
- ✓Publish the reviewed initial history to the GitHub main branch.
- ✓Record which features are implemented versus aspirational.
- ✓Select Apache-2.0 through accepted ADR-0001 and add the canonical license.
- ✓Add authoritative vision, architecture, security, roadmap, contribution, and vulnerability-policy documents.
- ✓Audit the preserved prototype for obvious credentials, unsafe defaults, generated artifacts, large binaries, and machine-specific paths.
- ✓Enable GitHub Private Vulnerability Reporting and publish the active link in SECURITY.md.
- ✓Document branch, review, release, and signing policy.
- ✓Enforce the documented policy for main with branch protection.
- ✓Define baseline repository checks, shell linting, prototype smoke tests, CI, dependency policy, secret scanning, and Python CodeQL analysis.
- ✓Verify the initial GitHub Actions runs succeed on the default branch.
Phase 1
Deterministic security vertical slice
Exit End-to-end tests prove request → policy → approval → execution → verification → audit, including denial and failure paths.
4 of 4 complete
- ✓Define the initial typed request and tool/capability schemas. Versioned IPC transport remains intentionally deferred until a separate process exists.
- ✓Implement broker, deny-by-default policy engine, approval state machine, sandboxed diagnostic executor, verification, and audit records.
- ✓Build the smallest interactive terminal approval and activity surface needed to exercise the path, including non-TTY denial and audited cancellation.
- ✓Use a fixed harmless diagnostic; do not integrate an LLM.
Phase 2
Capability and sandbox foundation
Exit Every registered tool declares a static capability and passes its applicable containment tests. See docs/PHASE_2_BASELINE.md.
5 of 5 complete
- ✓Define the capability taxonomy and expansion rules before adding tools.
- ✓Add narrowly scoped system, process, file, and service-read tools in the order fixed by ADR-0004.
- ✓Evaluate and select confinement technologies per resource class by ADR or an accepted extension of an existing profile.
- ✓Keep environment, working-directory, filesystem, network, timeout, output, process, and resource controls code-owned: the fixed Phase 1 command uses its Bubblewrap profile, while native Phase 2 tools use resource-specific bounds and confinement documented in the capability evidence.
- ✓Add property, adversarial, and integration tests for each applicable security boundary, including protected target-Linux evidence.
Phase 3
Privileged operations
Exit Docs/PHASE_3_BASELINE.md records the requirement-by-requirement evidence and independent no-generic-root-path review. The exit checkpoint passed protected CI and merged to main as 0662e51.
3 of 3 complete
- ✓Design a minimal typed helper and polkit policy boundary.
- ✓Add the fixed low-complexity Bluetooth try-restart operation with approval and verification.
- ✓Complete threat review, negative tests, replay protection, and audit coverage.
Phase 4
Replaceable local AI runtime
Exit Deterministic conformance tests pass for both providers, real local-model operation is verified offline on target Linux, and no provider path bypasses the broker, policy, approval, verification, or audit boundary. Unauthenticated loopback endpoints receive no private input.
7 of 7 complete
- ✓Accept the provider-neutral inference, proposed-tool-intent, cancellation, streaming, locality, privacy, and conformance contract.
- ✓Implement closed core types, validation, cancellation, normalized stream state, redacted audit projection, and scripted conformance tests.
- ✓Implement the fixed-local, synthetic-only Ollama development adapter.
- ✓Implement the fixed-local, synthetic-only llama.cpp development adapter.
- ✓Implement the accepted ADR-0012 provider endpoint-identity and packaging boundary before either real adapter may receive private or ambient user data.
- ✓Validate every model output and proposed tool intent against strict, code-owned schemas before it reaches the broker.
- ✓Produce controlled-protocol and real-model target-Linux evidence with external network access disabled.
Phase 5
Planning and verification
Exit A plan reaches completed only when every required step has a code-owned successful verification. Dispatch, exit status, provider output, or tool return alone cannot produce success. Partial and indeterminate effects, retry/rollback limits, and unsupported durable recovery remain explicit.
7 of 7 complete
- ✓Accept ADR-0020 for the closed plan schema, monotonic state machine, per-step authority checks, cancellation, partial/indeterminate outcomes, recovery and rollback limits, audit projection, and truthful summaries.
- ✓Add the closed bounded plan schema, code-derived capability projection, monotonic step lifecycle, terminal taxonomy, and truthful aggregate core.
- ✓Record plan acceptance, every step state, and the final typed aggregate in the engine's hash-chained, content-redacted audit log.
- ✓Translate only normalized, per-turn-eligible Phase 4 native-read intents into conservatively chained typed steps with runtime-derived identifiers.
- ✓Integrate intent, per-step policy, approval, execution, verification, and truthful-summary states over existing typed operations.
- ✓Handle dependency blocking, partial completion, rollback opportunities, cancellation, retry representation, and recovery limits.
- ✓Treat model, tool, and retrieved content as untrusted across adversarial end-to-end orchestration tests and record the exit audit.
Phase 6
Blossom Shell
Exit The shell can operate the tested vertical slices without XFCE dependencies.
7 of 7 complete
- ✓Review and accept the shell IPC and approval-surface ADR.
- ✓Freeze a closed, authenticated, versioned, size-bounded session IPC schema for only the existing fixed diagnostic slice. The closed Rust schema, adversarial decoder tests, real sender authentication, and private-bus transport test are implemented.
- ✓Implement the unprivileged session service without moving authorization, token custody, execution, verification, or audit authority into QML. The connection-bound pending state and fixed-diagnostic engine bridge are implemented with a bounded redacted projection of authoritative audit stages. A Linux-only session D-Bus service adapter now exists behind an inactive production feature. Installed evidence is tracked separately below.
- ✓Prove hostile same-user caller, replay, mutation, expiry, disconnect, restart, cancellation, schema, and service-loss behavior fails closed. Client unique-name loss now cancels its pending approval through the audited engine path, and loss of the owner-monitor stream terminates the service path; the private-bus suite also proves cross-peer preview theft, preview mutation, approval replay, exact cancellation, and cancellation replay against the real engine with an execution counter. Private-bus replacement and bus-loss tests prove old previews cannot survive service or bus loss and start nothing.
- ✓Establish the pinned Arch + Hyprland + Quickshell development and package boundary. The accepted exact stable-repository versions, closed lock schema, inactive user service, D-Bus activation metadata, and drift checker are committed; installed compatibility remains a separate exit gate.
- ✓Build exact approval preview and readable correlated activity UI for the fixed diagnostic. The ARM64 guest renders every fixed preview field and the correlated authoritative activity projection. Installed denial and Escape-cancellation terminate without execution or verification events.
- ✓Produce installed target evidence and an independent Phase 6 exit audit. A separate Apple Silicon ARM64 VM experiment has verified its isolated image-builder boot. A frozen September 3 snapshot resolved the initial ARM Hyprland/Aquamarine mismatch; all 279 diagnostic packages passed signature and integrity checks, the installed versions match, and an ext4 image was assembled. The ARM guest now reaches a serial login prompt and the host ANGLE backend initializes on Metal. Owner screenshots verify visible Hyprland 0.56.1 rendering and DRM/VirGL diagnostics. The ARM service/plugin build and 26 selected tests pass. Installed graphical preview, denial, and keyboard Escape cancellation now pass after correcting service-bus isolation, D-Bus wire typing, plugin linkage, explicit expiry reporting, approval focus, and narrow Bubblewrap/systemd namespace integration. The fixed approve-once workflow now reaches terminal verification with a seven-record correlated audit sequence. A bounded native-client timer now triggers backend-authoritative expiry; the installed graphical panel closes with terminal cancellation and no execution. A fixed-name owner watcher now closes pending UI and reports unavailable when the broker disappears. See docs/PHASE_6_APPLE_SILICON_VALIDATION.md. ARM evidence does not replace the x86-64 gate. Final run 34102303699 passed at signed commit b3bd89e: the pinned package set, installed service/plugin tree, real Qt/D-Bus path, fixed networkless executor, nested compositor, real Hyprland and Quickshell, keyboard close/deny/approve flows, and AT-SPI accessibility checks all passed on the trusted Intel GPU runner. ADR-0021 intentionally provides no durable activity recovery; replacement and bus-loss tests prove stale previews fail closed. The passing evidence and its limits are in docs/PHASE_6_INSTALLED_EVIDENCE.md; the completion decision is in docs/PHASE_6_EXIT_AUDIT.md.
Phase 7
Structured system awareness
Exit Both accepted context sources are typed, permissioned, observable, and testable. Additional sources require separate future review.
3 of 3 complete
- ✓Define the closed context registry and add the fixed battery-summary and coarse network-connectivity sources with per-source privacy, lifetime, and capability rules.
- ✓Use fixed native UPower and NetworkManager IPC adapters, strict verification, content-minimized audit, and narrow shell projections.
- ✓Pass deterministic, adversarial, regression, and real installed evidence for battery present/absent and network online/isolated non-internet outcomes.
Phase 8
Memory and personalization
Exit No durable memory can be created invisibly. Automatic capture, broader memory classes, and public activation remain outside this boundary.
3 of 3 complete
- ✓Accept the closed separation of session context, temporary memory, user-approved durable memory, project knowledge, and system history.
- ✓Implement disabled-by-default encrypted durable notes with exact create/edit approval and no automatic capture, promotion, or model-authored persistence.
- ✓Add fixed inspect, edit, delete, export, disable, retention, and bounded recall controls with adversarial and installed Linux evidence.
Phase 9
Distribution and updates
4 of 7 complete
- ✓Freeze the x86-64 UEFI VM distribution, installer, update, recovery, and rollback boundary in ADR-0026.
- ✓Build closed Arch packages and a Blossom-owned ArchISO without insecure legacy defaults or mutable runtime downloads.
- ✓Add bounded hardware/model selection and resumable first-run state.
- ✓Implement the accepted installer-side disk foundation: two independent ext4 roots, per-slot UKIs, stable observed partition identities, verified rootfs bytes, and a separate persistent state partition.
- ○Wire the physical inactive-slot updater, retained-descriptor streaming, boot-counted trial selection, health promotion, and automatic fallback to that disk foundation. The file-backed Phase 9 lifecycle remains evidence only.
- ○Prove power-loss-safe staging, failed-trial boot fallback, confirmation, and recovery against the real disk/boot layout.
- ○Reissue the independent Phase 9 exit decision after those gates pass.
Phase 10
Public beta hardening
Exit The security review and non-publication candidate checklist pass with traceable evidence at commit 0f6ca2c. Public release publication remains a separate explicit maintainer decision.
8 of 10 complete
- ✓Accept ADR-0027 and freeze the first beta-candidate boundary without expanding the Phase 9 x86-64 UEFI VM evidence target.
- ✓Complete the threat-model, privilege, and sandbox review.
- ✓Enforce locked dependency updates and current advisory scanning.
- ✓Add bounded fuzzing for untrusted protocol decoders.
- ✓Generate deterministic SPDX SBOM, checksums, and release metadata.
- ✓Prove practical release-binary reproducibility and signed provenance.
- ✓Publish limitations, supported-target, disclosure, and release policy.
- ✓Pass the protected beta-candidate workflow and independent exit audit.
- ○Threat-model review, dependency audit, fuzzing, privilege and sandbox review, signed releases, SBOM, practical reproducible builds, and disclosure process.
- ○Publish clear limitations and supported hardware.
Phase 11
First physical-device qualification
Exit One exact physical target completes the reviewed safety, installation, hardware, update, rollback, and recovery matrix. No broader hardware claim is implied.
5 of 9 complete
- ✓Define the exact first-device boundary and implement a closed read-only preflight that grants no installation or support authority.
- ✓Confirm the exact target identity and prerequisites on the physical host. Protected read-only run 34447352126 verified all six closed checks for the frozen MacBookPro11,1 target without collecting stable identifiers.
- ✓Add explicit target discovery, destructive-action rejection rules, typed confirmation, power/recovery prerequisites, and disposable-media tests. The non-writing guard, bounded write/read/restore probe, adversarial tests, and protected pre-write observation are complete. The approved /dev/sdc probe wrote, verified, restored, and re-verified its bounded 4 KiB region; minimized result evidence is preserved in the repository.
- ✓Add a reproducible Apple-silicon maintainer entrypoint for the pinned x86_64 candidate build, plus a checksum-first macOS/Linux media creator with external-disk filtering, exact identity confirmation, re-observation, and byte-for-byte post-write verification. Windows media creation remains open.
- ✓Add the minimum coherent desktop surface before another physical image: first-run guidance, application launcher, browser, files, editor, terminal, network and audio settings, session controls, workspaces, status, guarded installer entry, and a local Apple-silicon x86_64 emulation launcher.
- ○Pass the desktop usability matrix in a fresh generic VM: every fixed app action launches, welcome and launcher remain readable at 1280x720, keyboard window/workspace controls work, live installation stays explicit, and restart/shutdown confirmations behave correctly.
- ○Add a trusted human-presence approval ceremony before admitting sensitive capabilities to the graphical shell; D-Bus connection binding proves process continuity, not human intent.
- ○Prove installation, boot, essential hardware surfaces, update rollback, and recovery on the frozen physical target.
- ○Publish an independent Phase 11 exit audit and exact limitations.
Phase 12
Desktop fine-tuning
Exit A fresh install in the generic VM and on the physical target passes the desktop usability matrix (window controls, Settings v1, lock and idle, display changes with revert, storage page, performance budgets) with recorded evidence, and every setting survives reboot and an A/B slot switch.
0 of 51 complete
- ○Settings are user actions, never agent capabilities. Exposing any setting to the agent needs its own ADR.
- ○System-wide changes go through existing systemd/freedesktop D-Bus services (timedated, localed, hostnamed, AccountsService, power-profiles-daemon, NetworkManager) with polkit. No new privileged helper and no generic shell.
- ○Every persistent setting survives A/B updates and rollback: user settings live in the home directory on the state partition; system settings are added to the closed slot-sync set (ADR-0029) or moved to the state partition, with a test.
- ○Petal tokens and icons only. No Unicode glyph icons, text at 4.5:1 contrast or better, and every control reachable by keyboard and AT-SPI.
- ○Each item is verified in the fast loop (disposable overlay, packages installed with pacman -U) before it is included in an image gate.
- ○One-day labwc spike in a disposable overlay: shell renders, command-bar keybinding works over a focused app, dock lists and closes/minimizes windows, approval window stays above all windows with password-dialog focus, and the compositor-PID polkit subject is re-verified.
- ○Accept an ADR choosing labwc, or Hyprland with floating rules, title bars, and mouse move/resize, including the security re-verification it requires.
- ○Replace every Unicode glyph in the top bar, dock, and panels with the Petal 24-icon set (24 grid, 1.75 stroke, currentColor).
- ○Top bar as designed: flower and workspace on the left, date and time in the centre, one combined quick-settings button (network, sound, Bluetooth, battery percentage) and power on the right.
- ○Quick-settings panel: Wi-Fi, Bluetooth, and Do-not-disturb tiles, one volume slider, agent status line ("No agent actions pending"), and "All settings".
- ○Dock: Apps, Files, Browser, Terminal | Agent, with running-app dots and hover labels.
- ○Status pills, activity rows, and the monospace security field (digests grouped in fours) from the Petal components board.
- ○"Dark shell, light apps": a Petal light GTK and Qt theme, Petal cursor and icon theme for apps, Petal-styled notifications.
- ○Ship a Firefox policies.json: no telemetry, no studies, no Pocket, no first-run or post-update pages, no default-browser check, a privacy-respecting default search engine.
- ○Windows open floating and centred at a sensible size.
- ○Title bars with close, minimize, and maximize; drag to move; edge resize.
- ○Snap to left/right half and maximize by dragging to screen edges.
- ○Minimized windows restorable from the dock; Alt+Tab window switcher.
- ○Usability check: two windows of the same app never auto-tile or cascade off-screen.
- ○Applications panel backed by broker discovery: every installed app's icon and name, search using command-bar routing, launch by opaque row ID.
- ○Row IDs bound to a catalogue generation; a rescan (for example after installing Chrome) reloads the panel and stale IDs fail closed.
- ○Bounded catalogue (512 entries); system entries first, user-installed entries labelled; icons resolved by theme name only, never by path.
- ○Settings app in Petal with a sidebar and search.
- ○Appearance: wallpaper picker, light/dark apps, accent preview, text size.
- ○Date & time: timezone, automatic time (NTP), 24-hour clock, date format, via timedated. Timezone persists across slots.
- ○Keyboard & language: layouts and switching shortcut, system language and formats, via localed.
- ○Mouse & touchpad: pointer speed, natural scrolling, tap to click.
- ○Notifications: Do-not-disturb, per-app on/off.
- ○Default apps: browser, file manager, text editor.
- ○Users & password: change password and display name through AccountsService/polkit.
- ○Agent & privacy: workspace folder, model in use and its memory use, activity log viewer and clear, durable notes on/off.
- ○Sound, Network, Bluetooth: native pages, or links to pavucontrol, nm-connection-editor, and blueman until native pages exist.
- ○About: Blossom version, active slot, hardware summary, licences.
- ○Screen lock with a Petal lock screen; manual lock with Super+L and from the system menu.
- ○Automatic lock after idle (default 5 minutes), on lid close, and before suspend. Locking cannot be disabled without the user's password.
- ○Screen off after idle; suspend on lid close; configurable timeouts.
- ○Power profiles (power saver, balanced, performance) via power-profiles-daemon; low-battery warning and critical action.
- ○Screensaver: a simple Petal idle animation before screen-off, optional.
- ○Gate: lock engages after idle and lid close in the VM and on the physical target; the approval and password dialogs never appear above the lock screen.
- ○Resolution, refresh rate, and scaling (including fractional HiDPI) per output, applied live with a 15-second "keep these settings?" revert.
- ○Multi-monitor arrangement and primary display; settings persisted per output.
- ○Brightness (keyboard keys and slider) and Night Light with a schedule.
- ○Gate: settings survive reboot and A/B slot switch; a bad mode reverts automatically.
- ○Storage page: usage of the active root slot, inactive slot, and state partition; largest folders in the workspace; low-space warning on the state partition at a fixed threshold.
- ○Bounded growth: journald size cap on the state partition, pacman cache cleanup timer (paccache), thumbnail and browser cache caps, model cache accounted for.
- ○SSD health: fstrim.timer enabled; noatime on root and state; ext4 error behaviour documented.
- ○Memory: zram swap via zram-generator; systemd-oomd policy that protects the shell, broker, and lock screen and sacrifices the model provider first; model provider unloads after an idle period and reloads on demand.
- ○Performance budgets measured in every image gate and recorded in the evidence: boot to desktop, idle RAM and CPU with and without the model loaded, command bar open latency, app launch latency, model cold and warm latency.
- ○Gate: budgets met in the ARM64 VM and on the MacBookPro11,1 target, with numbers recorded per architecture.
- ○Text size and high-contrast mode; reduced motion respected by the shell.
- ○Every shell surface passes the AT-SPI check; screen-reader (Orca) smoke test for the command bar, approval window, and Settings.
This is pre-alpha research software.
Blossom OS is not ready to install as a trusted daily operating system and has no supported release. The repository still contains the preserved Arch/XFCE prototype and a rule-based Python assistant that does not load or run a real LLM. Those legacy scripts include insecure development defaults.
The Rust security core is real but narrow. No security property described in the target documents should be read as a claim about what is shipping today.
