Pethost

View saved version →

---
name: pethost
description: The user's own hosting for their projects (Pethost). Use whenever the user wants to deploy, host, publish, ship or put something online, such as an app, a site, a bot, an API or a database, and for everything about what already runs there, including logs, domains, environment variables and secrets, restarts, rollbacks, files and shell commands. Pethost runs Docker Compose projects on the user's one rented machine.
license: MIT
compatibility: Needs the Pethost MCP server (streamable HTTP, sign-in by OAuth) and a Pethost account (https://pethost.dev).
---

# Pethost

Pethost is the user's hosting for their own projects: one rented Linux machine that runs Docker
Compose projects, each a directory with a `compose.yaml`. You run it with the tools of the
`pethost` MCP server; the person sees the same in Pethost's web panel.

The tools (`GetMachine`, `CreateProject`, `DeployProject` and the rest) are tool calls you make
yourself, like any other tool you have; where your client loads tools on demand, load them
first. They are not shell commands, and an answer is only ever what a call returned: never
write one yourself.

## Always

1. **Call `GetMachine` first, with `{}`, whatever the task.** It lists every project on the
   machine with its URL and its `problems`, the person's domain (`machine.apps_domain`) and
   whether backups are on. The app the person talks about is usually already there, even when
   your working directory is empty: look before you ask for anything.
2. **Read the answer, do not assume.** A call that deploys waits for the deploy and answers with
   the project as it then is: `operation.status`, `project.url`, `project.services[].state`,
   `project.problems`. No second call is needed, unless `operation.status` is
   `OPERATION_STATUS_IN_PROGRESS`: then `GetOperation` with `{"project_id":"…"}`, again until it
   ends.
3. **An error is a code and a sentence that says what to do.** Do that; do not work around it.
4. **Do what was asked and no more.** Asked what is wrong: find out and say. Change or deploy
   only what the person asked to change.

## Deploy something new

1. The directory needs a compose file at its root (`compose.yaml`, `docker-compose.yml`, …), or
   a `Dockerfile` alone (Pethost then writes the compose file: one service, `app`). With
   neither, write both. If the compose file there is written for a laptop (source bind-mounted,
   `--reload`, a published database port, a password in the file), leave it and write
   `pethost.compose.yaml` beside it: Pethost takes that one.

   ```yaml
   services:
     web:
       build: .
       env_file: .env          # only if the app has secrets
       volumes: [data:/data]   # whatever must survive a deploy
   volumes:
     data:
   x-pethost:
     metadata: { name: Recipe Box }
     routes:
       - { host: recipes.sam.pethost.app, service: web, port: 3000 }
   ```

   - `host`: `<name>.<machine.apps_domain>` is live at once with HTTPS, nothing to set up. Use
     it unless the person names a domain they own (see "A domain" below).
   - `port`: the port the app listens on, at `0.0.0.0`, not `127.0.0.1`.
   - A routed service needs no `ports:`. A database, a worker or a bot needs no route.
   - A compose file that already has `ports:`, such as an app's own from its repository, deploys
     as it is: never edit them out. A published port that answers HTTP gets
     `<project>.<machine.apps_domain>` by itself (`project.url`; `<project>-<service>.…` each
     when there are several) and is not opened on the machine; any other opens there as written.
     Send no `x_pethost.routes` then: with them the machine names nothing.
   - Data lives only in named volumes: whatever else a container writes is lost at the next
     deploy. Secrets live in `/.env`, never in `compose.yaml` or the image.
2. Send it, one of three ways:
   - **A directory on your disk** (the usual case): `CreateTransfer` with
     `{"upload_archive":{}}`, run the `com

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.