Elestio Skill

Version: 2.4 Purpose: Deploy and manage services on Elestio DevOps platform Status: Ready to use Last Updated: 2026-09-22

Elestio is a fully managed DevOps platform. Dedicated VMs (not shared Kubernetes). 400+ open-source templates, 9 cloud providers, 100+ regions. Handles deployment, security, updates, backups, monitoring, support.

This skill uses the official Elestio CLI (elestio command, installed via npm install -g elestio). When the Elestio MCP connector is available instead (tools such as deploy_template, deploy_catalog_pipeline, list_clusters), use its tools: the rules below apply the same way. See "Using the Elestio MCP connector" for the tool that matches each command.

When to Use This Skill

Use this skill when:

User wants to deploy PostgreSQL, MySQL, Redis, MongoDB, Elasticsearch, etc.
User says "deploy", "spin up", "create a server", "I need a database"
User mentions ANY open-source software (WordPress, Grafana, n8n, Metabase, etc.)
User wants to deploy custom code via CI/CD
User needs to manage backups, firewall, SSL, SSH access
User asks about service status, costs, or credentials

Trigger phrases:

"Deploy PostgreSQL" -> elestio deploy postgresql
"I need a Redis cache" -> elestio deploy redis
"Set up n8n for automation" -> elestio deploy n8n
"Deploy my app from GitHub" -> CI/CD workflow (Phase 4)
"What services are running?" -> elestio services
"How much is this costing?" -> elestio billing

When NOT to Use This Skill

Initial account setup - Signup, payment, approval must be done manually by human
Interactive SSH sessions - Use direct SSH instead
Complex Docker Compose editing - SSH into the server directly

Decision Tree: What Should I Deploy?

There are THREE deployment shapes, not two. Choosing wrong is the single most common cause of a failed deployment.

Is the software in the Elestio catalog?  (elestio templates search <name>)
|
+-- YES
|   |
|   +-- Does the user want a managed, isolated VM?  (production databases,
|   |   anything needing backups / monitoring / support)
|   |       -> MANAGED SERVICE
|   |          elestio deploy <template> --project <id>
|   |
|   +-- Does the user want replication / high availability?
|   |       -> CLUSTER   (19 templates only: elestio clusters templates)
|   |          elestio deploy <template> --cluster --nodes <n> --project <id>
|   |
|   +-- Does the user want it cheap, or several apps on one VM?
|           -> PIPELINE FROM CATALOG TEMPLATE
|              elestio cicd deploy-template <software> --target <vmID>
|
+-- NO, it is the user's own code
    |
    +-- In a Git repo?
    |       -> elestio cicd create --auto --target <vmID> --name X --repo owner/repo
    |
    +-- Just a docker-compose file?
            -> elestio cicd create <pipeline.json>

CRITICAL: catalog software in a pipeline

To run catalog software (Vaultwarden, Redis, Metabase, ...) on a CI/CD target, you MUST use elestio cicd deploy-template (MCP: deploy_catalog_pipeline). You must NOT use elestio cicd create (MCP: create_pipeline_docker / create_pipeline_auto).

cicd create builds an EMPTY pipeline. It does not know the software's ports, environment variables or install scripts, so the pipeline deploys and nothing runs. This is the most frequently reported failure.

deploy-template reads the template's elestio.yml (from github.com/elestio-examples/<software>) and configures the pipeline from it.

# RIGHT
elestio cicd deploy-template vaultwarden --target <vmID>

# WRONG -- produces an empty pipeline
elestio cicd create --auto --target <vmID> --name vaultwarden --repo elestio-examples/vaultwarden

From CLI 1.3.0 this works for the whole catalogue, including software that mounts files from its repo or needs its install scripts (Chromadb, Kafka, ClickHouse, WordPress, n8n...). The pipeline points at the elestio-examples repo and Elestio clones it on the VM itself, so those files exist and the scripts run. No Git account, nothing copied anywhere.

On CLI 1.2.x and earlier, the only route inlined the compose file, and roughly half the catalogue could not work that way. If you are on an older CLI, upgrade (npm install -g elestio@latest) rather than falling back to the dashboard.

To check the catalog: elestio templates search <software-name> # everything elestio cicd templates <software-name> # deployable as a pipeline elestio clusters templates # supports clustering

Using the Elestio MCP connector

When the Elestio MCP tools are available (claude.ai connector, Claude Code MCP server...), use them instead of the CLI. They cover the same operations, and every rule in this skill applies to them. Destructive tools require "confirm": true: ask the user first, exactly as you would before --force.

