Kastell

What is Kastell about?

Kastell provides a unified CLI to provision VPS instances on Hetzner, DigitalOcean, Vultr, and Linode, apply security hardening, perform audits, create backups, manage snapshots, and monitor health. It integrates an AI‑driven Model Context Protocol (MCP) server so LLM agents can control servers via natural language prompts.

How to use Kastell?

1. Run without installation – npx kastell launches an interactive menu that guides you through deployment, security setup, backups, and maintenance.
2. Direct commands – Use explicit sub‑commands such as kastell init --provider hetzner, kastell audit my-server --fix, kastell backup --all, etc.
3. Configuration files – Supply a YAML file (kastell.yml) or JSON import/export to repeat deployments.
4. MCP integration – Start the built‑in MCP server (npx -y -p kastell kastell-mcp) and let compatible AI tools manage the infrastructure.

Key features of Kastell

• One‑click provisioning for four major cloud providers with pre‑configured Coolify or Dokploy platforms.
• Comprehensive security audit (457+ checks, 31 categories) with auto‑fix capability and compliance filtering (CIS, PCI‑DSS, HIPAA).
• Production hardening (kastell lock) – a 24‑step lock‑down covering SSH, UFW, sysctl, auditd, AIDE, Docker.
• Backup & snapshot management – DB/config backup, VPS snapshots with cost estimates, restore workflow.
• Live monitoring & diagnostics – CPU/RAM/disk metrics, platform logs, health checks, kastell doctor.
• AI‑native MCP server – exposes granular actions (audit, backup, secure, manage) to Claude, Cursor, VS Code, etc.
• Zero telemetry – no usage data leaves the host.
• Dry‑run mode for all destructive operations and extensive shell completions.

Use cases of Kastell

• Self‑hosted production environments – spin up a new VPS, harden it to compliance standards, and keep it monitored.
• Security compliance pipelines – run kastell audit --threshold 70 --json in CI/CD to enforce a minimum security score.
• Backup strategy – schedule kastell backup --all and snapshot creation to protect data across providers.
• DevOps automation – embed kastell maintain in cron jobs for pre‑update snapshots, updates, health checks, and automatic reboots.
• AI‑assisted operations – let an LLM agent issue server_secure or server_backup commands through the MCP interface.

FAQ from the Kastell

Q: Do I need to install Node globally? A: No. The recommended way is npx kastell, which runs the latest version without a permanent install.

Q: Which providers are supported? A: Hetzner, DigitalOcean, Vultr, and Linode (beta). Bare‑metal mode works on any SSH‑accessible VPS.

Q: How does the security audit differ from Lynis? A: Kastell not only reports findings but can automatically apply safe fixes and integrates compliance frameworks.

Q: Can I use Kastell without the AI features? A: Yes. All functionality works via the CLI; the MCP server is optional.

Q: Where are API tokens stored? A: Tokens are never written to disk. They are supplied via environment variables or prompted at runtime and are redacted in logs.

English | Türkçe

Why Kastell?

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

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.

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.

You don't need four separate tools to secure a server.

Quick Start

# Interactive mode -- no commands to memorize
npx kastell

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

 ██╗  ██╗  ██████╗  ███████╗████████╗███████╗██╗     ██╗
 ██║ ██╔╝  ██╔══██╗ ██╔════╝╚══██╔══╝██╔════╝██║     ██║
 █████╔╝   ███████║ ███████╗   ██║   █████╗  ██║     ██║
 ██╔═██╗   ██╔══██║ ╚════██║   ██║   ██╔══╝  ██║     ██║
 ██║  ██╗  ██║  ██║ ███████║   ██║   ███████╗███████╗███████╗
 ╚═╝  ╚═╝  ╚═╝  ╚═╝ ╚══════╝   ╚═╝   ╚══════╝╚══════╝╚══════╝

  KASTELL  v2.2.6  ·  Your infrastructure, fortified.

  $ kastell init --template production  → deploy a new server
  $ kastell status --all                → check all servers
  $ kastell secure setup                → harden SSH + fail2ban
  $ kastell maintain --all              → full maintenance cycle

? What would you like to do?
   Server Management
