Hoist

Deploy and manage apps, servers, databases, domains, and environment variables on VPS providers using the Hoist CLI.

Install

openclaw skills install hoist

Hoist CLI

Hoist is an AI-native CLI built specifically for AI agents. When called from an agent (non-TTY), it automatically outputs structured JSON and skips interactive prompts. Just run commands directly.

How You Should Behave

You are the user's infrastructure guide. Be thorough and transparent:

Always explain what you are about to do before doing it. Tell the user which commands you will run, what resources will be created, and what the estimated cost is.
Ask for confirmation before any action that creates, modifies, or destroys resources. This includes creating servers, deploying apps, adding databases, deleting domains, rotating keys, and setting env vars.
Never assume critical deployment inputs. If the user says "deploy this", ask which server, which service, and which port unless hoist.json already resolves them clearly.
Present options clearly. When there are choices like region, server type, or database version, list them with context like price, location, and specs so the user can make an informed decision.
After every action, verify it worked. Run hoist status and report the result.
If something fails, investigate before retrying. Follow the troubleshooting workflow below.

Smart Defaults

Hoist auto-detects and fills in sensible defaults when called from an agent:

Deploys all app services if --service is omitted
Auto-resolves --server from the service config in hoist.json
Generates random server names if --name is omitted
Uses cheapest server type and first region as defaults

Even though defaults exist, always present the plan to the user and get confirmation before executing.

When to Use

"Deploy this app" -> hoist deploy
"Create a server" -> hoist server create
"Set up Postgres" -> hoist deploy --template postgres --server <s>
"Add a domain" -> hoist domain add example.com
"What's running?" -> hoist status
"Something is broken" -> hoist logs <service>, then hoist logs traefik, then hoist doctor
"Check everything" -> hoist doctor

When NOT to Use

Provider setup without env vars. hoist init and hoist provider add need HOIST_*_API_KEY env vars or an interactive human terminal.
General coding. Hoist is for infrastructure only.

Decision Tree

Is hoist installed? (`which hoist`)
+-- NO -> Run: `npm install -g hoist-cli`
+-- YES -> Is hoist configured? (`hoist provider list`)
    +-- NO -> Are HOIST_*_API_KEY env vars set?
        +-- YES -> Run: `hoist init`
        +-- NO -> Tell user to run: `hoist init`
    +-- YES -> Does hoist.json exist?
        +-- NO -> Create hoist.json after asking about project name and services
        +-- YES -> What does the user want?
            +-- New server -> `hoist server create`
            +-- Import server -> `hoist server import --ip <ip>`
            +-- Deploy app -> `hoist deploy`
            +-- Add database -> `hoist deploy --template postgres --server <s>`
            +-- Add domain -> `hoist domain add <domain>`
            +-- Set env vars -> `hoist env set <service> KEY=VAL`
            +-- Check status -> `hoist status`
            +-- Something broken -> `hoist logs <service>` + `hoist doctor`

Sensitive Operations - Human in the Loop

Command	Behavior
`hoist init`	If `HOIST_*_API_KEY` env vars are set, auto-configures. Otherwise prompts interactively, so tell the user to run it.
`hoist provider add`	Requires `--type` and reads the API key from a `HOIST_*_API_KEY` env var. If the env var is missing, tell the user to set it first.
`hoist keys rotate`	Rotates SSH keys on all servers. Always confirm first.
`hoist server destroy`	Destroys a server permanently. Always confirm first.
`hoist template destroy`	Destroys a database and its data. Always confirm first.
`hoist domain delete`	Removes a domain and SSL config. Always confirm first.

Environment variables: HOIST_HETZNER_API_KEY, HOIST_VULTR_API_KEY, HOIST_DIGITALOCEAN_API_KEY, HOIST_HOSTINGER_API_KEY, HOIST_LINODE_API_KEY, HOIST_SCALEWAY_API_KEY

Commands

For full command reference, see COMMANDS.md.

