sysknife

<p align="center">
  <a href="https://github.com/lacs-project/sysknife">
    <img src="assets/logo/sysknife.svg" alt="SysKnife" width="170" height="170"/>
  </a>
</p>

<h1 align="center">SysKnife</h1>

<p align="center">
  <em>Your sysadmin co-pilot. Plan. Approve. Audit.</em>
</p>

<p align="center">
  <a href="https://github.com/lacs-project/sysknife/actions"><img src="https://img.shields.io/github/actions/workflow/status/lacs-project/sysknife/ci.yml?branch=main&style=flat-square&logo=github&label=CI" alt="CI"></a>
  <a href="https://github.com/lacs-project/sysknife/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lacs-project/sysknife?style=flat-square" alt="License"></a>
  <a href="https://github.com/lacs-project/sysknife/stargazers"><img src="https://img.shields.io/github/stars/lacs-project/sysknife?style=flat-square&logo=github" alt="Stars"></a>
  <a href="https://github.com/lacs-project/sysknife/issues"><img src="https://img.shields.io/github/issues/lacs-project/sysknife?style=flat-square" alt="Issues"></a>
  <a href="https://github.com/lacs-project/sysknife/discussions"><img src="https://img.shields.io/github/discussions/lacs-project/sysknife?style=flat-square&label=discuss" alt="Discussions"></a>
  <a href="https://www.npmjs.com/package/sysknife-setup"><img src="https://img.shields.io/npm/v/sysknife-setup?style=flat-square&logo=npm&label=npx%20setup" alt="npm version"></a>
  <a href="https://glama.ai/mcp/servers/lacs-project/sysknife"><img src="https://glama.ai/mcp/servers/lacs-project/sysknife/badges/score.svg" alt="Glama MCP server quality score"></a>
</p>

<p align="center">
  <strong>Distros</strong>&nbsp;
  <img src="https://img.shields.io/badge/Ubuntu%2020.04%2B-supported-2f855a?style=flat-square&logo=ubuntu&logoColor=white" alt="Ubuntu 20.04 and later supported">
  <img src="https://img.shields.io/badge/Ubuntu%2024.04-VM%20validated-2f855a?style=flat-square&logo=ubuntu&logoColor=white" alt="Ubuntu 24.04 VM validated">
  <img src="https://img.shields.io/badge/Fedora%20Atomic-legacy%2C%20unsupported-6b7280?style=flat-square&logo=fedora&logoColor=white" alt="Fedora Atomic legacy and unsupported">
</p>

<p align="center">
  <a href="#install">Install</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#why-not-just-x">Why not <em>X</em>?</a> ·
  <a href="docs/distro-support.md">Distro matrix</a> ·
  <a href="ROADMAP.md">Roadmap</a> ·
  <a href="CONTRIBUTING.md">Contribute</a> ·
  <a href="https://github.com/lacs-project/sysknife/discussions">Discuss</a>
</p>

<p align="center">
  <img src="assets/demo/mcp-flow.gif" alt="SysKnife in Claude Code via MCP" width="900"/>
</p>

<p align="center">
  <em>Illustrative reproduction of the Claude Code MCP flow — same flow works in Cursor and Codex CLI.</em><br/>
  <em>Looking for the standalone CLI? See <a href="docs/cli.md">the CLI guide</a>.</em>
</p>

> **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](docs/typed-actions.md), and a
[public-key-verifiable audit chain](docs/the-audit-chain.md) 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.

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

[![npm version](https://img.shields.io/npm/v/sysknife-setup?style=flat-square&logo=npm)](https://www.npmjs.com/package/sysknife-setup)

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` — 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](SECURITY.md#release-artefact-trust).

| Client          | Files written                                        |
|-----------------|------------------------------------------------------|
| **Claude Code** | `.mcp.json` + `.claude/hookify.*.local.md`           |
| **Cursor**      | `.cursor/mcp.json` + `.cursor/rules/sysknife.mdc`    |
| **Codex CLI**   | `~/.codex/config.toml` (appended) + `AGENTS.md`      |

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](docs/cli.md) for `sysknife "..."`, `--dry-run`, `--json`,
> approval prompts, and audit-log inspection.

<details>
<summary><strong>Manual install — Ubuntu 20.04+</strong></summary>

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

```sh
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
```

Ubuntu 24.04 is validated with 65/65 stories on a live VM. Ubuntu 22.04 and
26.04 have passed bootstrap and smoke tests but not the full story suite.
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`](docs/distro-support.md) for evidence and scope.
</details>

<details>
<summary><strong>Dry run — plan only, nothing executes</strong></summary>

```sh
# 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"
```
</details>

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