MCP server Hostim

hostim CLI

Command-line interface for the Hostim.dev cloud platform. Create and manage projects, apps, databases (MySQL / Postgres / Redis), volumes and domains from a terminal or a CI pipeline, over the public REST API at https://api.hostim.dev.

An app can deploy from a local directory (uploaded and built from its Dockerfile, or served as a static site), a git repository, or a Docker image. A local directory needs no git remote and no registry: hostim deploy web --source . --plan sa-1-1 --port 8080. See deploy.

This file is the complete manual. The binary carries the same text: run hostim agent to print it to stdout, so an agent or a script can read the whole manual without network access.

Commands, flags, output and API responses can change between releases. Check the release notes before you upgrade.

Contents

• Install
• Log in
• Configuration
• Global flags
• Output and exit codes
• Command reference
  • login, logout, whoami, use
  • projects
  • deploy
  • apps
  • status, logs, events, overview
  • env
  • domain
  • exec
  • db
  • volumes
  • backups
  • templates
  • regions
  • completion
  • agent
  • mcp
  • version
• Template files
• Deploy from CI
• Reporting problems
• Development
• License

Install

curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | sh

The script downloads the release binary for the current OS and architecture (Linux and macOS, amd64 and arm64) and installs it into /usr/local/bin, using sudo when that directory is not writable. When it is not writable and sudo is not installed either — a plain container, for example — the script falls back to ~/.local/bin and tells you if that directory is not on your PATH. Set PREFIX to choose the location yourself:

curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | PREFIX=$HOME/.local sh

Some agents and CI policies refuse to pipe a downloaded script into a shell. The script is not required. Use Homebrew (macOS and Linux):

brew install hostimdev/tap/hostim

Or npm (Node 18+). npx downloads the release binary for your platform on the first run, checks it against the release checksums and caches it:

npx -y hostim version
npm install -g hostim   # or install it once and run `hostim`

Or fetch the release binary directly:

