Heinzel — System Administration with Safety Guardrails

Heinzel is a set of rules that turns an AI coding assistant into a cautious, methodical sysadmin. It works with Claude Code, OpenCode, or any other terminal-based AI tool that can read project files and run shell commands. It supports Linux, FreeBSD, and macOS — remote servers over SSH and the local machine alike.

Describe what you need in plain English, and the AI figures out the right commands for your OS, proposes each one with an explanation, and waits for your approval before running anything. It backs up configs, tests commands before real execution, remembers every server it has worked on, and gives you a detailed report when it's finished.

Using it feels like pair-programming with a colleague who always checks the docs first and never skips a step because he's in a hurry. The bigger the network, the more it pays off — the AI remembers every server's OS, services, and quirks so you don't have to. Not sure yet? Ask the AI to plan first before making changes — no changes until you say go.

Screencast: Debug and fix some webserver problems

Other Screencasts on YouTube

• Debug and fix a misconfigured nginx and firewall on a remote server (1 min)
• Install the latest stable Ruby and Ruby on Rails (1 min)
• Install a firewall, upgrade the Linux distribution and setup automatic daily security updates (2 min)

How It Works

1. Clone the repo and start your AI tool

   git clone https://github.com/wintermeyer/heinzel.git
   cd heinzel
   

   Then launch your preferred AI coding assistant from inside the directory (e.g. claude for Claude Code, opencode for OpenCode).
2. Describe what you need in plain English

   ❯ Install and configure nginx on web1.example.com
   

3. Review and approve each command before it runs The AI proposes every SSH command, explains what it does and why, and waits for your approval. Nothing runs without your say-so.

Auto-detection

The first time you point Heinzel at any machine, the AI detects the OS, gathers hardware info, and remembers everything for future sessions:

 ❯ What OS is installed on app.example.com?

 ❯ Install a firewall on app.example.com and
   configure it to allow SSH and HTTPS traffic.

DNS alias detection

When multiple DNS names point to the same server, Heinzel detects this automatically by comparing IP addresses. The first hostname becomes the canonical name; additional names become symlinks that share the same memory. Each alias can have its own SSH user.

Memory across sessions

After working on a machine, the AI remembers it. Next week you start a new session and type:

 ❯ Check on web1.example.com.

It reads memory/servers/web1.example.com/memory.md, already knows it's Debian 12 with nginx and PostgreSQL, checks the local changelog, and picks up right where it left off.

Session to-do list

When a multi-step task gets interrupted — connection drop, conversation ends, laptop closes — Heinzel keeps a to-do list in memory/servers/<hostname>/todo.md with checkboxes for each step. On reconnection it shows what's still pending and asks whether to continue or start fresh.

Housekeeping checks

Run routine health inspections on any server:

 ❯ Run housekeeping on bremen1.wintermeyer.de

Heinzel checks disk, memory, load, pending updates, firewall, SSL certificates, failed services, and server-specific services. Problems are highlighted at the top of a concise report.

Security audit

Check security configuration on any server:

 ❯ Run a security audit on app.example.com

Heinzel checks SSH password authentication settings, firewall status, and reports issues by severity.

Plan mode (Claude Code)

For complex or unfamiliar tasks, switch to plan mode before touching anything:

 ❯ /plan Migrate the database from MySQL to
   PostgreSQL on db.example.com

The AI explores the server, checks what's running, reads configs, and drafts a step-by-step plan — but makes no changes. You discuss the approach, adjust it, and only when you approve does execution begin.

Note: The /plan command is a Claude Code feature. OpenCode does not have an equivalent — simply ask the AI to plan before acting.

Local administration

Heinzel also works on the local machine — no SSH needed, commands run directly. The same safety rules, memory, and guardrails apply whether the target is a remote server or your own laptop.

This works on both Linux and macOS:

 ❯ Update all Homebrew packages on this Mac

 ❯ Check if the firewall is configured on
   this machine

Supported AI Tools

Heinzel is tool-agnostic. Any terminal-based AI coding assistant that reads project files and runs shell commands will pick up the rules in CLAUDE.md and the rules/ directory.

Claude Code

Claude Code is Anthropic's CLI for Claude. It natively reads CLAUDE.md and is the primary tool Heinzel was developed with.

