SysKnife

[SysKnife]

SysKnife

The Linux sysadmin MCP server. Plan. Approve. Audit.

[CI] [License] [Stars] [Issues] [Discussions] [npm version] [Glama MCP server quality score] [Rust test count, read from the recorded baseline] [Frontend test count, read from the recorded baseline]

Distros  [Ubuntu 20.04 and later supported] [Ubuntu 22.04, 24.04 and 26.04 VM validated] [Fedora Atomic 41 and later eligible but not VM validated]

MCP server · Install · How it works · Why not X? · Distro matrix · Roadmap · Contribute · Discuss

[SysKnife in Claude Code via MCP on Ubuntu 24.04: UfwAllow, AptInstall and UfwStatus through terminal-issued receipts]

A deterministic reproduction of the Claude Code MCP flow on Ubuntu 24.04, rendered offline by ubuntu-flow-mock.sh so it replays identically from a fresh checkout. Every action name, risk level and command shown is the one the catalogue carries. The same flow works in Cursor and Codex CLI.
On an atomic host the plan uses rpm-ostree instead: the Fedora Atomic recording. Looking for the standalone CLI? See the CLI guide.

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:

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.

[npm version]

What this does:

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

Then in your chat: ask for what you want and review the plan with risk pills. Approve each transaction with sysknife approve <transaction-id> in a terminal, return the one-time receipts, and watch it execute. The daemon, not the prompt, enforces the receipt boundary.

Prefer the standalone CLI? Same engine, no IDE — see the CLI guide for sysknife "...", --dry-run, --json, approval prompts, and audit-log inspection.

sudo apt-get install -y build-essentialgit clone https://github.com/lacs-project/sysknifecd sysknifemake build                            # builds sysknife (CLI) + sysknife-daemonsudo make install                     # installs both; daemon runs as a system servicesudo systemctl enable --now sysknife-daemon
# Join the socket group and one role group, or every request is refused with# "Permission denied" before any role check runs: /run/sysknife is 0750# sysknife:sysknife, and a sudo admin is not in that group automatically.# Role groups: sysknife-observer (read-only), sysknife-dev (medium risk),# sysknife-admin (high risk). Members of wheel are treated as admin.sudo usermod -aG sysknife,sysknife-admin "$USER"newgrp sysknife                       # or log out and back in
# Then wire your IDE — --no-binary skips the download since you just built them# (--daemon-mode=skip: make install already set the service up)npx sysknife-setup --no-binary --daemon-mode=skip

# Removes the user service, the binaries in ~/.local/bin, and the SysKnife# entries in the MCP and agent config it wrote: Claude Code's in the current# directory, .cursor/mcp.json and .cursor/rules/sysknife.mdc, the sysknife block# in ~/.codex/config.toml, and the SysKnife block in AGENTS.md.npx sysknife-setup --uninstall
# See exactly what that would touch, without touching it.npx sysknife-setup --uninstall --dry-run

npx sysknife-setup --uninstall --purge   # names each file before deleting it

sudo make uninstall

# Requires the sysknife binary (see manual install above, or `npx sysknife-setup`).# Plans only: no daemon, no approval, no execution.export ANTHROPIC_API_KEY=sk-ant-...sysknife --dry-run "show disk usage and list services that ate cpu in the last hour"

Prefer the terminal? The CLI is a first-class path

Same engine, no IDE and no MCP client — plain language to a typed plan to live execution, straight from your shell, with --dry-run, --json, --yes up to a risk ceiling, and sysknife audit verify. This is a fully supported way to run SysKnife, not an afterthought. See the CLI guide.

[sysknife CLI — plan, approve, and execute in the terminal]

A deterministic reproduction of a real planning and execution session, rendered offline by demo-mock.sh. Live LLM calls are nondeterministic and the tape has to render with no daemon or provider configured, so the recording is scripted rather than captured; the output styling is generated from the same code paths as the real CLI.

Also: a desktop GUI — development paused. An experimental Tauri desktop app (sysknife-shell) wraps the same plan → approve → execute loop in a window. Its development is paused for now, and effort is going to Ubuntu across its supported versions instead. The code stays in the tree and still builds, but it is not being reviewed, tested, or extended, so reach for it only if you specifically want a graphical approval flow and can live with that. The MCP integration and the CLI are the maintained surfaces.

How it works

sysknife-brain   →   approval gate    →   sysknife-daemon  (planner)         (you, in a         (executor)   talks to LLM      terminal)          only privileged   never to OS       shows the plan,    process; signs                     takes y/n          every action

The approval gate is a surface, not a component, and it depends on how you reach SysKnife:

• MCP: a plan from an AI client needs a receipt from sysknife approve <transaction-id>, typed in your terminal, so the client cannot approve its own plan.
• The standalone CLI: sysknife "<intent>" asks about each step at its own prompt, or approves up to --max-risk under --yes. It never calls sysknife approve.
• An agent with a shell on your account can drive the CLI by itself. In that case the daemon's role limits (SECURITY.md, layer 3) are the boundary that holds.

