Describe what you want in plain language. Review a typed plan with risk
levels. Approve explicitly. Watch it execute with live output. Atomic-host
changes (rpm-ostree) roll back automatically on failure. Every action is
Ed25519-signed and audited.
The AI never supplies a command. Every action is a typed operation with a
formal risk level, and the daemon builds the command line itself from the
action's own definition — some actions do run through sh -c, but the shell
fragment is constructed by SysKnife, never by the model. The AI cannot touch
your system directly. A privileged daemon executes only what you approve, writes
a tamper-evident Ed25519-signed audit chain, and rolls back atomic-host
(rpm-ostree) changes automatically on failure.
Why typed actions and not a guarded shell? Red-team research (GuardFall)
found that 10 of 11 AI agents bypass raw-string shell guards — an allowlist
or regex is filtering a language rich enough to hide intent. SysKnife removes
the shell string entirely: the model emits
typed actions, and a
public-key-verifiable audit chain records every one.
MCP server
SysKnife is an MCP server first. Point Claude Code, Cursor or Codex CLI at it and
your assistant gets typed, risk-classified sysadmin tools in place of a shell:
| Tool | What it does |
|---|
sysknife_plan | Turns plain language into typed steps, each with a risk level, a resolved command and a daemon transaction ID |
sysknife_execute | Runs steps that carry a one-time receipt, and nothing else |
sysknife_history | Reads past runs out of the signed audit log |
sysknife_doctor | Reports daemon, provider and audit-chain health |
sysknife_audit_verify | Walks the Ed25519 chain and says whether it is intact |
sysknife_get_disk_usage, and the rest of the read-only catalogue | Direct queries, selected for the distro you are on |
npx sysknife-setup
One command wires the server into your client and installs the daemon.
Install has the detail, and MCP protocol has the
wire behaviour.
Your assistant cannot approve its own work. sysknife_plan hands back a
transaction ID and stops there. The receipt sysknife_execute demands comes
from sysknife approve <transaction-id>, typed in your terminal, on a channel
the model does not sit on. Missing, expired, mismatched and replayed receipts
are all refused.
Prefer to stay in the shell? The CLI
is the same engine with no client in front of it.
Install
The fastest path is the setup wizard. It installs the daemon and wires
SysKnife into your AI IDE — Claude Code, Cursor, or Codex CLI — so you can
plan and execute from chat.
npx sysknife-setup
Needs Node 22 or newer; older Node releases no longer receive security fixes.
On Ubuntu 22.04 apt install nodejs gives Node 12, which is too old; the installer
says so and how to get a current Node. No Rust
toolchain and no compile: it downloads verified prebuilt binaries.
What this does:
-
Downloads the prebuilt sysknife + sysknife-daemon binaries for your
architecture (x86_64 / aarch64) from GitHub Releases, SHA-256-verifies
each against the release checksum file — a mismatch aborts the install — and
places them in ~/.local/bin (no sudo). Pass --no-binary to skip the
download and build from source instead.
-
Asks for your LLM provider, key, and model — OpenAI / Anthropic / Gemini
/ Ollama / Groq / DeepSeek / Mistral / xAI (Ollama needs no key). The key
prompt is skipped when the matching env var is already set.
-
Asks which AI integration to wire up (or pick --claude / --cursor /
--codex / --all) and your daemon target(s) — socket, plus an optional
vsock token for a remote VM.
-
Writes the integration-specific MCP config (merging into any existing
file, never clobbering) so the next chat session sees the sysknife_* tools —
sysknife_plan, sysknife_execute, sysknife_history, sysknife_doctor,
sysknife_audit_verify, and distro-compatible direct read-only queries such
as sysknife_get_disk_usage — as first-class tools.
-
Installs and starts the daemon as a service (last step) — a systemd
user service by default (no sudo; kept alive across logout via linger).
That service runs as you, so read-only actions work but mutating ones do
not: installing packages or restarting services needs the system-level
service, whose sudoers grants belong to the sysknife system user. Pick the
system service on any host where you intend to change something, and pass
--daemon-mode=system|user|skip to choose without a prompt. --daemon-mode=system
does not install the system service from the wizard — it needs root-owned
sudoers, polkit and helper policy that sudo make install owns — so it prints
the exact sequence and reports the daemon as not yet installed.
To verify the download against a checksum list you trust independently of the
release, set SYSKNIFE_PINNED_SHA256SUMS=/path/to/sums; see
SECURITY.md.
To check where a release binary was built, download it from the release page and
run gh attestation verify sysknife-vX.Y.Z-linux-x86_64 --repo lacs-project/sysknife.
It succeeds only if the file matches a provenance statement GitHub signed for a
build of this repository by release.yml. Each release also ships that
provenance as sysknife-vX.Y.Z-linux-<arch>.intoto.jsonl, so the same check works
with --bundle; see Verify the published release.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
