sysknife

SysKnife

Your sysadmin co-pilot. Plan. Approve. Audit.

Distros 

·

·

·

·

·

·

A deterministic reproduction of the Claude Code MCP flow on Ubuntu 24.04, rendered offline by

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:

.

Looking for the standalone CLI? See .

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

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 18 or newer. 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:

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.

Then in your chat: ask for what you want and review the plan with risk pills.

Approve each transaction with `sysknife approve ` 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.

Manual install — Ubuntu 20.04+

Needs Rust stable and a C compiler (`build-essential`): the TLS and SQLite

dependencies build native code, so a rustup-only machine stops at

`error: linker cc not found`. `cmake` is not required. Budget 7 to 12

minutes for the ~400-crate build (6m56s on Ubuntu 24.04, 11m43s on 22.04).

sudo apt-get install -y build-essential
git clone https://github.com/lacs-project/sysknife
cd sysknife
make build                            # builds sysknife (CLI) + sysknife-daemon
sudo make install                     # installs both; daemon runs as a system service
sudo 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

Uninstall

Whichever way you installed, there is one command for it.

# Removes what the wizard installed: the user service, the binaries in
# ~/.local/bin, and the MCP + agent config in the current directory.
npx sysknife-setup --uninstall

# See exactly what that would touch, without touching it.
npx sysknife-setup --uninstall --dry-run

Your audit history is kept by default. Removing the software should not

destroy the record of what it did, so the audit database, the safety-audit log

and `~/.config/sysknife` are left in place and their paths printed. Delete those

too, only if you mean to, with:

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

If you installed the system service with `sudo make install`, remove it with

the Makefile that owns its sudoers grants, polkit rules and privileged helpers.

`--uninstall` deliberately will not touch those, because half a removed

privilege boundary is worse than none:

sudo make uninstall

All three Ubuntu LTS releases record a live-VM run of the 79-story Ubuntu

suite, and each run has a replay twin that reproduces it: 22.04, 24.04 and 26.04

all at 79/79, every twin serving every call with zero misses. The runs are in

`tests/evidence/story-runs/`. The suite grew from 50 when every Debian-only

action got a story, `GetHostState` first.

Fedora Atomic is the rpm-ostree target; record a current Silverblue 44 VM run

before treating a release as current-validated. Plain Fedora Workstation and

Server remain experimental until the `dnf` action family ships. See the

`distro support matrix` for evidence and scope.

Dry run — plan only, nothing executes

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

A deterministic reproduction of a real planning and execution session, rendered offline by

. 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. In the maintained paths it is

`sysknife approve ` in your terminal — for the CLI and for MCP

alike, which is why an AI client cannot approve its own plan. The paused Tauri

GUI (`sysknife-shell`) is a third implementation of that same 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, rolls back automatically on

high-risk 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, polkit-mediated privilege boundary. 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.

1,837 Rust tests and 72 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-specific
ollama_url   = "http://localhost:11434"
max_turns    = 10

[daemon]
socket   = "/run/sysknife/daemon.sock"
database = "/var/lib/sysknife/daemon.sqlite"

[storage]                         # production-recommended
backend = "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 ` 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 .

·

Issues, ideas, war stories — .