VERSION=$(curl -fsSL https://api.github.com/repos/hostimdev/cli/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
curl -fsSL "https://github.com/hostimdev/cli/releases/download/${VERSION}/hostim_linux_amd64.tar.gz" | tar -xz hostim
install -m 0755 hostim /usr/local/bin/hostim   # or anywhere on your PATH

Build from source instead (Go 1.26+):

git clone https://github.com/hostimdev/cli && cd cli
make build           # writes bin/hostim
make install         # installs into /usr/local/bin (PREFIX to change)

Check the install:

hostim version

Log in

hostim login uses a device code. It prints a URL and a short code, you approve the request in the browser, and the token is saved automatically:

hostim login

hostim login polls until you approve and saves the token itself, so there is no need to write a waiting loop around it or to run it a second time. The browser step does not need a terminal, so an agent can run hostim login and show you the code. If you already have a token, store it directly instead — create one in the dashboard at https://console.hostim.dev:

hostim login --token-value "$T"   # non-interactive, for scripts and CI

login validates the token against the API before saving it to ~/.config/hostim/config.yml (mode 0600). In CI, skip login and export HOSTIM_TOKEN instead — no file is written.

Most commands act on one project. Set a default once:

hostim projects ls
hostim use my-project
hostim whoami                     # token source, current project, project count

Configuration

Values are resolved as flag → environment variable → config file, with a built-in default for the API URL.

Value	Flag	Environment variable	Config key
API token	--token	HOSTIM_TOKEN	token
API base URL	--api-url	HOSTIM_API_URL	apiUrl (default https://api.hostim.dev)
Target project	-p, --project	HOSTIM_PROJECT	currentProject, set by hostim use

The config file lives at ~/.config/hostim/config.yml, or $XDG_CONFIG_HOME/hostim/config.yml when XDG_CONFIG_HOME is set:

token: ...                 # written by `hostim login`
currentProject: my-project # written by `hostim use`
apiUrl: https://api.hostim.dev  # only written when --api-url was passed

Projects and apps can be named by name or by ID everywhere.

Global flags

Available on every command:

--token string      API token (overrides HOSTIM_TOKEN and config)
--api-url string    API base URL (default https://api.hostim.dev)
-p, --project       project to target (overrides HOSTIM_PROJECT and current project)
-o, --output        output format: table or json (default "table")
-h, --help          help for the command
-v, --version       version (root command only)

Destructive commands (rm, templates apply) ask for confirmation and take -y / --yes to skip the prompt.

Output and exit codes

Default output is an aligned text table meant for a human. -o json switches every command to machine output and is the right mode for scripts and agents:

• read commands print the API object or list as indented JSON;
• write commands print a single result object naming what happened, for example {"status":"created","kind":"app","name":"web"} or {"status":"ok","kind":"env","set":1};
• failures print a JSON object on stderr, for example {"status":"error","error":"..."}, and exit non-zero. When a command is short of several requirements, the object carries a "missing" array listing all of them at once.

Exit codes:

Code	Meaning
0	success
1	any CLI or API error, or an aborted confirmation
other	hostim exec passes through the remote command's exit status

Command reference

Every example below is runnable as written once a token and a project are set.

login, logout, whoami, use

hostim login                          # device login: approve a code in the browser
hostim login --token-value "$TOKEN"   # store an existing API token instead
hostim logout                         # remove the stored token
hostim whoami                         # API URL, token source, current project
hostim whoami -o json
hostim use my-project                 # set the default project (verifies it exists)
hostim use my-project --force         # skip the check (offline)
hostim use --clear                    # unset the default project

projects

hostim projects ls                            # aliases: project, proj; ls | list
hostim projects get my-project
hostim projects create my-project --region eu-center
hostim projects rm my-project -y
hostim projects export -p prod -f prod.yml    # template YAML for `templates apply`
hostim projects export -p prod -o json        # template as JSON on stdout

--region is required on create; see hostim regions ls for the values.

projects export writes a desired-state template, not a backup: volume and database contents (data) are not exported. That data is backed up on a schedule anyway: Postgres and MySQL databases and volumes, see backups (hostim backups). Costs, IDs, built-in domains and unused source blocks are stripped, and env var values are exported RAW — the file holds secrets (passwords, API keys), so store and share it like a password file. Docker registry passwords and git tokens are not readable through the API and are left out (registry usernames are kept); set them again after applying. Redeploy with hostim templates apply -f prod.yml --new-project prod-clone.

deploy

hostim deploy <app> creates the app when it does not exist (from --source, --git or --docker-image) and otherwise updates its source and triggers a rebuild. It waits for the build and exits non-zero if the build fails, so it drops straight into a pipeline. hostim apps deploy is the same command.

# first deploy from a git repo
hostim deploy web \
  --git https://github.com/me/app --branch main \
  --plan sa-1-1 --port 8080 \
  --health-check-path /healthz \
  --env LOG_LEVEL=debug --env-file .env

# deploy a local directory: it is uploaded and built with its Dockerfile
hostim deploy web --source . --plan sa-1-1 --port 8080

# deploy a built static site (index.html, no Dockerfile): nginx on port 80
npm run build && hostim deploy site --source dist --plan sa-1-1

# redeploy: source is unchanged, just rebuild
hostim deploy web

# deploy a docker image and do not wait
hostim deploy web --docker-image ghcr.io/me/app:latest --wait=false

# private registry: the registry host goes inside the image reference
hostim deploy web --docker-image registry.example.com/me/app:1.2.3 \
  --docker-user ci --docker-pass "$REG_PASS"

# private git repo
hostim deploy web --git https://github.com/me/private --git-token "$GH_TOKEN"

# mount a volume and attach a domain on create
hostim deploy web --docker-image nginx --plan sa-1-1 --port 80 \
  --volume data:/var/lib/app --domain app.example.com

Flags:

--source string              deploy a local directory: it is uploaded and built with its Dockerfile
--static                     serve --source as a static site with nginx (automatic when it has an index.html and no Dockerfile)
--git string                 git repository URL
--branch string              git branch
--dockerfile string          path to the Dockerfile in the repo or source dir; its directory is the build context
--git-token string           token for private git repos
--docker-image string        docker image reference, registry host included
--docker-user string         docker registry username
--docker-pass string         docker registry password
--plan string                app plan (required when creating)
--port int                   HTTP port (on create; required unless --public=false)
--public                     expose the app publicly (on create) (default true)
--replicas int               number of replicas (on create) (default 1)
--domain stringArray         custom domain (repeatable, on create)
--volume stringArray         mount a volume as name:mountPath (repeatable)
--env stringArray            environment variable as KEY=VALUE (repeatable, merges)
--env-file string            read environment variables from a .env file (merges)
--command string             override the container command (empty value restores the image default)
--health-check-path string   HTTP path for the readiness probe (empty value disables it)
--wait                       wait for the build to finish (default true)
--timeout duration           max time to wait for the build (default 15m0s)
--poll-interval duration     status poll interval (default 3s)

With --source . the directory is packed into a .tar.gz and uploaded before the build. These paths are always left out: .git/, node_modules/ (at any depth), .env and .env.* files (except .env.example, .env.sample and .env.template). A .dockerignore at the directory root is applied too; the Dockerfile and .dockerignore are always kept. Symlinked directories are not followed, and a symlink is skipped when its target is outside the directory. The archive is limited to 500 MiB after compression. The same files always give the same archive hash, so an unchanged directory is not uploaded twice. The platform keeps an uploaded archive for 7 days; after that, run the deploy with --source <dir> again to re-upload it.

A directory with an index.html and no Dockerfile is a static site: the CLI adds an nginx Dockerfile and config, so --port is not needed (the app listens on 80). --static forces this mode when the directory has a Dockerfile (Jekyll copies one into _site); the directory's own Dockerfile and .dockerignore are then ignored. In static mode every file in the directory is uploaded, even inside a git work tree whose .gitignore lists the build folder. The nginx config serves /about from about.html or about/index.html, uses the site's 404.html, gzips text, and caches /_astro/, /_next/static/ and /assets/ for a year. On success the deploy prints the app's URL.

Plan IDs are per resource kind and look like sa-1-1 (shared app, 1 core, 1 GB RAM). List the ones a region offers with hostim regions pricing <region> --for apps.

deploy handles one app. An app that also needs a database, a Redis or a volume is deployed as a template — see templates.

apps

hostim apps ls                    # aliases: app; ls | list; `hostim apps` alone does the same
hostim apps get web
hostim apps status                # health table for every app in the project
hostim apps status web
hostim apps rebuild web           # rebuild from the current source
hostim apps restart web           # restart the running containers
hostim apps rm web -y             # aliases: delete, remove

status, logs, events, overview

hostim status                          # every app in the project
hostim status web                      # one app: build + runtime status
hostim status -o json

hostim logs web                        # last 100 lines, oldest first
hostim logs web -f                     # stream new lines
hostim logs web -n 500                 # 1-10000 lines
hostim logs web --since 2h             # every line of the last 2 hours (up to 10000)
hostim logs web --since 2026-10-14T14:00 --until 2026-10-14T14:10   # one time window
hostim logs web --since 1h | grep -i error   # search
hostim logs web --build --since 1h     # build logs (git-built apps only)

# Logs cover stdout and stderr of every container the app ran in the last
# 7 days, so lines from before a redeploy or a crash are still there.

hostim events web                      # status history: why the app changed state
hostim events web -f                   # keep printing new events
hostim events web -n 20

hostim overview                        # every resource in every project + cost
hostim overview my-project             # alias: resources

status shows the current value; events shows how it got there, which is where to look when an app went unhealthy and came back. --build works for apps built from git; an app that runs a prebuilt docker image has no build logs.

env

Environment variables belong either to one app (-a/--app) or to the whole project (--global). Apps see the global set plus their own.

hostim env get -a web
hostim env get --global -o json
hostim env set KEY=VALUE OTHER=2 -a web       # merges with existing vars
hostim env set SENTRY_DSN=... --global
hostim env rm KEY OTHER -a web
hostim env pull -a web --file .env            # write to a file (- for stdout)
hostim env push -a web --file .env            # load from a file, merging
hostim env push -a web --file .env --replace  # replace the whole set

Changing environment variables restarts the app.

To reach another app in the same project, use its internal DNS name app-<name>-service on its HTTP port, for example API_URL=http://app-api-service:8080. hostim status <app> shows it as "Internal DNS". Apps without an HTTP port have none.

Values can reference database variables with $(...), also inside a longer value such as a DSN. They are expanded at container start, so hostim env get shows the literal text. See Placeholders in envVars for every variable name.

hostim env set -a web \
  'DATABASE_URL=mysql://$(MAIN_MYSQL_USER):$(MAIN_MYSQL_PASSWORD)@$(MAIN_MYSQL_HOST):$(MAIN_MYSQL_PORT)/$(MAIN_MYSQL_DATABASE)'

domain

hostim domain add app.example.com -a web    # prints the DNS record to create
hostim domain status web                    # domains + DNS/certificate state
hostim domain rm app.example.com -a web -y

Add the printed record at the DNS provider, then re-run hostim domain status until it reports the domain as active; the certificate is issued automatically.

exec

Runs a command inside an app's container, or opens an interactive shell when no command is given. The connection goes through the project's SSH bastion, so the project has to authorize your public SSH key. The first hostim exec against a project offers to add the key for you; pass -y to add it without the prompt, which is what a script or a CI job needs.

hostim exec web                                   # interactive shell
hostim exec web -- rails c                        # one-off command
hostim exec web -- sh -c 'ls -la /var/www | head'
hostim exec web -- cat /tmp/app.log               # read a file the app does not log
cat dump.sql | hostim exec --stdin db -- psql app # pipe local data in
hostim exec web -i ~/.ssh/id_ed25519 -- env       # pick the SSH key
hostim exec -y web -- ./migrate.sh                 # no prompts, for CI

Aliases: shell, ssh. The exit status of the remote command becomes the exit status of hostim exec.

db

Three engines, the same command shape: hostim db mysql|postgres|redis ls|get|create|credentials|status|rm. pg is an alias for postgres.

hostim db postgres ls
hostim db postgres create main --plan sp-1
hostim db postgres get main
hostim db postgres status main
hostim db postgres credentials main -o json   # hostname, port, username, password, database
hostim db postgres rm main -y

hostim db mysql ls
hostim db mysql create app --plan sm-1
hostim db mysql get app
hostim db mysql status app
hostim db mysql credentials app -o json
hostim db mysql rm app -y

hostim db redis ls
hostim db redis create cache --plan sr-1
hostim db redis get cache
hostim db redis status cache
hostim db redis credentials cache -o json
hostim db redis rm cache -y

--plan is required on create. Plan IDs differ per engine — sp-* for Postgres, sm-* for MySQL, sr-* for Redis — and hostim regions pricing <region> --for postgres|mysql|redis lists them with their storage and price.

Postgres extensions:

hostim db postgres extensions ls              # what a database can request (alias: ext)
hostim db postgres extensions add main postgis pg_trgm

Load a plain-SQL dump (pg_dump --format=plain). It goes through the project's SSH bastion into psql. SQL errors are printed and counted but do not stop the import, because dumps from other hosts carry a few harmless ones (event triggers, extension owners, unknown settings). It exits non-zero only when psql cannot run the dump at all, for example when it cannot connect. Like exec, it offers to authorize your SSH key; -y adds it without asking.

hostim db postgres import main -f dump.sql
hostim db postgres import main -y < dump.sql

Read the credentials into an app's environment in one step:

hostim db postgres credentials main -o json \
  | jq -r '"DATABASE_URL=postgres://\(.username):\(.password)@\(.hostname):\(.port)/\(.database)"' \
  | xargs hostim env set -a web

volumes

hostim volumes ls                                   # aliases: volume, vol
hostim volumes get data
hostim volumes create data --plan vol-1
hostim volumes rm data -y

The plan sets the size (vol-1 is 5 GB); list plans with hostim regions pricing <region> --for volume.

Mount a volume on an app with hostim deploy <app> --volume data:/var/lib/app.

backups

hostim backups                        # schedule, retention and last backup per resource
hostim backups create                 # start a manual backup of the whole project
hostim backups create data --wait     # back up one resource and wait for it to finish
hostim backups ls data                # the backups of one database or volume, newest first
hostim backups ls main --kind postgres   # skip the kind lookup
hostim backups download 1a2b3c4d               # prepare, then download
hostim backups download --latest data          # the newest backup of one resource
hostim backups download 1a2b3c4d -f -           # write to stdout (no resume)

hostim backups lists every database and volume with the time of its last backup, then the schedule and the retention policy. Times are in your local time zone. hostim backups create starts a manual backup; without a resource it backs up the whole project. --wait polls until the run finishes and exits non-zero if it did not succeed. hostim backups ls shows the size of the data before compression; the downloaded file is smaller. hostim backups ls needs the resource name; if a database and a volume share a name, pass --kind postgres|mysql|volume. hostim backups download --latest <resource> skips the ID lookup and takes the newest backup. hostim backups download prepares the file first, which can take minutes for a large backup, then downloads it. If the transfer is interrupted, run the same command again: it resumes from the partial <file>.part on disk. -f - writes to stdout and cannot resume.

Downloads are compressed with zstd. A database backup is a .sql.zst file (unpack with zstd -d <file>), a volume backup a .tar.zst archive (unpack with tar --zstd -xf <file>; it unpacks into a folder named after the volume).

templates

A template is one YAML description of a whole stack — volumes, databases, Redis and apps — that apply creates in dependency order, waiting for each resource.

hostim templates ls                        # curated templates (aliases: template, tpl)
hostim templates show freshrss

# deploy a curated template into the current project
hostim templates apply --id freshrss

# deploy into a brand new project
hostim templates apply --id freshrss --new-project blog --region eu-center

# save it as YAML, edit, then deploy the edited file
hostim templates apply --id freshrss --save stack.yml
hostim templates validate -f stack.yml     # offline check, no API calls
hostim templates apply -f stack.yml -y

# convert a docker-compose file into a template
hostim templates apply --compose docker-compose.yml --save stack.yml
hostim templates apply --compose docker-compose.yml