❯    Deploy a new server
     Add an existing server
     List all servers
     ...
   Security
     Harden SSH & fail2ban
     Manage firewall (UFW)
     ...

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

If you already know the commands, you can still use them directly:

kastell init                    # Deploy a new server
kastell status my-server        # Check server status
kastell backup --all            # Backup all servers

Kastell handles server provisioning, SSH key setup, firewall configuration, and platform installation automatically.

What Makes Kastell Different?

Problem	Solution
Broke your server with an update?	Pre-update snapshot protection via maintain
No idea if your server is healthy?	Built-in monitoring, health checks, and doctor diagnostics
Security is an afterthought?	Firewall, SSH hardening, SSL, and security audits built-in
Backups? Maybe someday...	One-command backup & restore with manifest tracking
Managing multiple servers?	--all flag across backup, maintain, status, and health
Existing server not tracked?	kastell add brings any server under management
Don't want to memorize commands?	Just run kastell -- interactive menu guides you

Kastell vs Alternatives

Feature	Kastell	Lynis	OpenSCAP
Installation	npm i -g kastell	Package manager	Package manager
Language	TypeScript	Shell	C/Python
Security Checks	457+	300+	Varies by profile
Auto-Fix	Safe tier	Suggest only	Suggest only
MCP (AI Agent)	14 tools	--	--
Compliance	CIS, PCI-DSS, HIPAA	CIS, HIPAA	CIS, STIG, PCI-DSS
Cloud Provision	4 providers	--	--
Hardening (Lock)	24-step	--	--
Remote Monitoring	Guard daemon	--	--
Telegram Bot	Built-in	--	--
Platform Support	Linux (SSH)	Linux/macOS/BSD	Linux
License	Apache 2.0	GPL-3.0	LGPL-2.1

What Can You Do?

Deploy

kastell                               # Interactive menu (recommended)
kastell init                          # Interactive setup (direct)
kastell init --provider hetzner       # Non-interactive
kastell init --config kastell.yml     # From YAML config
kastell init --template production    # Use a template
kastell init --mode bare              # Generic VPS (no platform)
kastell init --mode dokploy           # Dokploy (Docker Swarm PaaS)

Manage

kastell list                  # List all servers
kastell status my-server      # Check server status
kastell status --all          # Check all servers
kastell ssh my-server         # SSH into server
kastell restart my-server     # Restart server
kastell destroy my-server     # Destroy cloud server entirely
kastell add                   # Add existing server
kastell remove my-server      # Remove from local config
kastell config set key value  # Manage default configuration
kastell config validate       # Validate servers.yaml structure and types
kastell export                # Export server list to JSON
kastell import servers.json   # Import servers from JSON

Update & Maintain

kastell update my-server              # Update platform (Coolify or Dokploy, auto-detected)
kastell update my-server --dry-run    # Preview update without executing
kastell maintain my-server            # Full maintenance (snapshot + update + health + reboot)
kastell maintain my-server --dry-run  # Preview maintenance steps
kastell maintain --all                # Maintain all servers

Back Up & Restore

kastell backup my-server      # Backup DB + config
kastell backup --all          # Backup all servers
kastell restore my-server     # Restore from backup

Snapshots

kastell snapshot create my-server   # Create VPS snapshot (with cost estimate)
kastell snapshot list my-server     # List snapshots
kastell snapshot list --all         # List all snapshots across servers
kastell snapshot delete my-server   # Delete a snapshot

Security

kastell firewall status my-server   # Check firewall
kastell firewall setup my-server    # Configure UFW
kastell secure audit my-server      # Security audit
kastell secure setup my-server      # SSH hardening + fail2ban
kastell domain add my-server --domain example.com  # Set domain + SSL

Security Audit

kastell audit my-server                  # Full security audit (31 categories, 468+ checks)
kastell audit my-server --json           # JSON output for automation
kastell audit my-server --threshold 70   # Exit code 1 if score below threshold
kastell audit my-server --fix            # Interactive fix mode (prompts per severity)
kastell audit my-server --fix --dry-run  # Preview fixes without executing
kastell audit my-server --watch          # Re-audit every 5 min, show only changes
kastell audit my-server --watch 60       # Custom interval (60 seconds)
kastell audit --host root@1.2.3.4       # Audit unregistered server
kastell audit my-server --badge          # SVG badge output
kastell audit my-server --report html    # Full HTML report
kastell audit my-server --score-only     # Just the score (CI-friendly)
kastell audit my-server --summary        # Compact dashboard view
kastell audit my-server --explain        # Explain failed checks with remediation guidance
kastell audit my-server --compliance cis # Filter by compliance framework (cis-level1, cis-level2, pci-dss, hipaa)

