HostKit CLI

Python CLI for managing projects, services, and infrastructure on a HostKit VPS. Runs on the server and is called by the MCP server over SSH (or directly by operators).

Installation

Via bootstrap script (recommended)

The bootstrap script installs the CLI as part of full VPS setup:

curl -fsSL https://raw.githubusercontent.com/hostkit/hostkit/main/install/bootstrap.sh | bash

Via pip

pip install hostkit

From source

cd packages/cli
pip install -e .

Requirements

• Python 3.11+
• Ubuntu 22.04+ (server-side)
• PostgreSQL, Redis, nginx (installed by bootstrap)

Usage

# System overview
hostkit status
hostkit status --json

# Project lifecycle
hostkit project create myapp --python --with-db --with-auth
hostkit deploy myapp --install
hostkit rollback myapp
hostkit health myapp

# Services
hostkit auth enable myapp
hostkit payments enable myapp
hostkit sms enable myapp
hostkit chatbot enable myapp
hostkit minio enable myapp --public

# Database
hostkit db create myapp
hostkit db migrate myapp
hostkit backup create myapp --r2

# Operations
hostkit service logs myapp
hostkit env set myapp KEY=value
hostkit diagnose myapp
hostkit validate myapp

Every command supports --json for machine-readable output.

Command Reference

Configuration

The CLI reads configuration from /etc/hostkit/config.yaml:

domain: hostkit.dev
data_dir: /var/lib/hostkit
log_dir: /var/log/hostkit
backup_dir: /backups

Project layout on disk

Each project maps to:

/home/{project}/
├── releases/           # Timestamped deploys
├── app -> releases/x/  # Current release (symlink)
├── shared/             # Persistent data across deploys
├── .env                # Environment variables
├── .auth/              # Auth service (if enabled)
├── .payments/          # Payments service (if enabled)
└── venv/ or node_modules/

Runtimes

Service port allocation

Each project gets a base port (starting at 8001). Services use offsets:

Development

cd packages/cli
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Lint
ruff check src/

# Type check
mypy src/hostkit/

# Test
pytest

To deploy changes to a live VPS:

VPS_HOST=root@YOUR_VPS_IP ./scripts/deploy.sh