Skip to content
Back to search

sysknife

An AI that administers Linux through typed, approval-gated, Ed25519-audited actions. The model selects the action; the daemon builds the command.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/lacs-project/sysknife with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/lacs-project/sysknife'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lacs-project--sysknife/badge.svg)](/listings/lacs-project--sysknife)

HTML

<a href="/listings/lacs-project--sysknife"><img src="/api/listings/lacs-project--sysknife/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

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

sudo apt-get install -y build-essential
git clone https://github.com/lacs-project/sysknife
cd sysknife

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 508 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://github.com/lacs-project/sysknife">
  3. <img src="assets/logo/sysknife.svg" alt="SysKnife" width="170" height="170"/>
  4. </a>
  5. </p>
  6. <h1 align="center">SysKnife</h1>
  7. <p align="center">
  8. <em>The Linux sysadmin MCP server. Plan. Approve. Audit.</em>
  9. </p>
  10. <p align="center">
  11. <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>
  12. <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>
  13. <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>
  14. <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>
  15. <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>
  16. <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>
  17. <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>
  18. <a href="https://github.com/lacs-project/sysknife/blob/main/tests/evidence/workspace-tests.json"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flacs-project%2Fsysknife%2Fmain%2Ftests%2Fevidence%2Fworkspace-tests.json&query=$.tests&label=Rust%20tests&style=flat-square&color=2f855a" alt="Rust test count, read from the recorded baseline"></a>
  19. <a href="https://github.com/lacs-project/sysknife/blob/main/tests/evidence/workspace-tests.json"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flacs-project%2Fsysknife%2Fmain%2Ftests%2Fevidence%2Fworkspace-tests.json&query=$.frontend_tests&label=frontend%20tests&style=flat-square&color=2f855a" alt="Frontend test count, read from the recorded baseline"></a>
  20. </p>
  21. <p align="center">
  22. <strong>Distros</strong>&nbsp;
  23. <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">
  24. <img src="https://img.shields.io/badge/Ubuntu%2022.04%20%7C%2024.04%20%7C%2026.04-VM%20validated-2f855a?style=flat-square&logo=ubuntu&logoColor=white" alt="Ubuntu 22.04, 24.04 and 26.04 VM validated">
  25. <img src="https://img.shields.io/badge/Fedora%20Atomic%2041%2B-eligible%2C%20unvalidated-b7791f?style=flat-square&logo=fedora&logoColor=white" alt="Fedora Atomic 41 and later eligible but not VM validated">
  26. </p>
  27. <p align="center">
  28. <a href="#mcp-server">MCP server</a> ·
  29. <a href="#install">Install</a> ·
  30. <a href="#how-it-works">How it works</a> ·
  31. <a href="#why-not-just-x">Why not <em>X</em>?</a> ·
  32. <a href="docs/distro-support.md">Distro matrix</a> ·
  33. <a href="ROADMAP.md">Roadmap</a> ·
  34. <a href="CONTRIBUTING.md">Contribute</a> ·
  35. <a href="https://github.com/lacs-project/sysknife/discussions">Discuss</a>
  36. </p>
  37. <p align="center">
  38. <img src="assets/demo/ubuntu-flow.gif" alt="SysKnife in Claude Code via MCP on Ubuntu 24.04: UfwAllow, AptInstall and UfwStatus through terminal-issued receipts" width="900"/>
  39. </p>
  40. <p align="center">
  41. <em>A deterministic reproduction of the Claude Code MCP flow on Ubuntu 24.04, rendered offline by
  42. <a href="assets/demo/ubuntu-flow-mock.sh">ubuntu-flow-mock.sh</a> so it replays identically from a
  43. fresh checkout. Every action name, risk level and command shown is the one the catalogue
  44. carries. The same flow works in Cursor and Codex CLI.</em><br/>
  45. <em>On an atomic host the plan uses rpm-ostree instead:
  46. <a href="assets/demo/mcp-flow.gif">the Fedora Atomic recording</a>.
  47. Looking for the standalone CLI? See <a href="docs/cli.md">the CLI guide</a>.</em>
  48. </p>
  49. > **Describe what you want in plain language.** Review a typed plan with risk
  50. > levels. Approve explicitly. Watch it execute with live output. Atomic-host
  51. > changes (rpm-ostree) roll back automatically on failure. Every action is
  52. > Ed25519-signed and audited.
  53. The AI never supplies a command. Every action is a **typed operation** with a
  54. formal risk level, and the daemon builds the command line itself from the
  55. action's own definition — some actions do run through `sh -c`, but the shell
  56. fragment is constructed by SysKnife, never by the model. The AI cannot touch
  57. your system directly. A privileged daemon executes only what you approve, writes
  58. a tamper-evident Ed25519-signed audit chain, and rolls back atomic-host
  59. (rpm-ostree) changes automatically on failure.
  60. **Why typed actions and not a guarded shell?** Red-team research (GuardFall)
  61. found that **10 of 11 AI agents bypass raw-string shell guards** — an allowlist
  62. or regex is filtering a language rich enough to hide intent. SysKnife removes
  63. the shell string entirely: the model emits
  64. [typed actions](docs/typed-actions.md), and a
  65. [public-key-verifiable audit chain](docs/the-audit-chain.md) records every one.
  66. ---
  67. ## MCP server
  68. SysKnife is an MCP server first. Point Claude Code, Cursor or Codex CLI at it and
  69. your assistant gets typed, risk-classified sysadmin tools in place of a shell:
  70. | Tool | What it does |
  71. |---|---|
  72. | `sysknife_plan` | Turns plain language into typed steps, each with a risk level, a resolved command and a daemon transaction ID |
  73. | `sysknife_execute` | Runs steps that carry a one-time receipt, and nothing else |
  74. | `sysknife_history` | Reads past runs out of the signed audit log |
  75. | `sysknife_doctor` | Reports daemon, provider and audit-chain health |
  76. | `sysknife_audit_verify` | Walks the Ed25519 chain and says whether it is intact |
  77. | `sysknife_get_disk_usage`, and the rest of the read-only catalogue | Direct queries, selected for the distro you are on |
  78. ```sh
  79. npx sysknife-setup
  80. ```
  81. One command wires the server into your client and installs the daemon.
  82. [Install](#install) has the detail, and [MCP protocol](#mcp-protocol) has the
  83. wire behaviour.
  84. **Your assistant cannot approve its own work.** `sysknife_plan` hands back a
  85. transaction ID and stops there. The receipt `sysknife_execute` demands comes
  86. from `sysknife approve <transaction-id>`, typed in your terminal, on a channel
  87. the model does not sit on. Missing, expired, mismatched and replayed receipts
  88. are all refused.
  89. Prefer to stay in the shell? [The CLI](#prefer-the-terminal-the-cli-is-a-first-class-path)
  90. is the same engine with no client in front of it.
  91. ---
  92. ## Install
  93. The fastest path is the setup wizard. It installs the daemon and wires
  94. SysKnife into your AI IDE — Claude Code, Cursor, or Codex CLI — so you can
  95. plan and execute from chat.
  96. ```sh
  97. npx sysknife-setup
  98. ```
  99. Needs **Node 22 or newer**; older Node releases no longer receive security fixes.
  100. On Ubuntu 22.04 `apt install nodejs` gives Node 12, which is too old; the installer
  101. says so and how to get a current Node. No Rust
  102. toolchain and no compile: it downloads verified prebuilt binaries.
  103. [![npm version](https://img.shields.io/npm/v/sysknife-setup?style=flat-square&logo=npm)](https://www.npmjs.com/package/sysknife-setup)
  104. What this does:
  105. 1. **Downloads the prebuilt `sysknife` + `sysknife-daemon` binaries** for your
  106. architecture (x86_64 / aarch64) from GitHub Releases, **SHA-256-verifies**
  107. each against the release checksum file — a mismatch aborts the install — and
  108. places them in `~/.local/bin` (no sudo). Pass `--no-binary` to skip the
  109. download and build from source instead.
  110. 2. Asks for your **LLM provider, key, and model** — OpenAI / Anthropic / Gemini
  111. / Ollama / Groq / DeepSeek / Mistral / xAI (Ollama needs no key). The key
  112. prompt is skipped when the matching env var is already set.
  113. 3. Asks **which AI integration** to wire up (or pick `--claude` / `--cursor` /
  114. `--codex` / `--all`) and your **daemon target(s)** — socket, plus an optional
  115. vsock token for a remote VM.
  116. 4. **Writes the integration-specific MCP config** (merging into any existing
  117. file, never clobbering) so the next chat session sees the `sysknife_*` tools —
  118. `sysknife_plan`, `sysknife_execute`, `sysknife_history`, `sysknife_doctor`,
  119. `sysknife_audit_verify`, and distro-compatible direct read-only queries such
  120. as `sysknife_get_disk_usage` — as first-class tools.
  121. 5. **Installs and starts the daemon as a service** (last step) — a systemd
  122. *user* service by default (no sudo; kept alive across logout via linger).
  123. That service runs as you, so read-only actions work but **mutating ones do
  124. not**: installing packages or restarting services needs the system-level
  125. service, whose sudoers grants belong to the `sysknife` system user. Pick the
  126. system service on any host where you intend to change something, and pass
  127. `--daemon-mode=system|user|skip` to choose without a prompt. `--daemon-mode=system`
  128. does not install the system service from the wizard — it needs root-owned
  129. sudoers, polkit and helper policy that `sudo make install` owns — so it prints
  130. the exact sequence and reports the daemon as not yet installed.
  131. To verify the download against a checksum list you trust independently of the
  132. release, set `SYSKNIFE_PINNED_SHA256SUMS=/path/to/sums`; see
  133. [SECURITY.md](SECURITY.md#release-artefact-trust).
  134. To check where a release binary was built, download it from the release page and
  135. run `gh attestation verify sysknife-vX.Y.Z-linux-x86_64 --repo lacs-project/sysknife`.
  136. It succeeds only if the file matches a provenance statement GitHub signed for a
  137. build of this repository by `release.yml`. Each release also ships that
  138. provenance as `sysknife-vX.Y.Z-linux-<arch>.intoto.jsonl`, so the same check works
  139. with `--bundle`; see [Verify the published release](docs/release.md#verify-the-published-release).
  140. | Client | Files written |
  141. |-----------------|------------------------------------------------------|
  142. | **Claude Code** | `.mcp.json` + `.claude/hookify.*.local.md` |
  143. | **Cursor** | `.cursor/mcp.json` + `.cursor/rules/sysknife.mdc` |
  144. | **Codex CLI** | `~/.codex/config.toml` (appended) + `AGENTS.md` |
  145. Then in your chat: ask for what you want and review the plan with risk pills.
  146. Approve each transaction with `sysknife approve <transaction-id>` in a
  147. terminal, return the one-time receipts, and watch it execute. The daemon, not
  148. the prompt, enforces the receipt boundary.
  149. > **Prefer the standalone CLI?** Same engine, no IDE — see the
  150. > [CLI guide](docs/cli.md) for `sysknife "..."`, `--dry-run`, `--json`,
  151. > approval prompts, and audit-log inspection.
  152. <details>
  153. <summary><strong>Manual install — Ubuntu 20.04+</strong></summary>
  154. Needs Rust stable **and a C compiler** (`build-essential`): the TLS and SQLite
  155. dependencies build native code, so a rustup-only machine stops at
  156. `error: linker cc not found`. `cmake` is not required. Budget 7 to 12
  157. minutes for the ~400-crate build (6m56s on Ubuntu 24.04, 11m43s on 22.04).
  158. ```sh
  159. sudo apt-get install -y build-essential
  160. git clone https://github.com/lacs-project/sysknife
  161. cd sysknife
  162. make build # builds sysknife (CLI) + sysknife-daemon
  163. sudo make install # installs both; daemon runs as a system service
  164. sudo systemctl enable --now sysknife-daemon
  165. # Join the socket group and one role group, or every request is refused with
  166. # "Permission denied" before any role check runs: /run/sysknife is 0750
  167. # sysknife:sysknife, and a sudo admin is not in that group automatically.
  168. # Role groups: sysknife-observer (read-only), sysknife-dev (medium risk),
  169. # sysknife-admin (high risk). Members of wheel are treated as admin.
  170. sudo usermod -aG sysknife,sysknife-admin "$USER"
  171. newgrp sysknife # or log out and back in
  172. # Then wire your IDE — --no-binary skips the download since you just built them
  173. # (--daemon-mode=skip: make install already set the service up)
  174. npx sysknife-setup --no-binary --daemon-mode=skip
  175. ```
  176. ### Uninstall
  177. Whichever way you installed, there is one command for it.
  178. ```sh
  179. # Removes the user service, the binaries in ~/.local/bin, and the SysKnife
  180. # entries in the MCP and agent config it wrote: Claude Code's in the current
  181. # directory, .cursor/mcp.json and .cursor/rules/sysknife.mdc, the sysknife block
  182. # in ~/.codex/config.toml, and the SysKnife block in AGENTS.md.
  183. npx sysknife-setup --uninstall
  184. # See exactly what that would touch, without touching it.
  185. npx sysknife-setup --uninstall --dry-run
  186. ```
  187. **Your audit history is kept by default.** Removing the software should not
  188. destroy the record of what it did, so the audit database, the safety-audit log
  189. and `~/.config/sysknife` are left in place and their paths printed. Delete those
  190. too, only if you mean to, with:
  191. ```sh
  192. npx sysknife-setup --uninstall --purge # names each file before deleting it
  193. ```
  194. If you installed the **system** service with `sudo make install`, remove it with
  195. the Makefile that owns its sudoers grants, polkit rules and privileged helpers.
  196. `--uninstall` deliberately will not touch those, because half a removed
  197. privilege boundary is worse than none:
  198. ```sh
  199. sudo make uninstall
  200. ```
  201. All three Ubuntu LTS releases record a live-VM run of <!-- fig:lts_story_total -->79<!-- /fig --> stories from the Ubuntu
  202. suite (which has since grown to <!-- fig:stories_ubuntu floor=10 -->90+<!-- /fig -->), and each run has a replay twin that reproduces it: 22.04, 24.04 and 26.04
  203. all at <!-- fig:lts_story_rate -->79/79<!-- /fig -->, every twin serving every call with zero misses. The runs are in
  204. `tests/evidence/story-runs/`. The suite grew from 50 when every Debian-only
  205. action got a story, `GetHostState` first.
  206. Fedora Atomic is the rpm-ostree target; `make install` does not complete on
  207. rpm-ostree yet ([#301](https://github.com/lacs-project/sysknife/issues/301)), and
  208. a release needs a current Silverblue 44 VM run before it counts as validated. Plain Fedora Workstation and
  209. Server remain experimental until the `dnf` action family ships. See the
  210. [`distro support matrix`](docs/distro-support.md) for evidence and scope.
  211. </details>
  212. <details>
  213. <summary><strong>Dry run — plan only, nothing executes</strong></summary>
  214. ```sh
  215. # Requires the sysknife binary (see manual install above, or `npx sysknife-setup`).
  216. # Plans only: no daemon, no approval, no execution.
  217. export ANTHROPIC_API_KEY=sk-ant-...
  218. sysknife --dry-run "show disk usage and list services that ate cpu in the last hour"
  219. ```
  220. </details>
  221. ## Prefer the terminal? The CLI is a first-class path
  222. Same engine, no IDE and no MCP client — plain language to a typed plan to live
  223. execution, straight from your shell, with `--dry-run`, `--json`, `--yes` up to a
  224. risk ceiling, and `sysknife audit verify`. This is a fully supported way to run
  225. SysKnife, not an afterthought. See the [CLI guide](docs/cli.md).
  226. <p align="center">
  227. <img src="assets/demo/demo.gif" alt="sysknife CLI — plan, approve, and execute in the terminal" width="900"/>
  228. </p>
  229. <p align="center">
  230. <em>A deterministic reproduction of a real planning and execution session, rendered offline by
  231. <a href="assets/demo/demo-mock.sh">demo-mock.sh</a>. Live LLM calls are nondeterministic and the
  232. tape has to render with no daemon or provider configured, so the recording is scripted rather
  233. than captured; the output styling is generated from the same code paths as the real CLI.</em>
  234. </p>
  235. > **Also: a desktop GUI — development paused.** An experimental Tauri desktop
  236. > app (`sysknife-shell`) wraps the same plan → approve → execute loop in a
  237. > window. **Its development is paused for now**, and effort is going to Ubuntu
  238. > across its supported versions instead. The code stays in the tree and still
  239. > builds, but it is not being reviewed, tested, or extended, so reach for it
  240. > only if you specifically want a graphical approval flow and can live with
  241. > that. The MCP integration and the CLI are the maintained surfaces.
  242. ## How it works
  243. ```
  244. sysknife-brain → approval gate → sysknife-daemon
  245. (planner) (you, in a (executor)
  246. talks to LLM terminal) only privileged
  247. never to OS shows the plan, process; signs
  248. takes y/n every action
  249. ```
  250. The approval gate is a surface, not a component, and it depends on how you
  251. reach SysKnife:
  252. - **MCP:** a plan from an AI client needs a receipt from
  253. `sysknife approve <transaction-id>`, typed in your terminal, so the client
  254. cannot approve its own plan.
  255. - **The standalone CLI:** `sysknife "<intent>"` asks about each step at its own
  256. prompt, or approves up to `--max-risk` under `--yes`. It never calls
  257. `sysknife approve`.
  258. - **An agent with a shell on your account** can drive the CLI by itself. In that
  259. case the daemon's role limits
  260. ([SECURITY.md, layer 3](SECURITY.md#layer-3--role-based-authorization-sysknife-daemon))
  261. are the boundary that holds.
  262. The paused Tauri GUI (`sysknife-shell`) is a third implementation of the gate,
  263. not a step the other two route through.
  264. 1. You type a natural-language request.
  265. 2. The brain proposes a plan — each step is a **typed action** with
  266. a risk level (`Low` · `Medium` · `High`).
  267. 3. The shell shows the plan with previews, side-effects, and rollback
  268. metadata.
  269. 4. You approve each step explicitly (or set `--yes` up to a risk ceiling).
  270. 5. The daemon executes, streams live output, and rolls back atomic-host
  271. (rpm-ostree) changes automatically on failure.
  272. 6. Every execution is logged to a hash-chained SQLite or Postgres audit
  273. trail you can verify with `sysknife audit verify`.
  274. The brain *proposes*; only the daemon is privileged. The daemon *enforces*
  275. policy, executes typed actions, writes the signed chain, and triggers
  276. atomic-host rollback (rpm-ostree) on failure. The trust boundary is
  277. mechanical: no shell strings cross the wire.
  278. ## Why not just X?
  279. | Tool | The gap |
  280. |---|---|
  281. | **Open Interpreter** | Runs arbitrary Python/Shell. No formal risk model. No audit chain. |
  282. | **Goose / Continue** | General-purpose. Ad-hoc confirmation, not typed risk levels. |
  283. | **Claude Computer Use** | Uncontrolled desktop automation, not system administration. |
  284. | **Ansible** | YAML written in advance. Not conversational. No risk classification. |
  285. | **shell-gpt / Copilot** | Suggests raw shell commands. You still run raw shell. |
  286. | **AIShell-Gate** | Closest peer, but proprietary and closed; audit is symmetric HMAC (the verifier holds the signing secret, so a proof convinces no one else). No rollback. |
  287. | **Manual** | No audit trail. No rollback. One typo = lost work. |
  288. SysKnife is different by construction: typed actions, an Ed25519-signed audit
  289. chain, explicit approval gate, automatic rollback for atomic-host (rpm-ostree)
  290. changes, a privilege boundary scoped per action across sudo and polkit. The AI
  291. never holds a shell. See the
  292. full [SysKnife vs. alternatives](docs/comparison.md) breakdown (AIShell-Gate,
  293. gate-oc-audit, MCP gateways, generic mcp-shell).
  294. ## Status
  295. The trust chain is built, tested, and shipping. Multi-distro is the active
  296. milestone.
  297. | Component | State |
  298. |---|---|
  299. | `sysknife-brain` — LLM planner, tool loop, safety fence | ✅ |
  300. | `sysknife-daemon` — <!-- fig:typed_actions floor=10 -->190+<!-- /fig --> typed actions, auth, preview, transactions | ✅ |
  301. | Live IPC + streaming + atomic-host rollback (rpm-ostree) | ✅ |
  302. | Terminal approval gate — one-time, TTL-bounded receipts | ✅ |
  303. | MCP server (Claude Code / Cursor / any MCP client) | ✅ |
  304. | Tamper-evident Ed25519-signed audit chain | ✅ |
  305. | RFC 5424 syslog forwarding (Splunk / Sentinel / QRadar) | ✅ |
  306. | Postgres backend (RDS / Cloud SQL / Neon / Supabase) | ✅ |
  307. | **Ubuntu support** — <!-- fig:story_run:ubuntu-22.04-gpt-oss-120b -->79/79<!-- /fig --> stories on a live 22.04 VM, recorded in `tests/evidence/story-runs/` | ✅ |
  308. | **Every Ubuntu LTS validated** — 22.04, 24.04 and 26.04 all at <!-- fig:lts_story_rate -->79/79<!-- /fig -->, each with a replay twin that reproduces it | ✅ |
  309. | Telegram approval interface | 📋 roadmap |
  310. **<!-- fig:rust_tests floor=1000 -->2,000+<!-- /fig --> Rust tests and <!-- fig:frontend_tests floor=10 -->70+<!-- /fig --> frontend tests** form the current deterministic
  311. release baseline.
  312. ## Configure your LLM
  313. SysKnife works with **Ollama** (no key, recommended for privacy / offline /
  314. homelab) or **OpenAI**, **Anthropic**, **Gemini**, **Groq**, **DeepSeek**,
  315. **Mistral**, **xAI**.
  316. ```toml
  317. # ~/.config/sysknife/config.toml
  318. [llm]
  319. provider = "ollama" # or anthropic / openai / gemini / groq / ...
  320. model = "qwen3:8b" # provider-specific
  321. ollama_url = "http://localhost:11434"
  322. max_turns = 10
  323. [daemon]
  324. socket = "/run/sysknife/daemon.sock"
  325. database = "/var/lib/sysknife/daemon.sqlite"
  326. [storage] # production-recommended
  327. backend = "postgres"
  328. url = "postgres://sysknife:${PG_PASSWORD}@db.example.com/audit?sslmode=verify-full"
  329. ```
  330. Env vars always win over the config file. Full reference in
  331. [`docs/configuration.md`](docs/configuration.md).
  332. ## MCP protocol
  333. SysKnife implements the [Model Context Protocol](https://modelcontextprotocol.io/)
  334. and exposes approval-gated planning and execution tools. `sysknife_plan`
  335. returns a daemon-issued transaction ID for each step. After reviewing the
  336. plan, the user runs `sysknife approve <transaction-id>` in a real terminal and
  337. gives the one-time receipt to the agent. `sysknife_execute` rejects missing,
  338. expired, mismatched, or replayed receipts. The MCP server cannot mint approval
  339. receipts itself.
  340. Use the setup wizard (above) to wire it into Claude Code, Cursor, or Codex CLI.
  341. All config files that may contain API keys are created with `chmod 0600`.
  342. ## Roadmap
  343. See [ROADMAP.md](ROADMAP.md) for the full milestone breakdown.
  344. - ✅ **Ubuntu 22.04** — <!-- fig:story_run:ubuntu-22.04-gpt-oss-120b -->79/79<!-- /fig --> stories on a live VM (recorded in `tests/evidence/story-runs/`)
  345. - ✅ **Ubuntu 24.04 and 26.04** — <!-- fig:story_run:ubuntu-24.04-gpt-oss-120b -->79/79<!-- /fig --> and <!-- fig:story_run:ubuntu-26.04-gpt-oss-120b -->79/79<!-- /fig --> on live VMs; every LTS run has a replay twin that reproduces it
  346. - ✅ `sysknife audit export` — stored signed chain rows as JSON with `--since` / `--limit`
  347. - 📋 Telegram inline-button approvals
  348. - 📋 CEF / NDJSON output modes for SIEM ingest
  349. - 📋 Fleet plan/execute (one plan, N targets, parallel approval)
  350. ## Protocol
  351. SysKnife is the reference implementation of the **LACS (Linux Agent Control
  352. Standard)** protocol — typed actions, risk classification, approval gates,
  353. audit requirements. The spec is CC0 (public domain):
  354. → **[lacs-project/specification](https://github.com/lacs-project/specification)**
  355. Other implementations for other distros and languages are explicitly
  356. encouraged.
  357. ## Contributing
  358. We want help. **Multi-distro** is the highest-impact area to plug into right
  359. now — see [`docs/distro-support.md`](docs/distro-support.md) for the
  360. roadmap matrix and [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow.
  361. Issues labelled
  362. [`good first issue`](https://github.com/lacs-project/sysknife/labels/good%20first%20issue)
  363. are scoped with clear acceptance criteria.
  364. ### Thanks
  365. Patches so far from [@ITSMERNB](https://github.com/ITSMERNB),
  366. [@QinXi-ai](https://github.com/QinXi-ai), [@Osheun](https://github.com/Osheun),
  367. [@danial-razi](https://github.com/danial-razi),
  368. [@vsolano9](https://github.com/vsolano9) and
  369. [@Georgefifth](https://github.com/Georgefifth). Every release names who fixed
  370. what in [CHANGELOG.md](CHANGELOG.md).
  371. If you send a patch, watching
  372. [Releases](https://github.com/lacs-project/sysknife/releases) is the quickest way
  373. to see it ship and to catch new `good first issue` entries as they land. A star
  374. helps other people find the project.
  375. ## Documentation
  376. - [Typed actions — why never a shell string](docs/typed-actions.md)
  377. - [Action reference — every action, generated from the code](docs/action-reference.md)
  378. - [The audit chain — Ed25519, public-key verifiable](docs/the-audit-chain.md)
  379. - [Automatic rollback](docs/automatic-rollback.md)
  380. - [SysKnife vs. alternatives](docs/comparison.md)
  381. - [Architecture overview](docs/architecture.md)
  382. - [Distro support matrix](docs/distro-support.md)
  383. - [Configuration](docs/configuration.md)
  384. - [Audit storage and recovery](docs/storage-cloud.md)
  385. - [Developer guide](docs/developer-guide.md)
  386. - [Testing guide](docs/contributing/testing.md)
  387. - [VM daemon setup](docs/vm-daemon-setup.md)
  388. - [Security policy](SECURITY.md)
  389. - [Release readiness checklist](docs/release-readiness.md)
  390. - [Roadmap](ROADMAP.md)
  391. - [ADR 0001 — System boundaries](docs/adr/0001-system-boundaries.md)
  392. - [ADR 0002 — Brain provider layer](docs/adr/0002-brain-provider-layer.md)
  393. - [ADR 0003 — IPC wire protocol](docs/adr/0003-ipc-wire-protocol.md)
  394. ## Where to find SysKnife
  395. | Channel | Install | Notes |
  396. |---------|---------|-------|
  397. | **npm** | `npx sysknife-setup` | [npmjs.com/package/sysknife-setup](https://www.npmjs.com/package/sysknife-setup) — setup wizard; needs Node 22+, no compile |
  398. | **crates.io** | `cargo install sysknife-cli` / `cargo install sysknife-daemon` | Needs `build-essential`; ~7-12 min build. Published by reviewed version tags; see [docs/release.md](docs/release.md) |
  399. | **MCP Registry** | `io.github.lacs-project/sysknife` | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) — resolves to the crates.io install above. Directory pages that sandbox a server list every tool but cannot call the ones needing the daemon; [docs/mcp-registry.md](docs/mcp-registry.md#what-a-directory-sandbox-can-and-cannot-tell-you) explains the split |
  400. | **GitHub Releases** | Download from [Releases](https://github.com/lacs-project/sysknife/releases) | Prebuilt x86_64 + aarch64 binaries with SHA-256 checksums on every tag |
  401. ## License
  402. [MIT](LICENSE). Free to use, modify, distribute, and embed in proprietary
  403. products without restriction.
  404. The [LACS specification](https://github.com/lacs-project/specification) is
  405. [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) — public domain.
  406. ---
  407. <p align="center">
  408. Built by <a href="https://github.com/vladimirrott">Vladimir Rotariu</a>.
  409. ·
  410. Issues, ideas, war stories — <a href="https://github.com/lacs-project/sysknife/discussions">come say hi</a>.
  411. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.