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.
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.
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.
Bounded native os-release parsing.
A bounded native /proc/uptime read.
A bounded native /proc/meminfo read.
Native root-filesystem statvfs.
Native calling-process identity APIs.
With once-only approval, same-effective-user scope, bounded /proc/<pid>/status reads, and redacted audit counts.
Product principles
Ten commitments the code has to keep.
The agent is a participant in the desktop architecture, not a chat widget.
The model and inference provider are replaceable.
Structured capabilities are preferred over arbitrary shell commands.
No model receives unrestricted root or sudo access.
Sensitive actions are previewed, permission-checked, and auditable.
Security boundaries are enforced in code outside the model.
The shell, agent runtime, broker, executor, and privileged helper are separate components with explicit interfaces.
Local memory is visible, controllable, exportable, and erasable.
Results are verified before Blossom reports success.
Components fail closed when policy or identity cannot be established.
Roadmap
Eleven 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.
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.
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.
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.
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.
Exit Deterministic conformance tests pass for both providers and offline operation is verified.
0 of 4 complete
- ○Define provider-neutral inference, tool-call, cancellation, and streaming APIs.
- ○Implement one local provider, then a second provider to prove replaceability.
- ○Validate all model output against strict schemas.
- ○Keep arbitrary shell as an explicit fallback capability.
Exit Blossom never reports success solely because a command was issued.
0 of 3 complete
- ○Add intent, plan, capability analysis, approval, execution, verification, and truthful-summary states.
- ○Handle partial completion, rollback opportunities, cancellation, and recovery.
- ○Treat tool output and retrieved content as untrusted input.
Exit The shell can operate the tested vertical slices without XFCE dependencies.
0 of 3 complete
- ○Establish Hyprland + Quickshell development environment.
- ○Build agent panel, approval UI, activity history, launcher, notifications, and system status incrementally.
- ○Keep shell UI separate from authorization and execution services.
Exit Context sources are typed, permissioned, observable, and testable.
0 of 3 complete
- ○Add applications, windows, workspaces, hardware, battery, network, storage, services, clipboard, notifications, selected files, and active-project context.
- ○Prefer native APIs and IPC over screenshots or accessibility automation.
- ○Apply per-source privacy, lifetime, and capability rules.
Exit No durable memory is created invisibly.
0 of 2 complete
- ○Separate session context, temporary memory, user-approved durable memory, project knowledge, and system history.
- ○Add inspect, edit, delete, export, disable, retention, and encryption controls.
Exit Repeatable VM installation and rollback evidence exists before device claims.
0 of 2 complete
- ○Build Arch packages, services, ArchISO, hardware detection, model selection, first-run setup, recovery, rollback, and signed updates.
- ○Remove insecure legacy defaults and test upgrade paths.
Exit Release checklist and security review are complete with traceable evidence.
0 of 2 complete
- ○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.
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.