The paused Tauri GUI (sysknife-shell) is a third implementation of the gate, not a step the other two route through.

1. You type a natural-language request.
2. The brain proposes a plan — each step is a typed action with a risk level (Low · Medium · High).
3. The shell shows the plan with previews, side-effects, and rollback metadata.
4. You approve each step explicitly (or set --yes up to a risk ceiling).
5. The daemon executes, streams live output, and rolls back atomic-host (rpm-ostree) changes automatically on failure.
6. Every execution is logged to a hash-chained SQLite or Postgres audit trail you can verify with sysknife audit verify.

The brain proposes; only the daemon is privileged. The daemon enforces policy, executes typed actions, writes the signed chain, and triggers atomic-host rollback (rpm-ostree) on failure. The trust boundary is mechanical: no shell strings cross the wire.

Why not just X?

SysKnife is different by construction: typed actions, an Ed25519-signed audit chain, explicit approval gate, automatic rollback for atomic-host (rpm-ostree) changes, a privilege boundary scoped per action across sudo and polkit. The AI never holds a shell. See the full SysKnife vs. alternatives breakdown (AIShell-Gate, gate-oc-audit, MCP gateways, generic mcp-shell).

Status

The trust chain is built, tested, and shipping. Multi-distro is the active milestone.

2,000+ Rust tests and 70+ frontend tests form the current deterministic release baseline.

Configure your LLM

SysKnife works with Ollama (no key, recommended for privacy / offline / homelab) or OpenAI, Anthropic, Gemini, Groq, DeepSeek, Mistral, xAI.

# ~/.config/sysknife/config.toml[llm]provider     = "ollama"          # or anthropic / openai / gemini / groq / ...model        = "qwen3:8b"        # provider-specificollama_url   = "http://localhost:11434"max_turns    = 10
[daemon]socket   = "/run/sysknife/daemon.sock"database = "/var/lib/sysknife/daemon.sqlite"
[storage]                         # production-recommendedbackend = "postgres"url     = "postgres://sysknife:${PG_PASSWORD}@db.example.com/audit?sslmode=verify-full"

Env vars always win over the config file. Full reference in docs/configuration.md.

MCP protocol

SysKnife implements the Model Context Protocol and exposes approval-gated planning and execution tools. sysknife_plan returns a daemon-issued transaction ID for each step. After reviewing the plan, the user runs sysknife approve <transaction-id> in a real terminal and gives the one-time receipt to the agent. sysknife_execute rejects missing, expired, mismatched, or replayed receipts. The MCP server cannot mint approval receipts itself.

Use the setup wizard (above) to wire it into Claude Code, Cursor, or Codex CLI. All config files that may contain API keys are created with chmod 0600.

Roadmap

See ROADMAP.md for the full milestone breakdown.

• ✅ Ubuntu 22.04 — 79/79 stories on a live VM (recorded in tests/evidence/story-runs/)
• ✅ Ubuntu 24.04 and 26.04 — 79/79 and 79/79 on live VMs; every LTS run has a replay twin that reproduces it
• ✅ sysknife audit export — stored signed chain rows as JSON with --since / --limit
• 📋 Telegram inline-button approvals
• 📋 CEF / NDJSON output modes for SIEM ingest
• 📋 Fleet plan/execute (one plan, N targets, parallel approval)

Protocol

SysKnife is the reference implementation of the LACS (Linux Agent Control Standard) protocol — typed actions, risk classification, approval gates, audit requirements. The spec is CC0 (public domain):

→ lacs-project/specification

Other implementations for other distros and languages are explicitly encouraged.

Contributing

We want help. Multi-distro is the highest-impact area to plug into right now — see docs/distro-support.md for the roadmap matrix and CONTRIBUTING.md for the workflow.

Issues labelled good first issue are scoped with clear acceptance criteria.

Thanks

Patches so far from @ITSMERNB, @QinXi-ai, @Osheun, @danial-razi, @vsolano9 and @Georgefifth. Every release names who fixed what in CHANGELOG.md.

If you send a patch, watching Releases is the quickest way to see it ship and to catch new good first issue entries as they land. A star helps other people find the project.

Documentation

• Typed actions — why never a shell string
• Action reference — every action, generated from the code
• The audit chain — Ed25519, public-key verifiable
• Automatic rollback
• SysKnife vs. alternatives
• Architecture overview
• Distro support matrix
• Configuration
• Audit storage and recovery
• Developer guide
• Testing guide
• VM daemon setup
• Security policy
• Release readiness checklist
• Roadmap
• ADR 0001 — System boundaries
• ADR 0002 — Brain provider layer
• ADR 0003 — IPC wire protocol

Where to find SysKnife

License

MIT. Free to use, modify, distribute, and embed in proprietary products without restriction.

The LACS specification is CC0 1.0 — public domain.

Built by Vladimir Rotariu. · Issues, ideas, war stories — come say hi.