claude

OpenCode with Ollama

OpenCode is an open-source terminal AI tool that supports many providers, including local free models via Ollama. This lets you run Heinzel entirely on your own hardware — no cloud API required.

1. Install Ollama and pull a model

ollama pull qwen3.5:9b

2. Expand the context window

Ollama defaults to 4096 tokens — too small for agentic tool use. Create a variant with a larger context:

ollama run qwen3.5:9b
>>> /set parameter num_ctx 16384
>>> /save qwen3.5:9b-16k
>>> /bye

3. Configure OpenCode

Copy the example config and adjust if needed:

cp opencode.json.example opencode.json

Edit opencode.json to match your setup — e.g. change the baseURL if Ollama runs on a different host (http://192.168.0.3:11434/v1), or change the model name. The file is gitignored so local edits won't conflict on git pull.

4. Launch OpenCode

opencode

Select the Ollama model from the model picker (search for qwen). Start the model picker by typing /models in the OpenCode terminal.

Note: Larger models (14B+) produce more reliable tool calls. If you have the GPU memory, prefer a bigger model. The tools: true flag is required for agentic features. See the OpenCode provider docs for more configuration options.

Command Line Interface

You can script Heinzel from the command line without entering the interactive UI.

Claude Code

Use the -p flag to pass a prompt directly:

$ claude --dangerously-skip-permissions \
  -p "What OS is installed on \
  server1.example.com? Login as root."
**server1.example.com** is running **Debian 11
(Bullseye)** on an aarch64 (ARM64) system with
4 CPU cores, 3.8 GB RAM, and a 15 GB root disk
(15% used).

Note: Debian 11 reached end of life in August
2024 and only receives long-term support (LTS)
until August 2026. You may want to plan an
upgrade to Debian 12 (Bookworm) before then.
$ claude --dangerously-skip-permissions \
  -p "Upgrade server1.example.com to Debian 12. \
  I have a backup. Don't ask me any questions. \
  Just do it. Give me a report afterwards."
---

## Upgrade Report: server1.example.com

**Debian 11 (Bullseye) -> Debian 12 (Bookworm)**
— completed successfully.

### What was done

1. **Verified Debian 11.11 was fully up to date**
   before starting
2. **Updated `/etc/apt/sources.list`** from
   `bullseye` to `bookworm` (backed up first)
3. **Ran `apt-get upgrade`** — installed packages
   that could upgrade without removals
4. **Ran `apt-get full-upgrade`** — completed the
   full dist-upgrade
5. **Cleaned up** — `autoremove` removed 28
   obsolete packages (410 MB freed)
6. **Rebooted** into the new kernel
   6.1.0-43-arm64
7. **Removed old kernel** 5.10.0-38-arm64
   (257 MB freed)
8. **Reinstalled `unattended-upgrades`** — it was
   dropped during the dist-upgrade

### Current state

|                         |                               |
| ----------------------- | ----------------------------- |
| **OS**                  | Debian 12.13 (Bookworm)       |
| **Kernel**              | 6.1.0-43-arm64                |
| **Disk**                | 15 GB, 19% used               |
| **nginx**               | running                       |
| **ufw**                 | active, default deny incoming |
| **unattended-upgrades** | installed and enabled         |

OpenCode

Use the run command to pass a prompt directly:

opencode run "What OS is installed on \
  server1.example.com?"

Useful flags for scripting:

• --format json — machine-readable JSON output
• -m provider/model — override the model
• -f file.txt — attach files to the prompt
• -c — continue the previous session

For repeated calls without startup overhead, use the headless server:

opencode serve
opencode run --attach http://localhost:4096 \
  "Check disk usage on web1.example.com"

About --dangerously-skip-permissions (Claude Code)

By default Claude Code asks for your approval before every tool call — every SSH command, every file read, every write. The --dangerously-skip-permissions flag disables these prompts so Claude runs everything without asking.

The name is intentional: it is dangerous. You give up the ability to review each command before it hits a live server. On the other hand, it makes scripting and batch work practical — you can't sit and approve 200 prompts during an unattended upgrade.

When it makes sense:

• Non-interactive / scripted