![\"Kastell\"](\"assets/logo.png\"){kind=logo}
\n\n \n
Your infrastructure, fortified.
\n\n> English | [Türkçe](README.tr.md)\n\n\n[](https://app.codecov.io/gh/kastelldev/kastell)\n\n\n\n\n[](https://socket.dev/npm/package/kastell)\n[](https://snyk.io/test/github/kastelldev/kastell)\n[](https://kastell.dev)\n[](https://deepwiki.com/kastelldev/kastell)\n\n\n## Why Kastell?\n\nServer security is fragmented. Lynis scans but doesn't fix. OpenSCAP is powerful but complex. Custom scripts work until they don't -- and nobody maintains them. Each tool has its own output format, its own update cycle, its own learning curve.\n\n**Kastell takes a different approach:** one CLI that audits, fixes, hardens, and monitors. Scan your server, apply safe fixes, lock it down to production standards, and keep watching -- all with the same tool.\n\n**AI-native from day one.** Kastell ships with a built-in MCP server, so Claude, Cursor, or any MCP-compatible AI agent can manage your servers directly. Go from a prompt to production hardening in seconds.\n\nYou don't need four separate tools to secure a server.\n\n## Quick Start\n\n```bash\n# Interactive mode -- no commands to memorize\nnpx kastell\n```\n\nRunning `kastell` without any arguments launches an **interactive search menu** with a gradient ASCII banner and quick-start examples. Browse actions by emoji-categorized groups, type to filter results instantly, and configure options step by step -- no need to remember any command names or flags.\n\n```\n ██╗ ██╗ ██████╗ ███████╗████████╗███████╗██╗ ██╗\n ██║ ██╔╝ ██╔══██╗ ██╔════╝╚══██╔══╝██╔════╝██║ ██║\n █████╔╝ ███████║ ███████╗ ██║ █████╗ ██║ ██║\n ██╔═██╗ ██╔══██║ ╚════██║ ██║ ██╔══╝ ██║ ██║\n ██║ ██╗ ██║ ██║ ███████║ ██║ ███████╗███████╗███████╗\n ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚═╝ ╚══════╝╚══════╝╚══════╝\n\n KASTELL v2.3.1 · Your infrastructure, fortified.\n\n $ kastell init --template production → deploy a new server\n $ kastell status --all → check all servers\n $ kastell secure setup → harden SSH + fail2ban\n $ kastell maintain --all → full maintenance cycle\n\n? What would you like to do?\n Server Management\n❯ Deploy a new server\n Add an existing server\n List all servers\n ...\n Security\n Harden SSH & fail2ban\n Manage firewall (UFW)\n ...\n```\n\nEach action includes sub-options (server mode, template, log source, port number, etc.) and a **<- Back** option to return to the main menu at any point.\n\nIf you already know the commands, you can still use them directly:\n\n```bash\nkastell init # Deploy a new server\nkastell status my-server # Check server status\nkastell backup --all # Backup all servers\n```\n\nKastell handles server provisioning, SSH key setup, firewall configuration, and platform installation automatically.\n\n## What Makes Kastell Different?\n\n| Problem | Solution |\n|---------|----------|\n| Broke your server with an update? | Pre-update snapshot protection via `maintain` |\n| No idea if your server is healthy? | Built-in monitoring, health checks, and `doctor` diagnostics |\n| Security is an afterthought? | Firewall, SSH hardening, SSL, and security audits built-in |\n| Backups? Maybe someday... | One-command backup & restore with manifest tracking |\n| Managing multiple servers? | `--all` flag across backup, maintain, status, and health |\n| Existing server not tracked? | `kastell add` brings any server under management |\n| Don't want to memorize commands? | Just run `kastell` -- interactive menu guides you |\n\n## Kastell vs Alternatives\n\n| Feature | Kastell | Lynis | OpenSCAP |\n|---------|---------|-------|----------|\n| Installation | `npm i -g kastell` | Package manager | Package manager |\n| Language | TypeScript | Shell | C/Python |\n| Security Checks | 449 | 300+ | Varies by profile |\n| Auto-Fix | Safe tier | Suggest only | Suggest only |\n| MCP (AI Agent) | 17 tools | -- | -- |\n| Compliance | CIS, PCI-DSS, HIPAA | CIS, HIPAA | CIS, STIG, PCI-DSS |\n| Cloud Provision | 4 providers | -- | -- |\n| Hardening (Lock) | 24-step | -- | -- |\n| Remote Monitoring | Guard daemon | -- | -- |\n| Telegram Bot | Built-in | -- | -- |\n| Platform Support | Linux (SSH) | Linux/macOS/BSD | Linux |\n| License | Apache 2.0 | GPL-3.0 | LGPL-2.1 |\n\n## What Can You Do?\n\n### Deploy\n```bash\nkastell # Interactive menu (recommended)\nkastell init # Interactive setup (direct)\nkastell init --provider hetzner # Non-interactive\nkastell init --config kastell.yml # From YAML config\nkastell init --template production # Use a template\nkastell init --mode bare # Generic VPS (no platform)\nkastell init --mode dokploy # Dokploy (Docker Swarm PaaS)\n```\n\n### Manage\n```bash\nkastell list # List all servers\nkastell status my-server # Check server status\nkastell status --all # Check all servers\nkastell ssh my-server # SSH into server\nkastell restart my-server # Restart server\nkastell destroy my-server # Destroy cloud server entirely\nkastell add # Add existing server\nkastell remove my-server # Remove from local config\nkastell config set key value # Manage default configuration\nkastell config validate # Validate servers.yaml structure and types\nkastell export # Export server list to JSON\nkastell import servers.json # Import servers from JSON\n```\n\n### Update & Maintain\n```bash\nkastell update my-server # Update platform (Coolify or Dokploy, auto-detected)\nkastell update my-server --dry-run # Preview update without executing\nkastell maintain my-server # Full maintenance (snapshot + update + health + reboot)\nkastell maintain my-server --dry-run # Preview maintenance steps\nkastell maintain --all # Maintain all servers\n```\n\n### Back Up & Restore\n```bash\nkastell backup my-server # Backup DB + config\nkastell backup --all # Backup all servers\nkastell restore my-server # Restore from backup\n```\n\n### Snapshots\n```bash\nkastell snapshot create my-server # Create VPS snapshot (with cost estimate)\nkastell snapshot list my-server # List snapshots\nkastell snapshot list --all # List all snapshots across servers\nkastell snapshot delete my-server # Delete a snapshot\n```\n\n### Security\n```bash\nkastell firewall status my-server # Check firewall\nkastell firewall setup my-server # Configure UFW\nkastell secure audit my-server # Security audit\nkastell secure setup my-server # SSH hardening + fail2ban\nkastell domain add my-server --domain example.com # Set domain + SSL\n```\n\n### Security Audit\n```bash\nkastell audit my-server # Full security audit (31 categories, 449 checks)\nkastell audit my-server --json # JSON output for automation\nkastell audit my-server --threshold 70 # Exit code 1 if score below threshold\nkastell audit my-server --fix # Interactive fix mode (prompts per severity)\nkastell audit my-server --fix --dry-run # Preview fixes without executing\nkastell audit my-server --watch # Re-audit every 5 min, show only changes\nkastell audit my-server --watch 60 # Custom interval (60 seconds)\nkastell audit --host root@1.2.3.4 # Audit unregistered server\nkastell audit my-server --badge # SVG badge output\nkastell audit my-server --report html # Full HTML report\nkastell audit my-server --score-only # Just the score (CI-friendly)\nkastell audit my-server --summary # Compact dashboard view\nkastell audit my-server --explain # Explain failed checks with remediation guidance\nkastell audit my-server --compliance cis # Filter by compliance framework (cis-level1, cis-level2, pci-dss, hipaa)\n```\n\n### Security Hardening\n```bash\nkastell lock my-server # 24-step production hardening (SSH + UFW + sysctl + auditd + AIDE + Docker)\nkastell lock my-server --dry-run # Preview hardening steps without applying\n```\n\n### Monitor & Debug\n```bash\nkastell monitor my-server # CPU, RAM, disk usage\nkastell logs my-server # View platform logs (Coolify or Dokploy)\nkastell logs my-server -f # Follow logs\nkastell health # Health check all servers\nkastell doctor # Check local environment\n```\n\n## Supported Providers\n\n| Provider | Status | Regions | Starting Price |\n|----------|--------|---------|---------------|\n| [Hetzner Cloud](https://hetzner.cloud) | Stable | EU, US | ~€4/mo |\n| [DigitalOcean](https://digitalocean.com) | Stable | Global | ~$18/mo |\n| [Vultr](https://vultr.com) | Stable | Global | ~$12/mo |\n| [Linode (Akamai)](https://linode.com) | Beta | Global | ~$12/mo |\n\n> Prices reflect the cheapest plan with at least 2 GB RAM (required by Coolify and Dokploy). Bare mode has no minimum requirements -- plans start from ~$2.50/mo depending on provider. You can choose a different size during setup. Linode support is in beta -- community testing welcome.\n\n## Supported Platforms\n\n| Platform | Mode Flag | Min RAM | Min CPU | Description |\n|----------|-----------|---------|---------|-------------|\n| Coolify | `--mode coolify` (default) | 2 GB | 2 vCPU | Docker-based PaaS (port 8000) |\n| Dokploy | `--mode dokploy` | 2 GB | 2 vCPU | Docker Swarm-based PaaS (port 3000) |\n| Bare | `--mode bare` | — | — | Generic VPS, no platform overhead |\n\nKastell uses a **PlatformAdapter** architecture -- the same commands (`update`, `maintain`, `logs`, `health`) work across all platforms. The platform is stored in your server record and auto-detected on each command.\n\n## Developer Experience\n\n| Feature | Command / Flag | Description |\n|---------|---------------|-------------|\n| Dry Run | `--dry-run` | Preview destructive commands without executing. Available on: destroy, update, restart, remove, maintain, restore, firewall, domain, backup, snapshot, secure. |\n| Shell Completions | `kastell completions bash\\|zsh\\|fish` | Generate shell completion scripts for tab-completion of commands and options. |\n| Config Validation | `kastell config validate` | Check `servers.yaml` for structural and type errors using Zod strict schemas. |\n| Version Check | `kastell --version` | Shows current version and notifies if a newer version is available on npm. |\n\n## YAML Config\n\nDeploy with a single config file:\n\n```yaml\n# kastell.yml\nprovider: hetzner\nregion: nbg1\nsize: cax11\nname: my-coolify\nfullSetup: true\ndomain: coolify.example.com\n```\n\n```bash\nkastell init --config kastell.yml\n```\n\n## Templates\n\n| Template | Best For | Includes |\n|----------|----------|----------|\n| `starter` | Testing, side projects | 1-2 vCPU, 2-4 GB RAM |\n| `production` | Live applications | 2-4 vCPU, 4-8 GB RAM, full hardening |\n| `dev` | Development & CI/CD | Same as starter, no hardening |\n\n```bash\nkastell init --template production --provider hetzner\n```\n\n## Security\n\nKastell is built with security as a priority -- **12,132 tests** across 380 suites, including dedicated security test suites.\n\n- API tokens are never stored on disk -- prompted at runtime or via environment variables\n- SSH keys are auto-generated if needed (Ed25519)\n- All SSH connections use `StrictHostKeyChecking=accept-new` with IP validation (octet range) and environment filtering\n- Shell injection protection on all user-facing inputs (`spawn`/`spawnSync`, no `execSync`)\n- Provider error messages are sanitized to prevent token leakage\n- stderr sanitization redacts IPs, home paths, tokens, and secrets from error output\n- Config file token detection (22+ key patterns, case-insensitive, nested)\n- Import/export operations strip sensitive fields and enforce strict file permissions (`0o600`)\n- `--full-setup` enables UFW firewall and SSH hardening automatically\n- MCP: SAFE_MODE (default: on) blocks all destructive operations, Zod schema validation on all inputs, path traversal protection on backup restore\n- Claude Code hooks: destroy-block prevents accidental `kastell destroy` without `--force`, pre-commit audit guard warns on score drops\n- **Zero Telemetry** — Kastell collects no usage data, analytics, or telemetry. Your server data never leaves your machine.\n\n## Security behavior (v2.3.1)\n\nThis section documents security contracts shipped in v2.3.1. Future work is described elsewhere (see `CHANGELOG.md` for upcoming entries).\n\n- **`KASTELL_STRICT_HOST_KEY=true`** — when set, Kastell rejects unknown SSH host keys outright. Direct SSH connections (i.e. those that go through `accept-new`) emit a one-time Trust-On-First-Use (TOFU) warning so operators see the risk; combined with `KASTELL_STRICT_HOST_KEY=true`, the warning is promoted to a hard error.\n- **Non-TTY destructive commands** — in non-interactive environments (CI, scripts, automation), destructive operations require an explicit `--force` flag or the command's documented opt-in flag. Without one, the command exits with a non-zero status and a clear error.\n- **Structured skipped checks** — checks that are skipped (e.g. VPS-irrelevant, platform-mismatch, missing prerequisite) appear in audit output as a neutral, visible result rather than being silently dropped. Operators can see exactly which checks did not run and why.\n- **Windows secret files** — secret-bearing files written by Kastell on Windows receive restrictive ACLs (owner-only access). `0o600` POSIX permissions remain the source of truth on Linux/macOS; Windows uses the equivalent DACL.\n- **QuickWin JSON shape** — `audit --json` QuickWin entries now include a stable `id` (check ID) and `severity` field, in addition to the existing `description` and `commands`. This makes QuickWins programmatically consumable without parsing the human-readable description.\n- **FORBIDDEN previews include reasons** — when previewing fixes with `--dry-run` (or via `server_fix` MCP dry-run), each FORBIDDEN-tier fix now renders a short reason explaining why the fix is classified FORBIDDEN (e.g. \"requires reboot\", \"disrupts active SSH sessions\"). The reason is sourced from the check's `forbiddenReason` field.\n\n## Installation\n\n```bash\n# Run directly (recommended)\nnpx kastell