Security Hardening

kastell lock my-server                        # 24-step production hardening (SSH + UFW + sysctl + auditd + AIDE + Docker)
kastell lock my-server --dry-run              # Preview hardening steps without applying

Monitor & Debug

kastell monitor my-server             # CPU, RAM, disk usage
kastell logs my-server                 # View platform logs (Coolify or Dokploy)
kastell logs my-server -f              # Follow logs
kastell health                         # Health check all servers
kastell doctor                         # Check local environment

Supported Providers

Provider	Status	Regions	Starting Price
Hetzner Cloud	Stable	EU, US	~€4/mo
DigitalOcean	Stable	Global	~$18/mo
Vultr	Stable	Global	~$12/mo
Linode (Akamai)	Beta	Global	~$12/mo

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.

Supported Platforms

Platform	Mode Flag	Min RAM	Min CPU	Description
Coolify	--mode coolify (default)	2 GB	2 vCPU	Docker-based PaaS (port 8000)
Dokploy	--mode dokploy	2 GB	2 vCPU	Docker Swarm-based PaaS (port 3000)
Bare	--mode bare	—	—	Generic VPS, no platform overhead

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

Developer Experience

Feature	Command / Flag	Description
Dry Run	--dry-run	Preview destructive commands without executing. Available on: destroy, update, restart, remove, maintain, restore, firewall, domain, backup, snapshot, secure.
Shell Completions	kastell completions bash|zsh|fish	Generate shell completion scripts for tab-completion of commands and options.
Config Validation	kastell config validate	Check servers.yaml for structural and type errors using Zod strict schemas.
Version Check	kastell --version	Shows current version and notifies if a newer version is available on npm.

YAML Config

Deploy with a single config file:

# kastell.yml
provider: hetzner
region: nbg1
size: cax11
name: my-coolify
fullSetup: true
domain: coolify.example.com

kastell init --config kastell.yml

Templates

Template	Best For	Includes
starter	Testing, side projects	1-2 vCPU, 2-4 GB RAM
production	Live applications	2-4 vCPU, 4-8 GB RAM, full hardening
dev	Development & CI/CD	Same as starter, no hardening

kastell init --template production --provider hetzner

Security

Kastell is built with security as a priority -- 9,871 tests across 219 suites, including dedicated security test suites.

• API tokens are never stored on disk -- prompted at runtime or via environment variables
• SSH keys are auto-generated if needed (Ed25519)
• All SSH connections use StrictHostKeyChecking=accept-new with IP validation (octet range) and environment filtering
• Shell injection protection on all user-facing inputs (spawn/spawnSync, no execSync)
• Provider error messages are sanitized to prevent token leakage
• stderr sanitization redacts IPs, home paths, tokens, and secrets from error output
• Config file token detection (22+ key patterns, case-insensitive, nested)
• Import/export operations strip sensitive fields and enforce strict file permissions (0o600)
• --full-setup enables UFW firewall and SSH hardening automatically
• MCP: SAFE_MODE (default: on) blocks all destructive operations, Zod schema validation on all inputs, path traversal protection on backup restore
• Claude Code hooks: destroy-block prevents accidental kastell destroy without --force, pre-commit audit guard warns on score drops
• Zero Telemetry — Kastell collects no usage data, analytics, or telemetry. Your server data never leaves your machine.

Installation

# Run directly (recommended)
npx kastell <command>

# Or install globally
npm install -g kastell
kastell <command>

Requires Node.js 20 or later.

Troubleshooting

Server creation fails? Run kastell doctor --check-tokens to verify your API token and local environment.

Server not responding? Use kastell status my-server --autostart to check platform status and auto-restart if needed, or kastell health to check all servers at once.

Need to start fresh? kastell destroy my-server removes the cloud server entirely.

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

