Skip to content

AI

Saphira Linux aiDragon

A practical Saphira workspace for AI agents: your code, services, databases and tools stay under your control, while the model can run wherever it works best.

Verified on Saphira Linux, Arch, macOS M2 and Windows (Wine)

Saphira Linux aiDragon, the AI agent workspace mascot

saphira-build-mcp: a local MCP server for agents

saphira-build-mcp is a local Model Context Protocol (MCP) server with two capabilities: portable agent recovery (checkpoints, session handoff, durable notes and controlled recall on any supported host) and optional Saphira build integration (package, recipe, repository, build queue and policy tools when enabled). You do not need Saphira Linux, a /recipes tree, a Saphira repository or a builder database to use the portable features, and you do not need to compile anything.

It never builds, signs, publishes, installs or restarts anything, and it never executes recipe scripts. Missing data sources produce explicit errors, never invented results. The same binary runs as a stdio server on Linux, macOS and Windows; the agent launches it locally and, over SSH, remotely.

Truly cross-platform: prebuilt binaries

The repository ships prebuilt binaries for Linux (musl and glibc), macOS Apple Silicon (M2) and Windows x86-64, plus the SQLite companion where needed. Each platform comes in two sizes: small (links the system SQLite) and large (-builtin, SQLite compiled in, zero database dependency). Every released binary is checksum-verified at install time from SHA256SUMS.

  • Linux, musl libc: saphira-build-mcp.musl and saphira-build-mcp.musl-builtin (the builtin is fully static).
  • Linux, glibc: saphira-build-mcp.arch and saphira-build-mcp.arch-builtin.
  • macOS Apple Silicon (M2): saphira-build-mcp.osx and saphira-build-mcp.osx-builtin.
  • Windows x86-64: saphira-build-mcp.windows.exe (needs sqlite3.dll beside it) and saphira-build-mcp.windows-builtin.exe.
  • SHA256SUMS: checksums for every released binary; the installer refuses to install on a mismatch.
NoteThe -builtin binaries carry SQLite inside; the musl builtin is static end to end. The small binaries link the system SQLite, so the musl small binary is about 99 KB against the builtin's roughly 818 KB. The same binaries run on Arch, Debian, Ubuntu, Alpine, Saphira or another compatible Linux distribution.

Up and running in about a minute

Install and configure agents
git clone https://github.com/SaphiraLinux/saphira-build-mcp.git
cd saphira-build-mcp
./install.sh --configure-agents

The installer detects operating system, architecture and libc, picks the right variant, checksum-verifies the binary, and installs under ~/.local/bin (or /usr/bin with sudo). With --configure-agents it inserts the MCP entry into opencode.jsonc, Codex or Claude Code, and installs the checkpoint discipline. Portable, journal-only operation is selected with SBM_SAPHIRA=off and needs no builder database.

NoteInstalling the MCP does not teach your agent when to save, list, resume or close checkpoints. Read rules/AGENT_MCP_RULES.md (or the installer's --with-rules) into the agent's persistent instructions, then verify the round trip: save a checkpoint, restart the agent, and confirm the fresh session lists the register before doing anything else.

Agent checkpoint recovery

A checkpoint is a pre-restart write consumed post-restart: label, title, what was done, repository and commit state, findings, and the next action. Checkpoints form a persistent register of unfinished work shared by all agents on the host. checkpoint_list shows the active register (newest first, with a total count); a fresh session lists it and asks whether to resume, start fresh, or close, it never auto-resumes. checkpoint_resume consumes one by id, label, or newest; checkpoint_close retires finished work without deleting its history.

The recovery test for every task is mechanical: could another agent resume this from the checkpoint plus the repository, without asking the previous agent what happened? If not, the handover was not finished.

total_recall: the agent's own long memory

When checkpoints are not enough, total_recall retrieves the history behind them: ranked full-text query, chronological timeline, or paginated export over checkpoints, notes, policy evidence and tool-run metadata, filterable by session, package, label, project, author, hostname, username and working directory. Summaries by default, full bodies only on request, with tiered budgets (compact 4 KiB, standard 16 KiB, extended 64 KiB, deep 256 KiB) enforced before anything returns. It never runs automatically: checkpoint first, deeper recall only when asked.

NoteHonest boundary: tool outputs and conversation turns were never captured, so no retrieval system here can reproduce them. What it does capture is execution provenance, hostname, username, working directory, session id and agent client, so a year later an agent can establish what was worked on, on which machine and account, and what to do next.

Saphira build integration

On a Saphira builder host (the default mode) the server also answers structured queries so agents stop improvising them: package discovery and dependencies (package_search, package_info, package_dependencies, package_why_installed, package_installed), build queue and retained logs (build_queue, package_build_status, package_build_history, package_build_log, package_artifacts), and identity, readiness and policy evidence (package_identity, package_readiness, package_policy_status, package_policy_record).

Two actions are guarded: build_request queues through the daemon intake, which executes detached, the MCP never runs the build itself, and package_bump runs the packager's guards with the reason journaled. Human-controlled signing, publication and installation have no tools and stay human gates by construction.

GoodSafety is deny-by-shape: shells, interpreters, compilers, and anything that builds, signs, publishes or installs is unregistrable. Every invocation is audited to the journal, and external tool exposure is an allowlist that fails closed.

Signing, publication and installation stay human

GoodSigning, publication and installation remain human-controlled gates: no tool signs, publishes or installs, on any host, in any mode.

An agent with this MCP assists the system administrator; it does not independently control infrastructure. The tools that change the world beyond the journal are few, gated, and journaled both ways. Everything else is read-only or journal-only.

One journal, many agents, local or over SSH

One journal. Many agents. Many operating systems. Local or remote over SSH. Because MCP already speaks stdin/stdout and SSH already moves byte streams, no HTTP server or sync protocol is needed: the agent runs locally and the server runs remotely, and the journal never leaves the remote host.

Where to go next

The complete tool tour, all 23 tools one by one, with parameters, capability gates, real responses and the Linux, Python and PowerShell forms, lives in the RTFM guide, which also covers install, agent wiring, the checkpoint discipline and total_recall from an agent's point of view.