alex-schose/qubes-mcp

**Autonomous AI workflows inside a Qubes-isolated sandbox.** AI agents get real
capabilities — creating qubes, building templates, running commands, moving
files — while the rest of the machine stays invisible to them. Qubes provides
the isolation; this project provides the capability surface, mediated by dom0
so the boundary is enforced, not trusted.
> **Threat-model-driven implementation: human-designed boundaries, AI-assisted
> code. Review from Qubes engineers welcome and needed.**
An MCP server runs in one qube, the **hub** (mcp-control), and in each
project's **lead**. Agents connect to it over stdio (usually through SSH) and
call its tools. Every tool is a qrexec
call, and dom0 decides it. Most go to a small library in dom0 that decides
which qube is in scope, what may change and what a new qube is born with;
running a command, copying a file out and the firewall go to the qube or the
Admin API under dom0's qrexec policy. The hub, and each lead, can do what dom0
allows it, and nothing more.
**Status: 0.9.30 — the audit round's medium fixes, first half.** Besides the hub, up to 15
projects, each with its own lead agent that creates and runs its own workers
inside the project's names, templates, networks and disk quota, and sees
nothing outside it; a copy out of the project needs the operator's dialog.
A worker or a lead may be a **standalone**: its own copy of a template's
root, so the tools installed in it stay across restarts.
Every network an AI qube is given is a gateway the operator enrolled, and a
lead's firewall, which dom0 writes to allow its model endpoint (and DNS for a
host name), nothing else, is the operator's. A lead can instead use a
self-hosted model in a **model qube** with no network, which, while it is
guarded, nothing in AI space reaches but the leads it serves (the hub only
through your dialog); the lead then has no network either.
A project can be **anonymous**: its qubes sit only on anonymising routers (Tor,
a VPN), its templates update only through the qube above one, and a gate in
dom0 checks that every 15 seconds and after every qmcp change, and stops the
project when it is not so. One hidden from
the hub (the default) is out of the hub's reach, its names are random, and the
hub's services answer about them as about names that do not exist.
An installation can be in **anonymous mode**: every project is anonymous, and
the gate judges the hub too, with its own qubes and the templates it made.
A **guarded** qube — a template kept as a clean root, a model qube, any
reference — is sealed: the rulebook refuses the hub every way into it. The
operator can open one for a bounded time with qmcp open QUBE --for 2h, to
install software in it or maintain it; the hub may then run commands in it and
copy a file in behind your dialog, and with --firewall write its firewall
rules, never its network. The window ends by itself, at every boot, and on
qmcp seal, which kills the qube so nothing the hub started in it runs on.
The operator runs it all from qmcp-gui, a window in dom0 that is the qmcp
command with forms: every change it makes is a command it shows first. The hub
may ask for a project, a change to one, a new lead, a lead's new firewall, a
deletion, a window on a guarded qube, a qube brought into AI space or out of
the guarded state, a qube taken out of AI space, or exact packages installed
into a template by its own package manager;
nothing happens until the operator accepts it in dom0, in that window or with
qmcp proposal accept. The two
in-qube services need python3 and qvm-copy-to-vm and nothing else; measured
on Qubes 4.3.1, a lead and its workers run on Debian 13, Fedora 43 and Arch
templates alike, and dom0 keeps its own copy of them, so
qmcp template prepare writes them into a template or a standalone at any
time. A qube that comes back from a backup, or is copied by hand, is held for
your review rather than rejoining a project that may have changed, and
qmcp export puts qmcp's settings where a Qubes backup carries them. The
audit round of 0.9.28 is being fixed by severity: this release fixes the high
findings (a revoke now kills, a lock per qube orders the hub's calls against
the operator's commands, the gate kills a stopped qube it finds running, and
creates set their network before they join AI space). Next: the medium and
low findings, then 1.0.0 once all of it is green on a reinstalled machine. 0.9.17 replaced the tier model of 0.9.0–0.9.16; see CHANGELOG.md.
How it works