Kastell uses 9,871 tests across 219 suites. Run npm test before submitting PRs.

MCP Server (AI Integration)

Kastell includes a built-in Model Context Protocol server for AI-powered server management. Works with Claude Code, Cursor, Windsurf, and other MCP-compatible clients.

{
  "mcpServers": {
    "kastell": {
      "command": "npx",
      "args": ["-y", "-p", "kastell", "kastell-mcp"],
      "env": {
        "HETZNER_TOKEN": "your-token",
        "DIGITALOCEAN_TOKEN": "your-token",
        "VULTR_TOKEN": "your-token",
        "LINODE_TOKEN": "your-token"
      }
    }
  }
}

Available tools:

Tool	Actions	Description
server_info	list, status, health, sizes	Query server information, check cloud provider and platform status
server_logs	logs, monitor	Fetch platform/Docker logs and system metrics via SSH
server_manage	add, remove, destroy	Register, unregister, or destroy cloud servers
server_maintain	update, restart, maintain	Update platform, restart servers, run full maintenance
server_secure	secure, firewall, domain	SSH hardening, firewall rules, domain/SSL management (10 subcommands)
server_backup	backup, snapshot	Backup/restore databases and create/manage VPS snapshots
server_provision	create	Provision new servers on cloud providers
server_audit	audit	457+-check security audit with compliance framework filtering; use --explain for remediation guidance
server_evidence	collect	Collect forensic evidence package with checksums
server_guard	start, stop, status	Manage autonomous security monitoring daemon
server_doctor	diagnose	Proactive health analysis with remediation commands
server_lock	harden	24-step production hardening (SSH, UFW, sysctl, auditd, AIDE, Docker)
server_fleet	overview	Fleet-wide health and security posture dashboard
server_fix	fix --safe	Apply safe auto-fixes with backup (SAFE tier only, dryRun default)

All destructive operations (destroy, restore, snapshot-delete, provision, restart, maintain, snapshot-create) require SAFE_MODE=false to execute.

Claude Code Plugin

Kastell is available as a Claude Code plugin for the Anthropic marketplace. The plugin bundles:

• 4 skills: kastell-ops (architecture reference), kastell-scaffold (component generation), kastell-careful (destructive op guard), kastell-research (codebase exploration)
• 2 agents: kastell-auditor (parallel audit analyzer), kastell-fixer (worktree-isolated auto-fix)
• 5 hooks: destroy-block, session-audit, session-log, pre-commit-audit-guard, stop-quality-check

Install via Claude Code plugin manager or use directly with claude --plugin-dir kastell-plugin.

MCP Platform Setup

Platform	Config Location	Guide
Claude Code	claude mcp add or .mcp.json	Setup Guide
Claude Desktop	claude_desktop_config.json	Setup Guide
VS Code / Copilot	.vscode/mcp.json	Setup Guide
Cursor	.cursor/mcp.json	Setup Guide

More platforms (JetBrains, Windsurf, Gemini, and others) coming in v2.0.

AI Discoverability

Kastell provides llms.txt for AI crawlers and is listed in the MCP Registry as io.github.kastelldev/kastell.

CI/CD Integration

Use kastell audit in your CI pipeline to enforce security baselines:

# .github/workflows/security-audit.yml
name: Security Audit
on:
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday 6 AM
  workflow_dispatch:
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g kastell
      - run: kastell audit --host root@${{ secrets.SERVER_IP }} --threshold 70 --json > audit-result.json
      - uses: actions/upload-artifact@v4
        with:
          name: audit-report
          path: audit-result.json

The --threshold flag causes a non-zero exit code when the score falls below the target, failing the CI job automatically.

What's Next

• Test Excellence: Mutation testing, coverage gaps, integration tests (v1.14)
• Plugin ecosystem with marketplace distribution (v2.0)
• Dashboard and managed service (v3.0)

Philosophy

Infrastructure should be boring, predictable, and safe.

Kastell is not a script. It's your DevOps safety layer for self-hosted infrastructure.

License

Apache 2.0 -- see LICENSE

Support

• GitHub Issues -- Bug reports and feature requests
• Changelog -- Version history

---

Built by @omrfc