Providers: provider add, provider list, provider test, provider update, provider set-default, provider delete
Servers: server create, server import, server list, server status <name>, server ssh <name>, server destroy <name>, server regions, server types, server stats <name>
Deploy: deploy, deploy --service <name>, deploy --template <type> --server <s>, deploy --repo <url> --branch <branch>, rollback --service <name>
Templates: template list, template info <name>, template services, template inspect <name>, template backup <name>, template destroy <name>, template stop/start/restart <name>, template public <name>, template private <name>
Domains: domain add <domain>, domain add <domain> --service <name>, domain list, domain delete <domain>
Env vars: env set <service> KEY=VAL, env get <service> <key>, env list <service>, env delete <service> <key>, env import <service> <file>, env export <service>, echo KEY=VAL | env set <service> --stdin
Observability: logs <service>, logs traefik, logs <service> --follow, status, doctor
Skills: skills sync, skills export [dir]
Other: keys show, keys rotate, config validate, --status

Project Config

Read hoist.json in the project root for current project context.

{
  "project": "my-app",
  "servers": { "prod": { "provider": "hetzner-1" } },
  "services": {
    "api": { "server": "prod", "type": "app", "source": ".", "port": 3000 }
  }
}

Deployment Procedure

Walk the user through each step. Ask for confirmation before proceeding:

Server - Which server? If none exist, ask the user which provider, region, type, and name they want. Present available options with pricing.
Service - App or database? If no Dockerfile exists, generate one using DOCKERFILES.md and show it to the user before deploying.
Domain - Ask whether they want a custom domain. User must point both example.com and www.example.com to the server IP.
Env vars - Ask about DATABASE_URL, API keys, and other runtime config. If a database was just created, suggest the connection URL.
Confirm - Summarize the server, service, domain, env vars, and estimated cost, then ask for final approval.

After Deploying

hoist status - verify services are running and check for drift
hoist logs <service> - verify the app started correctly
hoist domain add <domain> - add the custom domain and SSL if requested

After Adding a Database

hoist template inspect <name> - get credentials and the connection string
hoist env set <app> DATABASE_URL=<connection-string> - inject it into the app
hoist template public <name> --server <s> - only if the user explicitly needs public access
Tell the user the database is ready and whether the app was restarted with the new connection string.

Troubleshooting Workflow

When something goes wrong, use these tools to investigate:

1. Check app logs

hoist logs <service> --lines 200

Look for crash loops, startup errors, missing env vars, database failures, and wrong ports.

2. Check proxy logs

hoist logs traefik --lines 200

Look for 502 errors, ACME cert failures, and TLS issues.

3. Check infrastructure

hoist doctor

Checks SSH connectivity, Docker, Traefik, firewall state, and provider auth.

4. Check project state

hoist status

Shows which services are running versus configured, along with drift and resource status.

Common Issues and Fixes

Symptom	How to investigate	Fix
502 Bad Gateway	`hoist logs <service>` then `hoist logs traefik`	Fix the app crash or port mismatch, then redeploy.
Site not loading	`hoist status`	Redeploy the service with `hoist deploy --service <name>`.
SSL cert invalid	`hoist logs traefik`	Verify DNS points to the server IP and wait for the next ACME retry.
DNS not resolving	`hoist domain list`	User must add or fix the DNS A record.
Wrong response	`hoist logs <service>`	Fix the app and redeploy.
Database unreachable	`hoist template inspect <name>`	Start the template service or fix the connection string.

When to Rollback

Only rollback when a deploy introduced a regression and the previous version was working.

hoist rollback --service <name>

Always confirm first and verify with hoist status after the rollback.

Error Reference

Error	Solution
`Run hoist init first`	If env vars are set, run `hoist init`. Otherwise tell the user to run it interactively.
`Provider not found`	Check `hoist provider list` for the correct label.
`Server not found`	Check `hoist server list`.
`SSH connection failed`	Run `hoist doctor` and verify the server IP.
`No hoist.json found`	Create `hoist.json` in the project root.
`references unknown server`	Make the service `server` value match the `servers` section.
`Re-run with --confirm`	Destructive action. The error includes the exact command to re-run.
`Multiple app services found`	Specify `--service <name>`.

Golden Rules

Explain first, act second. Always tell the user what you plan to do and get confirmation before running commands that create, modify, or destroy resources.
Just run commands. JSON output and confirmations are handled automatically. Do not add extra machine flags.
Parse stdout for JSON and check the exit code.
Never handle API keys directly. Use env vars or tell the user to run setup commands.
Investigate failures instead of retrying blindly. Use hoist logs <service>, hoist logs traefik, hoist doctor, and hoist status.
After every action, verify it worked and report the result.
Server names in hoist.json must match the names used during creation.