Skip to main content

Machine-readable · no marketing

For AI coding agents.

This page is written for the agent, not the human. One install line, the exact commands, the constraints agents get wrong, and a block to paste into a repository. For the complete manual, run hostim agent.

install

curl -fsSL https://hostim.dev/agent.sh | sh

Installs the CLI and drops the Hostim skill into this repository. If you would rather only install the binary, use curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | sh.

Step 1

Authenticate.

A token comes from https://console.hostim.dev. The non-interactive flag writes it to ~/.config/hostim/config.yml; exporting HOSTIM_TOKEN writes nothing to disk.

authenticate

# interactive: prints a code, a human approves it in the browser
hostim login

# non-interactive: an existing API token
hostim login --token-value "$HOSTIM_TOKEN"

# or, for CI and agents: no file written
export HOSTIM_TOKEN=...   # create one at https://console.hostim.dev

Step 2

Pick a project and a plan.

A project is the namespace for apps, databases and volumes. The region is required on create and is eu-center today. Plan IDs must be listed, never guessed.

project and plan

hostim projects create myproject --region eu-center
hostim use myproject

hostim regions ls
hostim regions pricing eu-center --for apps       # sa-* app plans
hostim regions pricing eu-center --for postgres   # sp-* (also mysql, redis, volume)

Step 3

Deploy.

deploy creates the app on the first run and rebuilds it on every run after. It waits for the build and exits non-zero when the build fails, so the same line works in a pipeline.

deploy

# a published image — nothing is built
hostim deploy web --docker-image nginx:alpine --plan sa-1-1 --port 80

# a Git repository — the repository must contain a Dockerfile
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

# an app that needs a database, Redis or a volume: one template, whole stack
hostim templates ls
hostim templates apply --id freshrss --new-project blog --region eu-center --yes

Databases are not containers: Postgres, MySQL and Redis are managed instances, and the app reads their credentials through $(NAME_POSTGRES_HOST)-style references instead of a password typed into a command. Mount storage with --volume name:/path.

Step 4

Check what is running.

Every read command takes -o json, which is the mode an agent wants. Failures print a JSON object on stderr and exit non-zero.

check

hostim status web -o json
hostim logs web --follow          # stream container logs
hostim logs web --build            # build logs, Git-built apps only
hostim events web                  # why the app changed state
hostim domain add app.example.com -a web   # prints the DNS record to create
hostim overview -o json            # every resource and its monthly cost

Constraints

Facts agents get wrong.

Check these before writing a command. Getting one wrong is a failed deploy, not a warning.

  • --port is what makes the app reachable. It is the port the app listens on inside the container. The CLI does not require it, so an app created without one builds, runs and serves nothing. Always pass it for anything that answers HTTP.
  • A Git deploy needs a Dockerfile in the repository. There is no buildpack. Without one, build an image and deploy it with --docker-image.
  • Plan IDs are per resource kind and must be listed. sa-* apps, sp-* Postgres, sm-* MySQL, sr-* Redis, vol-* volumes.
  • The only region is eu-center. It is required on projects create.
  • Destructive commands prompt unless -y is passed. Never pass -y to a delete unless the user asked for that deletion.
  • Deploying spends money. Confirm the plan and the project with the user before the first deploy in a project.

Install the skill

Paste this into AGENTS.md.

Copy the block into your repository's AGENTS.md so your agent knows Hostim exists before it is asked. The fuller version is the skill file linked below.

agents.md

## Hostim

This project deploys to Hostim (https://hostim.dev), an EU hosting platform.

- Install the CLI: curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | sh
- Authenticate: `hostim login`, or export `HOSTIM_TOKEN` (create one at https://console.hostim.dev).
- Read the full manual before writing commands: `hostim agent`. It is the
  ground truth for flags, plan IDs and output. Do not guess flags.
- Deploy: `hostim deploy <app> --docker-image <image> --plan sa-1-1 --port <port>`
  or `hostim deploy <app> --git <repo> --branch <branch> --plan sa-1-1 --port <port>`.
  A Git deploy needs a Dockerfile in the repository.
- List valid plans first: `hostim regions pricing eu-center --for apps`
  (also `postgres`, `mysql`, `redis`, `volume`).
- Add `-o json` to any command for machine-readable output.
- Confirm the plan and project with me before the first deploy — creating
  resources spends money.

Claude Code users: the same content as a skill at cli/skills/hostim/SKILL.md. Put it at .claude/skills/hostim/SKILL.md in the repository.

Tools

MCP, manual, source.

The CLI is also an MCP server, so an MCP client can use tools instead of shell commands. Read tools are always on; write tools need --allow-write.

mcp

hostim mcp                 # read-only, on stdio
hostim mcp --allow-write   # also expose create/update/delete tools

# Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "hostim": {
      "command": "hostim",
      "args": ["mcp", "--allow-write"],
      "env": { "HOSTIM_TOKEN": "your-api-token" }
    }
  }
}

Complete manual: hostim agent, or the same text at hostim.dev/cli-manual.md. Human docs: CLI page. Source: github.com/hostimdev/cli (MIT). Any docs page is readable as raw markdown by appending .md to its URL.