| Task | CLI | MCP tool | |---|---|---| | Find software | elestio templates search <name> | search_templates | | Deploy a managed service | elestio deploy <template> | deploy_template | | Deploy a cluster | elestio deploy <template> --cluster --nodes N | deploy_template with cluster_nodes (and cluster_mode) | | What can cluster | elestio clusters templates | list_cluster_templates | | Wait for a deployment | elestio wait <vmID> | wait_for_deployment (for a cluster, pass the comma-separated providerServerID as-is) | | CI/CD target | elestio deploy CI-CD-Target | deploy_cicd_target | | Catalog software in a pipeline | elestio cicd deploy-template <software> --target <vmID> | deploy_catalog_pipeline (supports dry_run) | | Your own repo in a pipeline | elestio cicd create --auto ... | create_pipeline_auto | | Your own compose in a pipeline | elestio cicd create <pipeline.json> | create_pipeline_docker | | Pipelines on a target | elestio cicd pipelines <vmID> | list_pipelines | | Clusters in a project | elestio clusters | list_clusters | | Cluster and its nodes | elestio clusters info <clusterID> | get_cluster | | Promote a replica | elestio clusters promote <clusterID> <vmID> --force | promote_cluster_node | | Automatic failover on/off | elestio clusters failover <clusterID> on\|off | set_cluster_auto_failover | | Rebuild replicas | elestio clusters resync <clusterID> --force | resync_cluster | | Lock / unlock a cluster | elestio clusters lock\|unlock <clusterID> | lock_cluster / unlock_cluster | | Add a node | elestio clusters add-node <clusterID> [--dry-run] | add_cluster_node (supports dry_run) | | Remove a node | elestio clusters remove-node <clusterID> <vmID> --force | remove_cluster_node | | Cluster firewall | elestio clusters firewall\|firewall-restrict\|firewall-open <clusterID> | get_cluster_firewall / set_cluster_port_access | | Delete a cluster | elestio clusters delete <clusterID> --force | delete_cluster | | Build history of a pipeline | elestio cicd pipeline-history <vmID> <pipelineID> | get_pipeline_history | | Delete a pipeline | elestio cicd pipeline-delete <vmID> <pipelineID> --force | delete_pipeline | | Live logs of a service | elestio logs <vmID> | get_service_logs | | Audit trail of a service | elestio audits <vmID> | get_service_audits |

The MCP has no dry run for deploy_template: before a cluster, state the VM count and monthly cost yourself (list_providers_and_sizes gives the price per VM) and get the user's go-ahead.

Setup (One-Time -- Human Action Required)

Prerequisites

Create Account: https://dash.elest.io/signup
Verify Email: Check inbox, click verification link
Add Credit Card: https://dash.elest.io/account/payment
Wait for Approval: Usually instant, sometimes 24-48h
Create API Token: https://dash.elest.io/account/security -> Manage API Tokens -> Create Token
Configure skill: Give email + API token to agent

Configure Credentials

elestio login --email "user@domain.com" --token "xxx_..."
elestio auth test

Verify Setup

# Should show: [SUCCESS] Authenticated as user@domain.com
elestio auth test

# List projects (should show at least one)
elestio projects

Quick Start Examples

Deploy PostgreSQL (2 commands)

# 1. Find template ID
elestio templates search postgresql
# -> ID: 11, PostgreSQL

# 2. Deploy (uses defaults: netcup/nbg/MEDIUM-2C-4G)
elestio deploy postgresql --project 112 --name my-db
# -> Waits for deployment, shows credentials when ready

Deploy Redis Cache

elestio deploy redis --project 112

Deploy WordPress

elestio deploy wordpress --project 112

Deploy a Cluster (replication / HA)

# 1. Check the software supports clustering and see its minimum node count
elestio clusters templates

# 2. ALWAYS dry-run first: billing is per VM, --nodes 3 bills 3 VMs
elestio deploy postgresql --cluster --nodes 3 --project 112 --dry-run

# 3. Deploy
elestio deploy postgresql --cluster --nodes 3 --project 112

# 4. Follow it
elestio clusters list --project 112
elestio clusters info <clusterID>

Rules:

--nodes is the TOTAL, primary included. --nodes 3 = 1 primary + 2 replicas.
ClickHouse, Vault, OpenSearch, RabbitMQ, rke2 and Nats need at least 3 nodes.
Everything else starts at 2. Maximum is 15.
--cluster-mode multi-master works for MySQL only; all others are primary-replica (the default).

Deploy Catalog Software as a Pipeline (Vaultwarden, Redis, Metabase...)

This is the route to use whenever the user wants catalog software on a CI/CD target rather than a dedicated VM.

# 1. Create a CI/CD target if none exists (this is a VM; pipelines share it)
elestio deploy CI-CD-Target --project 112 --name my-target
# -> note the vmID

# 2. Confirm the software is available as a pipeline template
elestio cicd templates vaultwarden

# 3. ALWAYS dry-run first: it prints the ports, env vars and lifecycle hooks
#    that will be applied, and creates nothing
elestio cicd deploy-template vaultwarden --target <vmID> --dry-run

# 4. Deploy (default route: Elestio clones the template repo on the VM)
elestio cicd deploy-template vaultwarden --target <vmID>

On success the CLI prints the software's URL, login and generated password.

Three routes. Use the default.

| | repo (default) | inline (--inline-compose) | git (--owner <git-user>) | |---|---|---|---| | What the pipeline runs | The elestio-examples repo, cloned on the VM by Elestio | Only the inlined docker-compose.yml | A copy of the repo in the user's Git account | | Needs a Git account | No | No | Yes | | Install scripts (pre/postInstall) | Run | Skipped | Run | | Files the compose mounts or reads (env_file) | Present | Missing | Present | | Works for | The whole catalogue | Templates needing no repo file | Every template |

