Kastell

[Kastell]

Kastell

Your infrastructure, fortified.

English | Türkçe

[Tests] [Coverage] [npm] [Downloads] [License] [GitHub stars] [Socket Badge] [Snyk] [Website] [DeepWiki] [Zero Telemetry]

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 memorizenpx 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.3.1  ·  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 serverkastell status my-server        # Check server statuskastell backup --all            # Backup all servers

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

What Makes Kastell Different?

Kastell vs Alternatives

What Can You Do?

Deploy

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

Manage

kastell list                  # List all serverskastell status my-server      # Check server statuskastell status --all          # Check all serverskastell ssh my-server         # SSH into serverkastell restart my-server     # Restart serverkastell destroy my-server     # Destroy cloud server entirelykastell add                   # Add existing serverkastell remove my-server      # Remove from local configkastell config set key value  # Manage default configurationkastell config validate       # Validate servers.yaml structure and typeskastell export                # Export server list to JSONkastell 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 executingkastell maintain my-server            # Full maintenance (snapshot + update + health + reboot)kastell maintain my-server --dry-run  # Preview maintenance stepskastell maintain --all                # Maintain all servers

Back Up & Restore

kastell backup my-server      # Backup DB + configkastell backup --all          # Backup all serverskastell restore my-server     # Restore from backup

Snapshots

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

Security

kastell firewall status my-server   # Check firewallkastell firewall setup my-server    # Configure UFWkastell secure audit my-server      # Security auditkastell secure setup my-server      # SSH hardening + fail2bankastell domain add my-server --domain example.com  # Set domain + SSL

Security Audit

kastell audit my-server                  # Full security audit (31 categories, 449 checks)kastell audit my-server --json           # JSON output for automationkastell audit my-server --threshold 70   # Exit code 1 if score below thresholdkastell audit my-server --fix            # Interactive fix mode (prompts per severity)kastell audit my-server --fix --dry-run  # Preview fixes without executingkastell audit my-server --watch          # Re-audit every 5 min, show only changeskastell audit my-server --watch 60       # Custom interval (60 seconds)kastell audit --host [email protected]       # Audit unregistered serverkastell audit my-server --badge          # SVG badge outputkastell audit my-server --report html    # Full HTML reportkastell audit my-server --score-only     # Just the score (CI-friendly)kastell audit my-server --summary        # Compact dashboard viewkastell audit my-server --explain        # Explain failed checks with remediation guidancekastell 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 usagekastell logs my-server                 # View platform logs (Coolify or Dokploy)kastell logs my-server -f              # Follow logskastell health                         # Health check all serverskastell doctor                         # Check local environment

Supported Providers

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

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

YAML Config

Deploy with a single config file:

# kastell.ymlprovider: hetznerregion: nbg1size: cax11name: my-coolifyfullSetup: truedomain: coolify.example.com

kastell init --config kastell.yml

Templates

kastell init --template production --provider hetzner

Security

Kastell is built with security as a priority -- 12,132 tests across 380 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.

Security behavior (v2.3.1)

This section documents security contracts shipped in v2.3.1. Future work is described elsewhere (see CHANGELOG.md for upcoming entries).

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

Installation

# Run directly (recommended)npx kastell <command>
# Or install globallynpm install -g kastellkastell <command>

Requires Node.js 20 or later.

Safety Modes

KASTELL_SAFE_MODE environment variable controls destructive operations:

• MCP default: true — provision, destroy, restore are blocked
• CLI default: false — all operations are enabled
• Override: KASTELL_SAFE_MODE=true kastell destroy <server> → rejected

Affected commands: init, destroy, backup-restore, snapshot-restore, snapshot-delete, restart, maintain.

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 11,206 tests across 344 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:

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

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.

v2.3 Reliability Contracts

These contracts apply to the CLI and the MCP server.

Provisioning behavior

server_provision returns after the provider creates the server and Kastell durably registers it. readiness.status may be pending; follow with server_info status or server_info health. The interactive kastell init command continues waiting through its existing readiness checks.

Automation contracts

• Unsupported and failed CLI operations return exit code 1.
• Valid empty results and user cancellation return 0.
• Mixed --all failures return 1.
• audit --json and audit --ci reserve stdout for one JSON payload.

CI/CD Integration

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

# .github/workflows/security-audit.ymlname: Security Auditon:  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