sentinel-cli

CLI and MCP server for the Sentinel DevOps portal. Manage deployments end-to-end from the terminal or via AI agents.

Install

python3.12 -m pip install payd-labs-sentinel-cli

Requires Python 3.12+.

Quick start

payd-sentinel login    # one-time OTP via Payd Auth, caches token at ~/.sentinel/

# End-to-end bootstrap of a new service (one command):
payd-sentinel bootstrap \
  --name my-app --type fastapi --domain my-app.paydlabs.com \
  --repo https://github.com/getpayd-tech/my-app \
  --create-db \
  --env SECRET_KEY="$(openssl rand -hex 32)" \
  --env APP_ENV=production \
  --deploy

Runs 7 steps: project create, env set, database create, Caddy route, server provision, write workflow to local git repo + set GitHub secret via gh, first deploy.

Command reference

Everyday ops

payd-sentinel status              # All projects + their latest deploy
payd-sentinel projects            # List projects
payd-sentinel services            # List containers
payd-sentinel deploy <project>    # Trigger deploy
payd-sentinel deploy <project> --tag v1.2.3
payd-sentinel rollback <project> <deploy-id>
payd-sentinel deployments [--project X]
payd-sentinel logs <container> [--tail 100] [--since 1h]
payd-sentinel restart|stop|start <container>
payd-sentinel audit [--action X] [--limit 30]

payd-sentinel deploy <project> --tag <sha> is authoritative for Sentinel-generated single-container and blended projects, where the project ghcr_image maps to one image or the generated -api and -ui images. For parameterized custom multi-image compose stacks, put a shared *IMAGE_TAG variable in the compose image: lines, for example CONNECT_IMAGE_TAG; Sentinel updates that variable in the compose file directory's .env before docker compose pull. For custom edge/router stacks, set --deploy-config with image prefixes and the edge service so Sentinel can assert the live service/image map before reporting success.

Example:

payd-sentinel project update payd-connect-v2-sandbox \
  --deploy-config '{"compose_source":"webhook_bundle","image_tag_variables":["CONNECT_IMAGE_TAG"],"project_image_prefixes":["ghcr.io/getpayd-tech/payd-connect-v2-sandbox-"],"edge_service":"payd-connect-v2-sandbox"}'

Projects

payd-sentinel project create <name> --type fastapi --domain X --repo URL
payd-sentinel project show <name>
payd-sentinel project update <name> --domain new --custom-domains
payd-sentinel project delete <name>
payd-sentinel project scan                     # Auto-discover /apps/
payd-sentinel project provision <name>         # Write compose + .env + Caddy
payd-sentinel project service-key <name>       # Generate API key for custom-domains API

Environment variables

payd-sentinel env list <project> [--reveal]
payd-sentinel env set <project> KEY=VAL KEY2=VAL2 ...
payd-sentinel env unset <project> KEY1 KEY2

Database (managed PostgreSQL)

payd-sentinel db list
payd-sentinel db create <name> [--password PW]
payd-sentinel db tables <db>
payd-sentinel db query <db> "SELECT * FROM ..."

Domains + TLS

payd-sentinel domain list
payd-sentinel domain add <domain> --upstream container:port [--tls auto|cloudflare_dns|on_demand|off]
payd-sentinel domain remove <domain>
payd-sentinel domain reload
payd-sentinel domain tls status|enable|disable
payd-sentinel custom-domain list [--project X]
payd-sentinel custom-domain remove <domain>

Security (fail2ban + SSH auth log)

payd-sentinel security banned [--jail sshd]
payd-sentinel security ban <ip> [--jail sshd]
payd-sentinel security unban <ip> [--jail sshd]
payd-sentinel security activity [--tail 50]
payd-sentinel security auth [--tail 50] [--type success|failure|info]
payd-sentinel security ip <ip>           # Full history (fail2ban + SSH)

Repo setup (close the loop on new services)

# End-to-end (recommended for new services):
payd-sentinel bootstrap --name X --type T --domain D --repo URL [...]

# For existing Sentinel projects that need the workflow added to their repo:
cd my-existing-repo
payd-sentinel repo setup <project>
#  -> fetches generated workflow YAML from Sentinel
#  -> writes .github/workflows/deploy.yml
#  -> runs `gh secret set SENTINEL_WEBHOOK_SECRET ...`
#  -> commits + pushes
# Flags: --no-secret, --no-commit, --message "msg"

Interactive wizard

payd-sentinel init    # prompts for each field, runs the 9-step wizard

Auth

Run payd-sentinel login once. Tokens are cached at ~/.sentinel/credentials.json with auto-refresh.

Or set SENTINEL_TOKEN env var with a valid admin JWT to skip the login flow.

Override the API URL: SENTINEL_URL=http://localhost:8000 payd-sentinel projects

MCP Server (for Claude Code / AI agents)

The package includes an MCP server that exposes 30 tools for AI agents.

Add to your Claude Code settings:

{
  "mcpServers": {
    "sentinel": {
      "command": "sentinel-mcp"
    }
  }
}

Available tools

Projects: sentinel_list_projects, sentinel_create_project, sentinel_update_project, sentinel_delete_project, sentinel_scan_projects, sentinel_provision_project, sentinel_project_status, sentinel_generate_service_key, sentinel_get_workflow

Deployments: sentinel_list_deployments, sentinel_deploy, sentinel_rollback

Services: sentinel_list_services, sentinel_restart_service, sentinel_stop_service, sentinel_start_service, sentinel_get_logs

Env: sentinel_list_env, sentinel_set_env, sentinel_unset_env

Database: sentinel_list_databases, sentinel_create_database, sentinel_list_tables, sentinel_db_query

Domains: sentinel_list_domains, sentinel_add_domain, sentinel_remove_domain, sentinel_reload_caddy, sentinel_list_custom_domains

Audit: sentinel_audit_log

The MCP server reads auth from ~/.sentinel/credentials.json (run payd-sentinel login first) or SENTINEL_TOKEN env var.

What is Sentinel?

Sentinel is a self-hosted DevOps portal for managing Docker container deployments behind Caddy reverse proxy. It provides webhook-based deploys, automatic health checks with rollback, custom domain management with on-demand TLS, fail2ban monitoring, and a web UI.

sentinel.paydlabs.com | GitHub | Self-hosting guide

Legacy alias: sentinel remains available for backwards compatibility.