The default route sends imageData.dockerExample (the template repo URL), branch and repoName. The backend stores them as the pipeline's gitConfig.repoURL and the deployment agent clones that repo with Elestio's own Git token. This is exactly what the dashboard does.

--inline-compose is for a compose file of your own. On that route the CLI refuses templates whose compose mounts or reads a repo file, naming them: the file may ship in the repo (n8n's ./n8n-task-runners.json), be generated by an install script (Kafka's ./jaas/*.conf), or be an env_file. Do not pass --force to get past it; use the default route instead.

The git route is unavailable: it needs POST /api/cicd/createRepoByTemplate, which the Elestio API returns 404 for (the controller exists but is not registered in the backend route whitelist). It is also unnecessary now that the default route exists.

ALWAYS verify a deployment instead of assuming it worked:

elestio cicd pipelines <vmID>                          # Build column must say "success"
elestio cicd pipeline-history <vmID> <pipelineID>      # Status, duration, log file

Deploy Custom App from GitHub (user's own code)

# 1. Deploy CI/CD target
elestio deploy CI-CD-Target --project 112 --name my-cicd

# 2. Auto-create pipeline
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <authID>
# -> Site is live at https://<name>-u<userID>.vm.elestio.app/

Use this ONLY for the user's own repository. For catalog software, use cicd deploy-template instead -- see above.

Deploy Custom App (Manual -- Docker mode)

# 1. Deploy CI/CD target
elestio deploy CI-CD-Target --project 112 --name my-cicd

# 2. Add SSH key for agent access
elestio ssh-keys add <vmID> --name "agent-key" --key "ssh-ed25519 AAAA..."

# 3. Generate pipeline config
elestio cicd template docker > pipeline.json
# Edit pipeline.json with correct CI/CD target info (see JSON reference below)

# 4. Create pipeline
elestio cicd create pipeline.json

# 5. SSH and configure
ssh root@<ipv4>
cd /opt/app/<pipeline-name>
# Edit docker-compose.yml, add code, docker-compose up -d

Pipeline JSON Reference (Docker mode -- `createCiCdExistServer` payload)

Do not write this by hand. Generate it with elestio cicd template docker and replace the REPLACE values. The endpoint takes the dashboard's whole form state, and every divergence has produced a 500 or a pipeline that never builds. Current shape (CLI 1.1.0, verified live):

{
  "cluster": {
    "isCluster": false,
    "createNew": false,
    "target": {
      "displayName": "REPLACE",
      "id": "REPLACE",
      "serverName": "REPLACE",
      "vmID": "REPLACE",
      "vmProvider": "REPLACE",
      "vmRegion": "REPLACE",
      "levelName": "Elestio-services",
      "projectID": "REPLACE"
    }
  },
  "gitData": {},
  "imageData": {
    "isPrivate": false,
    "compose": "services:\n  nginx:\n    image: nginx:alpine\n    ports:\n      - \"172.17.0.1:3000:80\"\n    volumes:\n      - ./html:/usr/share/nginx/html:ro",
    "dockerExample": "",
    "repoName": "CustomDocker"
  },
  "configData": {
    "buildDir": "/",
    "rootDir": "/",
    "runTime": "NodeJs",
    "buildCmd": "",
    "runCmd": "",
    "installCmd": "",
    "framework": "NoFramework",
    "version": "20"
  },
  "ports": [
    {
      "protocol": "HTTPS",
      "targetProtocol": "HTTP",
      "listeningPort": "443",
      "targetPort": 3001,
      "public": true,
      "targetIP": "172.17.0.1",
      "path": "/",
      "isAuth": false,
      "login": "",
      "password": "",
      "loginTitle": ""
    }
  ],
  "variables": "",
  "isPublicGitRepo": false,
  "exposedPorts": [
    {
      "protocol": "HTTP",
      "hostPort": "3000",
      "containerPort": "3000",
      "interface": "172.17.0.1"
    }
  ],
  "gitVolumeConfig": [
    {}
  ],
  "isNeedToCreateRepo": false,
  "gitUserFormData": {
    "selectedUser": "",
    "searchGitUser": "",
    "gitOrgsFilteredList": {
      "GITHUB": [],
      "GITLAB": []
    },
    "gitOrgsList": [],
    "selectedRepo": {},
    "thirdPartyRepoInput": "",
    "gitScopesUsers": [],
    "thirdPartyRepoScopeName": "",
    "getGitScopeUser": {
      "GITHUB": [],
      "GITLAB": []
    },
    "thirdPartyRepoName": "",
    "thirdPartyRepoPrivate": false,
    "loadSearch": false
  },
  "lifeCycleCommand": {
    "preInstallCommand": "",
    "postInstallCommand": "",
    "preBackupCommand": "",
    "postBackupCommand": "",
    "preRestoreCommand": "",
    "postRestoreCommand": "",
    "preUpdateCommand": "",
    "postUpdateCommand": "",
    "preDeployCommand": "",
    "postDeployCommand": ""
  },
  "monoRepoWorkSpaces": [
    ""
  ],
  "copyCommandConfig": [],
  "CICDMode": "DockerCompose",
  "projectID": "REPLACE",
  "pipelineName": "REPLACE",
  "isMovePipeline": false,
  "authID": null
}

cluster.target values come from elestio cicd targets: id is the target's serverID (the backend reads it), vmID its vmID.

Common payload mistakes to avoid:

| Field | WRONG | CORRECT | |-------|-------|---------| | CICDMode | "DOCKER" | "DockerCompose" | | configData.runTime | runtime (lowercase t) | runTime (capital T) | | configData.framework | "" | "NoFramework" | | imageData | { imageName, imageTag, registryUrl } | { isPrivate, compose, dockerExample, repoName } | | gitData (docker mode) | { projectName, branch, ... } | {} (empty object) | | authID (docker mode) | "0" | null | | isPublicGitRepo | "false" (string) | false (boolean) | | gitVolumeConfig | [] | [{}] | | ports[] | { targetPort, publishedPort, isDefault } | { protocol, targetProtocol, listeningPort, targetPort, targetIP, public, path, isAuth, login, password, loginTitle } | | exposedPorts | omitted | [{ protocol, hostPort, containerPort, interface }] | | cluster.target | only vmID | id (serverID), vmID, vmProvider, vmRegion, levelName, projectID, displayName, serverName | | nonRepoWorkSpaces | present | remove -- use monoRepoWorkSpaces instead | | variables | omitted or [] (array) | "" or "KEY=value\nKEY2=value2" (string; backend runs variables.trim()) | | lifeCycleCommand (compose, no repo) | hook paths such as ./scripts/preInstall.sh | all "": the agent chmods the paths before docker compose and fails the build |

Command Reference

Authentication & Configuration

elestio login --email X --token Y  # Set credentials
elestio auth test                  # Verify authentication
elestio whoami                     # Show current user
elestio config                     # Show current config
elestio config --set-default-project X  # Set default project

Catalog (No Auth Required)

elestio templates                  # List all 400+ templates
elestio templates search <query>   # Search by name
elestio templates info <name>      # Template details
elestio categories                 # List categories
elestio sizes                      # All provider/region/size combos
elestio sizes --provider netcup    # Filter by provider

Projects

elestio projects                   # List all projects
elestio projects create <name>     # Create project
elestio projects delete <id> --force  # Delete project
elestio projects members <id>      # List members
elestio projects add-member <id> <email>
elestio projects remove-member <id> <memberId>

Services

elestio services                   # List all services
elestio services --project 123     # Filter by project
elestio service <vmID>             # Service details
elestio deploy <template> --project X --name Y
elestio deploy <template> --cluster --nodes 3   # Cluster (see Clusters below)
elestio deploy CI-CD-Target --project X         # Deploy a CI/CD target VM
elestio delete-service <vmID> --force
elestio move-service <vmID> <targetProjectId>
elestio wait <vmID>                # Wait for deployment

Power Management

elestio reboot <vmID>              # Graceful reboot
elestio reset <vmID>               # Hard reset
elestio shutdown <vmID>            # Graceful shutdown
elestio poweroff <vmID>            # Force power off
elestio poweron <vmID>             # Power on
elestio restart-stack <vmID>       # Restart Docker only (fastest)
elestio lock <vmID>                # Enable termination protection
elestio unlock <vmID>              # Disable termination protection
elestio resize <vmID> --size LARGE-4C-8G  # Upgrade/downgrade VM size

Firewall

elestio firewall get <vmID>        # List rules
elestio firewall enable <vmID> --rules '[{"type":"INPUT","port":"22","protocol":"tcp","targets":["0.0.0.0/0"]}]'
elestio firewall update <vmID> --rules '[...]'
elestio firewall disable <vmID>

SSL / Custom Domains

elestio ssl list <vmID>            # List domains
elestio ssl add <vmID> <domain>    # Add with auto-SSL
elestio ssl remove <vmID> <domain>

SSH Keys

elestio ssh-keys list <vmID>       # List keys
elestio ssh-keys add <vmID> --name "name" --key "ssh-ed25519 AAAA..."
elestio ssh-keys remove <vmID> --name "name"

Note: When adding SSH keys, provide only the key type and key data (e.g., ssh-ed25519 AAAA...). Do NOT include the comment/email at the end of the key.

Auto-Updates

elestio updates system-enable <vmID> --day 0 --hour 5 --security-only
elestio updates system-disable <vmID>
elestio updates system-now <vmID>  # Run OS update now
elestio updates app-enable <vmID> --day 0 --hour 3
elestio updates app-disable <vmID>
elestio updates app-now <vmID>     # Run app update now
elestio change-version <vmID> <version>  # e.g., PostgreSQL 15

Alerts

elestio alerts get <vmID>          # Get current rules
elestio alerts enable <vmID> --rules '{...}' --cycle 60
elestio alerts disable <vmID>

Backups

# Local backups (application-level)
elestio backups local-list <vmID>
elestio backups local-take <vmID>
elestio backups local-restore <vmID> /opt/app-backups/backup.zst
elestio backups local-delete <vmID> /opt/app-backups/backup.zst

# Remote backups (Elestio managed)
elestio backups remote-list <vmID>
elestio backups remote-take <vmID>
elestio backups remote-restore <vmID> <snapshot-name>
elestio backups auto-enable <vmID>
elestio backups auto-disable <vmID>

# S3 external backups
elestio s3-backup verify <vmID> --key X --secret Y --bucket Z --endpoint S
elestio s3-backup enable <vmID> --key X --secret Y --bucket Z --endpoint S
elestio s3-backup disable <vmID>
elestio s3-backup take <vmID>
elestio s3-backup list <vmID>
elestio s3-backup restore <vmID> <backup-key>
elestio s3-backup delete <vmID> <backup-key>

Snapshots (Provider-level)

elestio snapshots list <vmID>      # List all snapshots
elestio snapshots take <vmID>      # Create manual snapshot
elestio snapshots restore <vmID> <id>  # Restore snapshot (0 = most recent)
elestio snapshots delete <vmID> <id>   # Delete snapshot
elestio snapshots auto-enable <vmID>   # Enable automatic snapshots
elestio snapshots auto-disable <vmID>  # Disable automatic snapshots

Access & Credentials

elestio credentials <vmID>         # App URL + login
elestio ssh <vmID>                 # SSH terminal URL
elestio ssh <vmID> --direct        # Direct SSH command
elestio vscode <vmID>              # VSCode web URL
elestio files <vmID>               # File explorer URL
elestio logs <vmID>                # Live app logs (temporary URL); --mode install for the install log
elestio audits <vmID> [--days 7]   # Who did what on the service

Volumes

Note: Volume support depends on the cloud provider. Hetzner supports full volume operations. Some providers like netcup have limited or no volume support.

elestio volumes                    # List all volumes in project
elestio volumes create --name X --size 10
elestio volumes service-list <vmID>    # List attached to service
elestio volumes service-create <vmID> --name X --size 10
elestio volumes resize <vmID> <volumeID> --size 20
elestio volumes detach <vmID> <volumeID>
elestio volumes delete <vmID> <volumeID>
elestio volumes protect <vmID> <volumeID>

Clusters

elestio clusters templates                  # Software that supports clustering
elestio clusters                            # List clusters in the project
elestio clusters info <clusterID>           # Details + nodes
elestio clusters nodes <clusterID>          # Active nodes only

# Creation goes through deploy, not through clusters
elestio deploy <template> --cluster --nodes <n> [--cluster-mode multi-master]

# Operations -- all destructive ones require --force
elestio clusters promote <clusterID> <vmID> --force   # Promote a replica
elestio clusters failover <clusterID> on|off          # AUTOMATIC failover switch, does not switch now
elestio clusters resync <clusterID> --force           # ERASES replica data
elestio clusters lock <clusterID>                     # Termination protection
elestio clusters unlock <clusterID>
elestio clusters delete <clusterID> --force           # Deletes ALL nodes (not delete-service)

# Nodes -- dry-run add-node first: billed as one more VM
elestio clusters add-node <clusterID> --dry-run       # Copies the primary: provider, region, size, version
elestio clusters add-node <clusterID> [--size X] [--region Y]
elestio clusters remove-node <clusterID> <vmID> --force   # Replicas only

# Firewall -- applies to every node; the cluster's own nodes stay allowed
elestio clusters firewall <clusterID>
elestio clusters firewall-restrict <clusterID> --port 25432 --ips 203.0.113.7,198.51.100.0/24
elestio clusters firewall-open <clusterID> --port 25432

Constraints (the CLI enforces these before calling the API):

| Rule | Value | |---|---| | --nodes counts | Total nodes, primary included | | Minimum, most software | 2 | | Minimum: ClickHouse, Vault, OpenSearch, RabbitMQ, rke2, Nats | 3 (quorum) | | Maximum | 15 | | --cluster-mode multi-master | MySQL only | | Billing | Per VM. --nodes 5 bills 5 VMs. | | Switching primary by hand | promote, NOT failover (which only toggles automatic failover) | | Replicas | Read-only, and no SSL: sslmode=require fails on a replica | | add-node prerequisites | Remote backups on the primary (elestio backups auto-enable <vmID>), primary-replica mode | | After add-node | The VM deploys, then Elestio spends a few minutes making it a replica. The cluster reads running meanwhile; wait before other node or firewall changes (the CLI refuses them) | | Removing the primary | Not possible: promote a replica first, or delete the cluster | | Restricting access | clusters firewall-restrict, never elestio firewall on one node: it would drift from the others |

NEVER deploy a cluster without running --dry-run first and telling the user the VM count and cost.

CI/CD Pipelines

# CATALOG SOFTWARE -> always use deploy-template (reads the template elestio.yml)
elestio cicd templates [query]     # Catalog software deployable as a pipeline
elestio cicd deploy-template <software> --target <vmID>
elestio cicd deploy-template <software> --target <vmID> --dry-run
elestio cicd deploy-template <software> --target <vmID> --inline-compose   # your own compose only
elestio cicd deploy-template <software> --target <vmID> --owner <git-user>  # git route (currently 404)
# Options: --name, --branch, --private, --non-org, --auth-id, --git-type,
#          --repo-name, --build-cmd, --run-cmd, --install-cmd, --build-dir

elestio cicd targets               # List CI/CD targets
elestio cicd pipelines <vmID>      # List pipelines
elestio cicd pipeline-info <vmID> <pipelineID>

# USER'S OWN REPO -> create --auto. Never use this for catalog software.
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <id>
# Modes: github, github-fullstack, gitlab, gitlab-fullstack, docker
# Optional: --branch, --build-cmd, --run-cmd, --install-cmd, --build-dir, --framework, --node-version

# Manual pipeline creation (from JSON template)
elestio cicd template docker       # Docker Compose (custom, no Git)
elestio cicd template github       # GitHub Static SPA (Vite/React)
elestio cicd template github-fullstack  # GitHub Full Stack (Node.js)
elestio cicd template gitlab       # GitLab Static SPA (Vite/React)
elestio cicd template gitlab-fullstack  # GitLab Full Stack (Node.js)
elestio cicd create <config.json>

# Pipeline actions
elestio cicd pipeline-restart <vmID> <pipelineID>
elestio cicd pipeline-stop <vmID> <pipelineID>
elestio cicd pipeline-logs <vmID> <pipelineID>          # Running app logs
elestio cicd pipeline-log <vmID> --pipeline <id>       # Latest build log (URL)
elestio cicd pipeline-log <vmID> --pipeline <id> --file <logID>   # One build, logID from pipeline-history
elestio cicd pipeline-history <vmID> <pipelineID>
elestio cicd pipeline-delete <vmID> <pipelineID> --force

# Pipeline domains
elestio cicd domains <vmID> <pipelineID>
elestio cicd domain-add <vmID> --pipeline <id> --domain myapp.example.com
elestio cicd domain-remove <vmID> --pipeline <id> --domain myapp.example.com

# Docker registries
elestio cicd registries
elestio cicd registry-add --name X --username U --password P --url URL

Auto-create pipeline flow: the CLI finds the connected Git account (or uses --auth-id), resolves the repo and the CI/CD target, and creates the pipeline through the API. Elestio then clones, builds and starts it; follow the build with elestio cicd pipelines <vmID> and elestio cicd pipeline-history <vmID> <pipelineID>.

Billing

elestio billing                    # Total costs
elestio billing project <id>       # Per-service breakdown

MANDATORY: Interactive Deployment Procedure

CRITICAL: When deploying ANY service, you MUST ask the user for each required parameter one by one using AskUserQuestion. NEVER deploy with default values without explicit user confirmation.

Required Parameters (ask in this order):

1. Provider -- Ask using AskUserQuestion:

Netcup (Recommended) -- Best price/performance ratio, EU-based, reliable
Hetzner -- Best features: full volume, snapshot & power management support
AWS -- Amazon Web Services, global reach
Azure -- Microsoft cloud

2. Region -- Ask using AskUserQuestion, based on selected provider:

Netcup: nbg (Europe - Germany, Nuremberg) | mns (North America - United States, Manassas)
Hetzner: fsn1 (Falkenstein, DE), nbg1 (Nuremberg, DE), hel1 (Helsinki, FI), ash (Ashburn, US)
AWS: us-east-1, eu-west-1, ap-southeast-1, etc.
Azure: germanywestcentral, eastus, westeurope, etc.

Use elestio sizes --provider <provider> to get exact available regions if needed.

3. Service Plan (Size) -- Ask using AskUserQuestion, propose available sizes with pricing:

SMALL-1C-1G -- 1 core, 1GB RAM (~$11/mo, Linode)
MEDIUM-2C-4G -- 2 cores, 4GB RAM (~$16/mo, Netcup DE)
LARGE-4C-8G -- 4 cores, 8GB RAM (~$30/mo, Netcup DE)
XL-8C-16G -- 8 cores, 16GB RAM (~$55/mo, Netcup DE)

Use elestio sizes --provider <provider> to get exact sizes/pricing for the chosen provider.

4. Name of Service -- Do NOT use AskUserQuestion. Simply ask the user in plain text to provide a name, suggesting a default based on the service type (e.g., "prod-postgres", "staging-redis"). Wait for user text input.

5. Admin Email -- Ask using AskUserQuestion, propose the employer's email as default. Let the user confirm or change.

Example Flow:

User: "Deploy PostgreSQL"
Agent: [AskUserQuestion] Which cloud provider? (Netcup recommended, Hetzner, AWS, Azure)
User: "Netcup"
Agent: [AskUserQuestion] Which region? (nbg Europe-Germany, mns North America-US)
User: "nbg"
Agent: [AskUserQuestion] Which service plan? (SMALL ~$11/mo, MEDIUM ~$16/mo, LARGE ~$30/mo, XL ~$55/mo)
User: "MEDIUM"
Agent: "What name do you want for this service? Suggestion: prod-postgresql"
User: "demo-postgres"
Agent: [AskUserQuestion] Admin email? (Suggested: user@company.com)
User: confirms
Agent: Deploys with all confirmed parameters

Golden Rules

Always authenticate first -- Every session starts with valid JWT
vmID != serverID -- Most endpoints use vmID, backup/notes use serverID (both from elestio services)
Check deployment status -- After deploy, wait for deploymentStatus = "Deployed" before accessing
Never delete without confirmation -- Always require --force flag
Use catalog when possible -- Phase 3 (catalog) is simpler than Phase 4 (CI/CD) 5b. Catalog software in a pipeline -> cicd deploy-template (MCP: deploy_catalog_pipeline), NEVER cicd create (MCP: create_pipeline_docker / create_pipeline_auto) -- those cannot know the software's ports, env vars or install scripts, so they produce a pipeline that deploys and runs nothing
Validate combos -- Provider + datacenter + serverType must match elestio sizes
Account must be approved -- New accounts need credit card + approval before deploying
ALWAYS follow the Interactive Deployment Procedure above -- Never skip parameter questions
Set default project -- Use elestio config --set-default-project <id> to avoid passing --project every time
Service belongs to project -- When using elestio service <vmID>, ensure the vmID belongs to the current default project or specify --project
Dry-run anything that multiplies VMs -- Always run --dry-run before a cluster deploy and tell the user the VM count and monthly cost; clusters bill per VM
--nodes is the total -- --nodes 3 is 1 primary + 2 replicas and bills 3 VMs, not 4

Defaults

| Setting | Default | Override | |---------|---------|----------| | Provider | netcup | --provider hetzner | | Datacenter | nbg (Germany) | --region fsn1 | | Server Size | MEDIUM-2C-4G | --size LARGE-4C-8G | | Support | level1 | --support level2 |

Why netcup? Best price/performance ratio. EU-based. Reliable.

Provider Limitations

Not all cloud providers support all features. Use --provider to switch.

| Feature | netcup | Hetzner | AWS | GCP | Azure | Scaleway | |---------|--------|---------|-----|-----|-------|----------| | Catalog deploy | yes | yes | yes | yes | yes | yes | | CI/CD deploy | yes | yes | yes | yes | yes | yes | | Volumes | no | yes | yes | yes | yes | yes | | Snapshots | limited | yes | yes | yes | yes | yes | | Power actions | limited | yes | yes | yes | yes | yes | | Firewall | yes | yes | yes | yes | yes | yes | | SSL/Domains | yes | yes | yes | yes | yes | yes | | Size downgrade | yes | no | yes | no | yes | yes |

Size downgrade support: Only Netcup, AWS, Azure, and Scaleway support downgrading instance sizes. Other providers (Hetzner, GCP, etc.) only support upgrades. Attempting a downgrade on an unsupported provider can block the service and require Elestio support intervention. The CLI will automatically block downgrade attempts on unsupported providers.

Recommendation: Use Hetzner if you need volumes, snapshots, or full power management. Use netcup for best value when basic features suffice. Use netcup, AWS, Azure, or Scaleway if you need the flexibility to downgrade instance sizes.

Rate Limiting (read before any loop)

The API throttles bursts, then answers Access temporarily restricted on every endpoint for several minutes -- authentication included, so it looks like a credentials problem and is not.

Never fan out. Looping over services, projects or the 420-template catalogue must be sequential, with roughly a second between calls. A parallel sweep got an account restricted for more than half an hour.
Stop on it, do not retry in a loop: retrying adds requests to an account that is already being throttled.
Never treat it as an empty result. A script that reads it as "this template has no config" reports success while having learned nothing.
Tell the user to wait a few minutes, then resume where you stopped.

The CLI (>= 1.2.3) and the MCP connector both report this explicitly.

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | "Not configured" | Missing credentials | elestio login --email X --token Y | | "Authentication failed" | Wrong credentials or expired token | Re-create API token in dashboard | | "Account not approved" | New account without approval | Wait for approval or contact support@elest.io | | "Template not found" | Wrong name/ID | Use elestio templates search <name> | | "Invalid serverType" | Provider/region/size combo doesn't exist | Check elestio sizes --provider X | | "Service not found" | Wrong vmID or project | Check elestio services --project X | | "Deployment timeout" | Taking too long | Check dashboard, contact support if > 10 min | | "Project not found" | Wrong projectId | Check elestio projects |

Composability: What to Do After...

After Deploying a Service

Get credentials: elestio credentials <vmID>
Verify running: Open the URL, confirm service works
Enable backups: elestio backups auto-enable <vmID>
Add custom domain: elestio ssl add <vmID> myapp.example.com
Configure firewall: elestio firewall enable <vmID> --rules [...]
Enable auto-updates: elestio updates system-enable <vmID> --security-only

After Creating CI/CD Target

Catalog software (Vaultwarden, Redis, Metabase...) -- use this:

Check it is available: elestio cicd templates <software>
Preview: elestio cicd deploy-template <software> --target <vmID> --no-git --dry-run
Deploy: elestio cicd deploy-template <software> --target <vmID>
Report the printed URL, login and password to the user
Add a domain: elestio cicd domain-add <vmID> --pipeline <pipelineID> --domain myapp.example.com

User's own repo:

Auto-create pipeline: elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <id>
Follow the build: elestio cicd pipelines <vmID> (Build column must say "success")

Manual docker-compose:

Add SSH key: elestio ssh-keys add <vmID> --name "name" --key "key"
Create pipeline: elestio cicd create pipeline.json
SSH and configure: ssh root@<ipv4>
Add domain: elestio cicd domain-add <vmID> --pipeline <pipelineID> --domain myapp.example.com

After an Error

Re-authenticate: elestio auth test
Check status: elestio service <vmID>
View logs: elestio logs <vmID> (service) or elestio cicd pipeline-logs <vmID> <pipelineID> (pipeline) 3b. See what changed: elestio audits <vmID>
Restart stack: elestio restart-stack <vmID>

Troubleshooting

"Authentication failed" repeatedly

# 1. Verify current config
elestio config

# 2. Re-configure with fresh token from dashboard
elestio login --email "..." --token "..."

# 3. Test
elestio auth test

Service stuck in "Deploying"

Normal deployment takes 2-5 minutes
If > 10 minutes, check Elestio dashboard for errors
Contact support@elest.io if still stuck

"Service not found" but it exists

Make sure you're using vmID, not serverID
Check the correct project: elestio services --project X
vmID looks like: 12345678 (numeric)

Pipeline deployed but the software is not running (MOST COMMON)

Almost always: the pipeline was created with cicd create instead of cicd deploy-template, so it has no ports, no environment variables and no install scripts.

# Confirm: a pipeline built correctly has env vars
elestio cicd pipeline-info <vmID> <pipelineID>

# Fix: delete it and redeploy through deploy-template
elestio cicd pipeline-delete <vmID> <pipelineID> --force
elestio cicd deploy-template <software> --target <vmID>

With the MCP connector the cause is the same: the pipeline was made with create_pipeline_docker or create_pipeline_auto. Redeploy it with deploy_catalog_pipeline.

Software starts then exits immediately

With CLI 1.3.0 the default route clones the template repo on the VM, so the install scripts run and the files the compose mounts are present. If the software still fails:

elestio cicd pipeline-history <vmID> <pipelineID>     # did the build fail?
elestio cicd pipeline-log <vmID> --pipeline <id>      # the build log

Two causes worth checking first:

the pipeline was created with cicd create (empty pipeline) instead of cicd deploy-template;
the pipeline was created with --inline-compose, which skips the install scripts and the repo's files. Delete it and redeploy on the default route.

"No elestio.yml found at ..."

That software has no pipeline template and cannot be deployed as a pipeline. Deploy it as a managed service instead: elestio deploy <template>.

Pipeline not working (general)

SSH into CI/CD target: ssh root@<ipv4>
Check logs: cd /opt/app/<pipeline-name> && docker-compose logs
Verify docker-compose.yml syntax
Check port mapping: 172.17.0.1:3000 (internal network)

Cluster errors

| Message | Cause | |---|---| | does not support clustering | Not one of the clusterable templates -- run elestio clusters templates | | needs at least 3 nodes | Quorum software (ClickHouse, Vault, OpenSearch, RabbitMQ, rke2, Nats) | | does not support multi-master | --cluster-mode multi-master works for MySQL only | | cannot exceed 15 nodes | Hard platform cap | | remote backups are off (add-node) | New nodes are seeded from the primary's remote backup: elestio backups auto-enable <primary vmID> | | is busy (add-node) | A node is still being configured; wait a few minutes | | is the primary (remove-node) | Promote a replica first, or delete the whole cluster |

"variables.trim is not a function" (500 Pipeline.CreateFailed)

The variables field in the pipeline payload must be a string, never an array or omitted. The backend runs variables.trim() on it, so any other type throws before your build/run/framework settings are even read (it fails even with minimal parameters).

Correct: "variables": "" (no env vars) or "variables": "KEY=value\nKEY2=value2".
Wrong: "variables": [] or leaving the field out entirely.

The CLI enforces this from 1.1.0 and the MCP connector sends it correctly. If you hit it with the CLI, upgrade: npm install -g elestio@latest.

ID Reference (Critical)

| Term | Find it in | Use in | |------|------------|--------| | vmID | elestio services -> .vmID | Most endpoints (actions, firewall, ssl, etc.) | | serverID | elestio services -> .id | Backup endpoints, notes | | projectID | elestio projects -> .projectID | Almost everything | | templateID | elestio templates -> .id | elestio deploy | | pipelineID | elestio cicd pipelines -> .pipelineID | CI/CD actions | | volumeID | elestio volumes -> .id | Volume actions |

Common mistake: Using serverID where vmID is expected (or vice versa). They are different numbers for the same service.

VM Architecture

Every Elestio service runs on a dedicated VM:

/opt/elestio/nginx/          <- Reverse proxy (auto-configured, don't modify)
/opt/app/                    <- Your application
    +-- docker-compose.yml   <- For catalog services
    +-- <pipeline_name>/     <- For CI/CD pipelines

Reverse proxy handles HTTPS termination automatically
SSL certificates are auto-generated via Let's Encrypt
Port 172.17.0.1:XXXX is the internal Docker network interface

Support Tiers

| Plan | Price | Response Time | |------|-------|---------------| | level1 | Included | 48h (email) | | level2 | +$50/svc/mo | 24h (priority) | | level3 | +$200/svc/mo | 4h (dedicated engineer) |