# lacs-project/sysknife [Health: Active]
**Category:** ๐ฅ๏ธ Command Line
**Repository:** https://github.com/lacs-project/sysknife
**GitHub Stars:** 5
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/lacs-project-sysknife
## Description
Security-hardened MCP server for Linux system administration via 189 typed actions instead of shell strings, with an Ed25519-signed hash-chain audit log, one-time TTL approval receipts, and automatic rollback. Works with Claude Code, Cursor, and Codex CLI.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"sysknife": {
"command": "npx",
"args": ["-y","sysknife-setup"]
}
}
```
## Documentation & README
SysKnife
Your sysadmin co-pilot. Plan. Approve. Audit.
Distros
Install ยท
How it works ยท
Why not X? ยท
Distro matrix ยท
Roadmap ยท
Contribute ยท
Discuss
Illustrative reproduction of the Claude Code MCP flow โ same flow works in Cursor and Codex CLI.
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](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.
[](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 ` 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.
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).
```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 22.04 records 49/50 stories on a live VM; the run that produced that
figure is in `tests/evidence/story-runs/`. Ubuntu 24.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.
Dry run โ plan only, nothing executes
```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"
```
## 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](docs/cli.md).
> **Also: a desktop GUI โ a distant third option.** An experimental Tauri
> desktop app (`sysknife-shell`) wraps the same plan โ approve โ execute loop in
> a window. It is the least frequently maintained surface, well behind the MCP
> integration and the CLI, so reach for it only if you specifically want a
> graphical approval flow.
## How it works
```
sysknife-brain โ sysknife-shell โ sysknife-daemon
(planner) (approval gate) (executor)
talks to LLM shows the plan, only privileged
never to OS takes y/n process; signs
every action
```
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?
| Tool | The gap |
|---|---|
| **Open Interpreter** | Runs arbitrary Python/Shell. No formal risk model. No audit chain. |
| **Goose / Continue** | General-purpose. Ad-hoc confirmation, not typed risk levels. |
| **Claude Computer Use** | Uncontrolled desktop automation, not system administration. |
| **Ansible** | YAML written in advance. Not conversational. No risk classification. |
| **shell-gpt / Copilot** | Suggests raw shell commands. You still run raw shell. |
| **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. |
| **Manual** | No audit trail. No rollback. One typo = lost work. |
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](docs/comparison.md) 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.
| Component | State |
|---|---|
| `sysknife-brain` โ LLM planner, tool loop, safety fence | โ
|
| `sysknife-daemon` โ 189 typed actions, auth, preview, transactions | โ
|
| Live IPC + streaming + atomic-host rollback (rpm-ostree) | โ
|
| Terminal approval gate โ one-time, TTL-bounded receipts | โ
|
| MCP server (Claude Code / Cursor / any MCP client) | โ
|
| Tamper-evident Ed25519-signed audit chain | โ
|
| RFC 5424 syslog forwarding (Splunk / Sentinel / QRadar) | โ
|
| Postgres backend (RDS / Cloud SQL / Neon / Supabase) | โ
|
| **Ubuntu support** โ 49/50 stories on a live 22.04 VM, recorded in `tests/evidence/story-runs/` | โ
|
| **Ubuntu 22.04 / 26.04 VM tooling** โ smoke tests pass on all three LTSes | โ
|
| Telegram approval interface | ๐ roadmap |
**1,711 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**.
```toml
# ~/.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`](docs/configuration.md).
## MCP protocol
SysKnife implements the [Model Context Protocol](https://modelcontextprotocol.io/)
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](ROADMAP.md) for the full milestone breakdown.
- โ
**Ubuntu 22.04** โ 49/50 stories on a live VM (recorded in `tests/evidence/story-runs/`)
- โ
**Ubuntu 22.04 / 26.04** โ VM tooling complete; smoke tests pass on all three LTSes
- ๐ Telegram inline-button approvals
- ๐ `sysknife audit export` (CEF / NDJSON 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](https://github.com/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`](docs/distro-support.md) for the
roadmap matrix and [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow.
Issues labelled
[`good first issue`](https://github.com/lacs-project/sysknife/labels/good%20first%20issue)
are scoped with clear acceptance criteria.
## Documentation
- [Typed actions โ why never a shell string](docs/typed-actions.md)
- [Action reference โ every action, generated from the code](docs/action-reference.md)
- [The audit chain โ Ed25519, public-key verifiable](docs/the-audit-chain.md)
- [Automatic rollback](docs/automatic-rollback.md)
- [SysKnife vs. alternatives](docs/comparison.md)
- [Architecture overview](docs/architecture.md)
- [Distro support matrix](docs/distro-support.md)
- [Configuration](docs/configuration.md)
- [Audit storage and recovery](docs/storage-cloud.md)
- [Developer guide](docs/developer-guide.md)
- [Testing guide](docs/contributing/testing.md)
- [VM daemon setup](docs/vm-daemon-setup.md)
- [Security policy](SECURITY.md)
- [Release readiness checklist](docs/release-readiness.md)
- [Roadmap](ROADMAP.md)
- [ADR 0001 โ System boundaries](docs/adr/0001-system-boundaries.md)
- [ADR 0002 โ Brain provider layer](docs/adr/0002-brain-provider-layer.md)
- [ADR 0003 โ IPC wire protocol](docs/adr/0003-ipc-wire-protocol.md)
## Where to find SysKnife
| Channel | Install | Notes |
|---------|---------|-------|
| **npm** | `npx sysknife-setup` | [npmjs.com/package/sysknife-setup](https://www.npmjs.com/package/sysknife-setup) โ setup wizard; needs Node 18+, no compile |
| **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) |
| **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 |
| **GitHub Releases** | Download from [Releases](https://github.com/lacs-project/sysknife/releases) | Prebuilt x86_64 + aarch64 binaries with SHA-256 checksums on every tag |
## License
[MIT](LICENSE). Free to use, modify, distribute, and embed in proprietary
products without restriction.
The [LACS specification](https://github.com/lacs-project/specification) is
[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) โ public domain.
---
Built by Vladimir Rotariu.
ยท
Issues, ideas, war stories โ come say hi.