Basalt OS

Security

How Basalt OS protects you.

Basalt OS is built so that AI can help on your computer without being able to harm it or you. This page explains the idea, the layers of protection, what each one stops and what it does not, and how we keep the model honest as it grows.

Security model 0.1, draft

In development

Catalog version 1, updated 2026-10-06. The model is a draft and is published as it evolves: each release is a tagged version on GitHub, through release candidates, until a final 1.0 that comes with the first stable Basalt OS release. Requirements can still change, and planned controls are expected while Basalt OS is pre-alpha.

Release security-model-v0.1-draft The documents on GitHub

The idea

Safety lives in the system, not in the AI.

An AI model, whether ours, a bigger one you install or one from a cloud provider, can only suggest. The operating system decides what it may touch and where it may connect, and it asks you before anything changes. Everything that matters is written to a record that cannot be quietly edited. A smarter model gets better at helping, not more powerful.

When security and AI pull apart, security sets the limits and AI works inside them. Each layer below says what it stops and, just as plainly, what it does not.

The layers

Nine layers, each with its limits.

  1. A verified start

    Secure Boot checks the boot loader and the kernel, and the kernel refuses unsigned drivers. Every Basalt package and the repository metadata are signed, and the system refuses a wrong or missing signature.

    Stops
    Tampered boot software, unsigned drivers, modified packages on a server or mirror.
    Does not stop
    A firmware or hardware attack, or a bug in a correctly signed package. A signature proves who published a file, not that it is free of bugs.

  2. Disk encryption

    The installer encrypts the disk by default. The TPM unlocks it only if the start-up was not tampered with; otherwise it asks for the recovery key you were shown when installing.

    Stops
    Someone who steals the computer or the disk and tries to read it.
    Does not stop
    Someone using the computer while it is on and unlocked, or who learns your password or recovery key. If you install without encryption, this layer is off.

  3. Confinement with SELinux

    SELinux is always on. Basalt's services, the assistant and every AI agent started through Basalt get their own narrow set of permissions, even when running as you or as root.

    Stops
    A tricked or broken program doing more than its job, like an agent reading your SSH keys or another project.
    Does not stop
    Programs you run yourself outside an agent session, which run with your full rights. Confined user accounts and confinement for all desktop apps are planned.

  4. You approve every change

    Agents and the assistant can only propose. You see exactly what will happen and confirm it, and only the desktop's own confirmation sheet or an administrator at a terminal can approve, never the program that asked. A snapshot is taken before a system change.

    Stops
    An AI tricked by a web page or an e-mail into acting for an attacker, and an agent approving its own request.
    Does not stop
    Approving something without reading it. The preview is exact, but the decision is yours. One approval gate for everything, with an Approvals app, is planned.

  5. An audit record you can trust

    One record of security events: what agents did, connections allowed or refused, what SELinux blocked, who became administrator. Each entry is chained to the previous one by a hash, and exports are signed.

    Stops
    Hiding what happened, and forging entries that look like another program's.
    Does not stop
    Root deleting the record. What root cannot do is make that invisible, because the chain no longer verifies.

  6. Network control for AI agents

    An agent session can connect only to the names on its list. Everything else is blocked by the kernel and recorded, and only a person can add a name.

    Stops
    An agent sending your data to a server it chose, including tricks through DNS names or your local network.
    Does not stop
    What an agent sends to a host on its list. Keep the lists short.

  7. AI agents in a box

    Agents such as Claude Code or Codex run through basalt-agent. Each session sees only its project folder, cannot read your keys or passwords and cannot become administrator. Its API key is added by a small proxy, never given to the agent.

    Stops
    A misbehaving agent stealing credentials, planting something that runs later, or leaking its key.
    Does not stop
    An agent spending your credits with its own provider, or damaging the project you gave it. Use version control.

  8. Signed models and knowledge

    The assistant's knowledge is signed and checked before use, and model files are installed only if their checksum matches. Text it reads in mail, pages and files is data, never instructions. The local model runs with no network access.

    Stops
    Poisoned knowledge, swapped model files and instructions hidden in content.
    Does not stop
    A wrong answer. The assistant can be mistaken; that is why it proposes and you confirm.

  9. Privacy when something leaves the computer

    Nothing is sent to us unless you send it. Feedback shows exactly what goes and removes names, addresses and secrets first. A cloud AI model is off by default and the administrator can forbid it.

    Stops
    Silent collection of your data by Basalt.
    Does not stop
    What a cloud AI provider you chose does with what you send it.

Honest limits

What Basalt OS does not promise.

  • It does not make a computer safe from someone who already has administrator rights on it. It makes their actions visible.
  • It does not replace backups. Snapshots undo system changes, and they live on the same disk.
  • It does not check what Fedora ships beyond the signatures. Basalt OS uses Fedora's packages as they are.
  • It is not certified against any standard. The catalog maps to known references to help reviewers, and we test it in the open with a public adversarial suite, basalt-os/ai-audit-suite.

How it stays honest

A catalog of controls, checked on every change.

  • Every protection is a numbered control with a stable ID, like BSC-DISK-001. An ID is never reused; a retired control keeps it.
  • Each control has a status. Implemented means enforced in the shipped packages and checked; partial means only part of the scope or without the full check; planned means decided but not built, so nothing should rely on it yet.
  • Automated checks run in CI on every change, and the build fails when the catalog drifts from the code: a missing path, a missing test or a missing audit step.
  • Audits: before every release with the checklist in the audit guide, and periodically with a full run of the audit guide on a lab installation. Gaps found become work items.
  • A control changes only through a recorded design decision, in the same change as the code, reviewed and approved. Weakening a control is allowed only this way.

Versions

  • 0.x drafts while Basalt OS is pre-alpha and alpha.
  • Release candidates, 1.0-rc.N, once every control needed for the first stable release is in place or has a recorded exception.
  • 1.0 with the first stable Basalt OS release.

Each release is a Git tag and a GitHub release. See releases of the security model and its changelog.

Read the details

The documents.

The full model lives with the source, in docs/security of basalt-os/basalt-os.

  • README.md: the overview, in plain words, of the layers on this page.
  • threat-model.md: what we protect, from whom, and what we assume.
  • controls.md: every control with its ID, requirement, status and how it is verified.
  • audit-guide.md: how to check each control yourself.
  • change-policy.md: how the model changes, its releases and its changelog.

Found a problem?

Report it privately.

A way around any control is a security problem. Please do not open a public issue; follow SECURITY.md to report it privately. For anything else, tell us what you think.