Contents

Pethost API

Everything the panel does to your machine, your agent can do too: they call the same methods.

Overview

Each plan you buy is a workspace: one machine of the plan's size, its apps domain and its backups. A call acts on the workspace its workspace field names, by id or name (ListWorkspaces lists them); without one, on the only workspace the token reaches, and with several it is refused with a WorkspaceChoice detail. The API is one service, pethost.panel.v1.PanelService, with 28 methods. 18 of them are also MCP tools, with the same name, the same request and the same response. The SDKs have those as methods, and the live streams too. The others serve the web panel. Each says what an agent uses instead.

The service is described in one file. This page is generated from it, and so are the web panel's client and the list of tools an agent sees: what you read here is what both of them call.

Calling it

There are two ways in. They run the same code and speak the same JSON.

As MCP tools

https://mcp.pethost.dev/mcp

Give this address to an MCP client, or install the plugin, which brings a skill with it. A tool is named after its method and takes the method's request as its arguments. Its result is the response, as JSON text and as structured content. An error is a result marked isError: the code and the message in one line, NOT_FOUND: …, then the error's details as JSON.

The endpoint keeps no session: a POST carries one JSON-RPC message and is answered in JSON.

Over HTTP

curl https://console.pethost.dev/pethost.panel.v1.PanelService/GetProject \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "blog"}'

A method is a POST of its request, as JSON, to https://console.pethost.dev/pethost.panel.v1.PanelService/<Method>; the answer is its response. This is a unary call of the Connect protocol, which any HTTP client can make. The streams are not called this way: an SDK reads them for you.

Authorization

A call of yours carries a token, pth_…. There are two ways to get one, and what a token can do is the same for both.

An API token, for your own program

Make one in the panel's Settings, under API tokens: give it a name and copy it. The panel shows a token once, when it is made, and keeps only its hash. Your program sends it with every call: Authorization: Bearer pth_…

OAuth, for an agent

An agent signs in by OAuth, as the MCP specification describes, and you approve it in your browser: there is nothing to copy.

  1. The client calls the MCP endpoint without a token. The 401 it gets leads it to the authorization server, https://console.pethost.dev, which describes itself at /.well-known/oauth-authorization-server.
  2. The client registers itself (POST /oauth/register), or is known by the address of its Client ID Metadata Document, and opens /oauth/authorize in your browser, with PKCE (S256).
  3. You sign in to the panel, read who is asking and where the answer goes, and press Connect.
  4. The client trades the code at POST /oauth/token for a token, pth_…, and sends it with every call: Authorization: Bearer pth_…

What a token can do

The web panel calls the same methods with your browser's session in place of a token.

Model

Workspace (workspace): what one plan buys: a machine of the plan's size, its apps_domain, its

backups. A call acts on the workspace its `workspace` names, by id or name; without one, on
the only one the caller has, and with several it is refused (WorkspaceChoice). Keep the id
from an answer (workspace_id), never the name: the person may rename it.

Machine: one VDS running the daemon, petnode: the one of the workspace a call acts on. Ids

below are unique within it: the same project_id in two workspaces is two projects.

The project is its directory

Its files declare everything (services, images, volumes, environment, hosts, name), and compose.yaml runs as written, or is refused with violations, each saying what to write: the machine corrects nothing in it. Source:

/.env and compose.yaml's x-pethost carry over between versions: after the first deploy, a new archive's or commit's own are ignored. Change them with DeployProject files (/.env) and x_pethost.

Conventions

Workspace

ListWorkspaces List workspaces

MCP toolRead-only

POST /pethost.panel.v1.PanelService/ListWorkspaces

The workspaces the caller may reach, by name, 20 a page: each one's id, name, size and what is free, location, hostname and apps domain. With project_id, also which of them hold a project of that id (holding_project). Free figures and project counts are each machine's latest sample, read now: one that did not answer in time leaves them absent (incomplete). The one call that takes no workspace. A caller that reaches none is refused as a call naming no workspace is: NoMachine (no plan) or WorkspaceNotGranted.

Request

project_id string

A project_id: holding_project then says which workspaces have a project of that id.

page_token string

A next_page_token. Empty = the first page.

Response

By name.

Empty = the last page.

total uint32

Workspaces in all, on every page.

holding_project array of string

With project_id: the workspaces that have a project of that id, by workspace_id. Empty = none of those that answered (see incomplete).

True = a machine did not answer in time: its free figures and project count are absent, and holding_project may lack it.

Machine

GetMachine Get the machine

MCP toolRead-only

POST /pethost.panel.v1.PanelService/GetMachine

Start here: the machine (resources, the person's domain, backups, SSH), every project with its problems and URL, deleted projects with snapshots, GitHub repositories to create projects from, and the workspace it serves. Figures are the latest sample; disk sizes and the day's traffic lag a few minutes. Several workspaces and no workspace: FAILED_PRECONDITION + WorkspaceChoice, which lists them.

Request

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

By project_id.

Projects no longer on the machine whose snapshots remain, the most recently backed up first; restore one with RunProjectAction.restore_snapshot and its project_id. Current after the machine's own backups and deletes; changes made to the backup repository elsewhere show later. Not known while Machine.snapshot_list_time is absent.

The workspace whose machine this is.

RunMachineAction Run a machine action

MCP toolDestructive

POST /pethost.panel.v1.PanelService/RunMachineAction

One machine action: add or remove the person's SSH public key (for SSH and SFTP to their projects' containers: Service.ssh_command), end a session, schedule or cancel a restart. Returns the machine.

Request

One of action: at most one of these is set.

label: one line, ≤100 chars; empty = the key's comment. An existing key gets the new label.

A Machine.ssh_keys fingerprint; its sessions end. NOT_FOUND = no such key.

Containers come back per restart policy. A new call before the restart replaces it; after (Machine.boot_time changed), restarts again.

True = cancels the scheduled restart.

A Machine.sessions id: ends it now (its key can open new ones until removed). NOT_FOUND = ended.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

As changed.

Project

GetProject Get a project

MCP toolRead-only

POST /pethost.panel.v1.PanelService/GetProject

One project in full: services (state, health, image, the ports it listens on, volumes, environment, the SSH command), volumes, routes, hosts with certificates, recent operations, snapshots, the last day's HTTP traffic. Env-file values and a database's password (Project.database.connection) only with include_secret_values. Its files: ReadPath.

Request

project_id string

True = include env-file values (EnvironmentVariable.secret) and a database's password (Project.database.connection). To edit .env: ReadPath /.env.

Only older snapshots: the oldest create_time seen, to page back. Absent = the newest.

Only snapshots holding this volume (Volume.snapshot_count). Empty = all.

Only incidents that opened before it: the oldest open_time seen, to page back. Absent = the newest.

≤90: Project.uptime_days. 0 = none.

With incidents_before: the incident_id of the oldest seen, so that those that opened at the same time are not skipped.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

CreateProject Create a project

MCP tool

POST /pethost.panel.v1.PanelService/CreateProject

Creates a project from its files and deploys it. Waits for the deploy (wait_seconds) and answers with the operation and, once it ended, the project: its URL, its services' states, its problems. violations instead = nothing was created: change what each says, call again. SUCCEEDED says the containers run and listen, not what a page answers: open the URL once (401 = its password page).

Files, one of: the directory as it is on your disk, as an archive (CreateTransfer, then upload_id): nothing is retyped; files, text you send yourself, when there is no directory or no shell (never a file you have not read); source.github. /.env holds the secrets (env_file: .env). The compose file is the root's pethost.compose.yaml (so the repository's compose.yaml stays for development), else compose.yaml, compose.yml, docker-compose.yml or docker-compose.yaml; it becomes /compose.yaml, other compose and override files are dropped. Without one, a Dockerfile yields service app (reading /.env if any, its EXPOSE ports, a named volume per VOLUME of its last stage).

A database (Postgres, MariaDB or Valkey) is CreateDatabase's: make the app's first, then link it here with link_databases, e.g. {database_project_id: "recipes-db", env_prefix: "DATABASE"}, and compose.yaml reads ${DATABASE_URL:?}. The app reaches each at the host <database_project_id> from its first start (its deploy waits for one still being made). own_user, on an engine whose offer has own_users (Postgres, MariaDB; a Valkey has one user), to share a database other apps use: a user and a database of its own, named as the project, which they cannot reach; all are restored together. Only link_databases makes one: LinkDatabase links as the apps' user. env_prefix "DATABASE": the machine writes DATABASE_URL, _HOST, _PORT, _USER, _PASSWORD and _NAME into /.env, so no password is copied. A name /.env sets already is refused, as a laptop's .env in an archive may set one: send files with a /.env without it beside upload_id.

compose.yaml rules. Data lives in named volumes; all else a container writes is lost when it is recreated. Project files are bind-mounted read-only. HTTP comes through the proxy, to a host of a route in x-pethost, the one extension read, in the file or as x_pethost:

x-pethost:
  metadata: {name: Recipe Box, emoji: "🥗", description: One line, notes: Free text}
  routes:
    - {host: recipes.sam.pethost.app, service: web, port: 3000}
    - {host: recipes.sam.pethost.app, path: /api, service: api, port: 8000, strip_path: true}

ports: stays as the file has it, and is never refused. A TCP port it publishes that answers HTTP gets its route by itself and is not opened on the machine: at <project>.<Machine.apps_domain>, or <project>-<service>.<apps_domain> each when the project has several; Project.url has it when the call answers. Any other published port opens on the machine as written, at <Machine.hostname>:<port>, and one that is taken there fails the deploy; so does a web port once its route is removed. Never opened: a port bound to 127.0.0.1 (ssh_command tunnels to it), a machine port of the machine's own (80, 443, 22), and one nothing listens on within a minute of its start, until a later deploy finds it listening (Service.published_ports lists what is open). With x_pethost.routes the routes are yours and the machine names none. A project that publishes no port gets <project>.<apps_domain> in its first deploy, for the one port it listens on. A service with neither is private: the project's services reach it at <service>:<port>. A password for visitors goes only as x_pethost.password, never into the file: every route then answers 401 with a password page, over HTTPS only; nothing returns it (Project.password_protected says it is set); and files that write /compose.yaml keep the password_hash line the machine put in its x-pethost. All of compose.yaml is interpolated: $$ for $.

The file runs as written, or is refused: the machine corrects nothing in it, in any version. Refused, each violation saying what to write instead:

  • a volume's name; driver (but Docker's default, local or bridge), driver_opts, external or ipam of a volume or network: remove them.
  • a writable bind mount of the whole project (.:/app): add :ro.
  • a volume with no name (- /data): name it. Below a bind mount it is allowed, as scratch space (/app/node_modules).
  • env_file naming a file the files lack: write it, empty if it sets nothing, or give the entry required: false.
  • privileged, cap_add, security_opt (but no-new-privileges), devices, host namespaces, the Docker socket, a path outside the directory; more than one replica; include or extends from a URL; a git URL as a build context.

Not refused, and read the machine's way: a container_name and a network's name name nothing on the machine, so two projects may write the same (the project's services still reach the container by it); a service with profiles runs only while COMPOSE_PROFILES in /.env names one of them, and is no service of the project until then; a bind mount of a folder without :ro (./data:/data) mounts the project's volume named after the path (data), which deploys keep and backups hold, with none of the version's files in it, so project files take :ro, and data is plainer in a named volume (data:/data, with data: under volumes:); a bind mount of a file without :ro mounts it read-only. An image's VOLUME that no mount covers fails the deploy (UNCOVERED_IMAGE_VOLUME): mount a named volume or a tmpfs there.

ALREADY_EXISTS = the id is taken (a retry with its operation_id returns that operation). An upload_id: FAILED_PRECONDITION = not arrived; NOT_FOUND = expired or used; one the machine refused (its PUT said why) answers with its violations. FAILED_PRECONDITION = the GitHub App cannot read the repository (see GetMachine.github), or no such branch or directory; + DatabaseLinkRefusal = a database of link_databases cannot be linked to it (database_project_id says which), and nothing was created. A deleted project's id inherits its snapshots.

Request

project_id string

New, [a-z0-9][a-z0-9_-]*, ≤63 chars; immutable.

Set = a GitHub project: {github: {repository}}. Absent = the files of this request.

upload_id string

An archive of the project's directory, from CreateTransfer.upload_archive, unpacked first.

files array of FileChange

The project's files, e.g. [{path: "/compose.yaml", text: "…"}, {path: "/.env", text: "…"}], or those to write over the archive's or the commit's. A github source takes only /.env.

Changes to the files' x-pethost: the name people see, the routes, a password.

As DeployProject's timeout_seconds.

As DeployProject's operation_id.

As DeployProject's wait_seconds.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

The first deploy: finished, or IN_PROGRESS when wait_seconds ran out (then GetOperation). Absent when violations stopped it: nothing was created.

adjustments array of string

With violations: what the machine had changed, as in Operation.adjustments. A deploy that started lists them in operation.adjustments only.

Once the operation ended, however it did: the project as GetProject returns it.

The log's last lines, unless it SUCCEEDED: why it FAILED, or what it is doing.

DeployProject Deploy a project

MCP toolDestructive

POST /pethost.panel.v1.PanelService/DeployProject

Deploys a new version of a project and answers as CreateProject does: files written over its own (/.env, /compose.yaml, a source file), x_pethost (name, routes, password), mount_volume, a new archive (upload_id, which replaces all files but /.env and x-pethost), a commit, or an earlier deploy's files again as a new version (rollback_deploy_id; /.env, x-pethost and volumes stay). compose.yaml rules: CreateProject's.

It builds build: images, pulls missing ones, runs compose up on the whole project and waits until each service runs (healthy, if it has a healthcheck) or each job exits 0, and until each routed service listens on its route's port (up to 15 s: one that does not is the project's SERVICE_PORT_CLOSED problem, its route answering 502, not a failed deploy). So it also starts stopped services, reruns jobs, recreates changed services and those bind-mounting project files, and fails on an unhealthy service. While Project.x_pethost_applies_at_once, a version differing only in x-pethost (or not at all) applies at once, restarting nothing but a service whose published port a route takes or leaves. Any other deploy applies its routes and password as it ends: to hide new content from its first second, set the password first, in a call of its own, then deploy the content.

A commit other than GithubSource.newest_commit turns auto_deploy off (pinned), even if it fails; only set_source turns it back on.

NOT_FOUND = no such project, or no such kept deploy. ABORTED = base_deploy_id is not Project.deploy_id: reread, redo. FAILED_PRECONDITION = as CreateProject, or commit not on the branch. RESOURCE_EXHAUSTED = too many or too large files: send them with CreateTransfer. ALREADY_EXISTS = operation_id started another kind of operation. When it FAILED, Operation.made_current says whether the files were applied: then fix them, or roll back.

Request

project_id string

Project.deploy_id as you read it. Empty = no check.

files array of FileChange

Written in order over the current files, or over the new version's: e.g. [{path: "/.env", text: "…"}] writes that file whole, and the files not named stay. With no new version pethost.compose.yaml is refused: write /compose.yaml. github: only /.env. None = redeploy.

Edits x-pethost by part, after files: metadata by key; routes all at once.

Not with upload_id, or github.

For the whole deploy, builds included; 0 = default.

For a safe retry: the same id returns the first call's operation and starts nothing. [A-Za-z0-9][A-Za-z0-9._-]*, ≤128 chars; empty = generated.

One of version: at most one of these is set.

A new version of the files; none = the current one.

upload_id string

files project: an archive from CreateTransfer.

commit string

github project: a commit of its branch (SHA, ≥7 chars), from ListCommits.

github project: true = GithubSource.newest_commit, read now.

files project, a rollback: the operation_id of an earlier deploy with files_kept (Project.operations).

Seconds to wait for the deploy's end, ≤45. Absent = 45; 0 = answer once it started. Still IN_PROGRESS then: GetOperation waits on.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

The deploy: finished, or IN_PROGRESS when wait_seconds ran out (then GetOperation). Absent when violations stopped it.

Why the files cannot be deployed: nothing changed and no operation started.

adjustments array of string

As in CreateProjectResponse: with violations only.

Once the operation ended, however it did: the project as GetProject returns it.

The log's last lines, unless it SUCCEEDED: why it FAILED, or what it is doing.

MoveProject Move a project to another workspace

MCP toolDestructive

POST /pethost.panel.v1.PanelService/MoveProject

Moves a project to another workspace of the same person, as one operation (OperationKind MOVE): it is stopped here, backed up into the destination's backups, restored and started there under the same project_id, then deleted here. Each database it is linked to (Project.dependencies) stays here, with its other apps, if any, running on: there the project uses one of the same engine instead, one the destination has or a new one, with the data of the database it signs in to copied, or none (DatabaseSwitch). A database project moves only when no app is linked to it. workspace is the source. Waits as DeployProject does (wait_seconds), then GetOperation, in either workspace, which once it ended answers the same move_message and the project. Answers, once it ended, with the project as it is in the destination, and move_message: what changed (hosts move to the destination's apps_domain, a domain of the person's own must point at its hostname, a new SSH command, which database it uses there instead of each, and with what data) and what stayed behind (operation history, logs, incidents, uptime, earlier snapshots, and what each database it left still holds). Until the restore succeeded, a failure undoes it: the source's services run again as they did, unless its failure says they did not start again; the move's snapshot stays in the destination's backups, as a deleted project's. After that it only goes forward: one that FAILED then moved the project, and its failure names what the source still holds. While it runs, a change to the project is UNAVAILABLE + ProjectBusy (kind MOVE) in either workspace, and so is a read where it is not then (before its restore, after its deletion from the source); afterwards, a call for it to the source is FAILED_PRECONDITION + ProjectMoved, until the source has a project of that id again. While it runs, a change to a database it leaves here, or to the one it uses instead there, is ProjectBusy too, as is a read of a new one before the move made it; GetOperation answers the move with any of their project_ids. INVALID_ARGUMENT = switch_databases names a database the project is not linked to, or twice, an env_prefix where the machine wrote the lines, none where it did not, one of no form a link takes or one two switches share, or an into the destination lacks or of another engine, or one two switches share, copies of more than 32 databases, or to_workspace is the source or none of the caller's; PERMISSION_DENIED + WorkspaceNotGranted = one this token may not reach. ALREADY_EXISTS = the destination has a project of the project's id, or of the id a new database takes, or operation_id is an operation of the project's or another move's already. FAILED_PRECONDITION = a database project with apps linked to it (the message names them: move each, or unlink it), a machine needs an update first (the message names it), the project has no deploy yet, or the destination's backups are off (its Machine.backups_enabled), which a move goes through.

Request

project_id string

The destination, as workspace takes one: its id or name.

As DeployProject's operation_id: the move's.

As DeployProject's wait_seconds.

What it uses in to_workspace instead of each database it is linked to (Project.dependencies), which stays here. One left out: the destination's database of its id and engine, if it has one, else a new one, with the data of its copy_database.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

The move: finished, or IN_PROGRESS when wait_seconds ran out (then GetOperation).

Once the project is in the destination: as it is there, as GetProject returns it. A move that FAILED after that has it too: it runs there, and its failure says what the source still holds. Absent while it runs, and when nothing moved.

What changed and what stayed behind, for people: the new hosts, the domains of the person's own to point at the destination's hostname, the SSH command.

GetMoveChoices

Web panel onlyRead-only

POST /pethost.panel.v1.PanelService/GetMoveChoices

What MoveProject may do with each database the project is linked to, for the web panel's move dialog: for each of Project.dependencies, the databases of to_workspace that DatabaseSwitch.into_database_project_id may name, whether a new one may be made there, and the choice the dialog starts from. MoveProject judges switch_databases by the same rules. Not an MCP tool: an agent reads Project.dependencies, and MoveProject chooses each switch it leaves out. NOT_FOUND = no such project. INVALID_ARGUMENT, PERMISSION_DENIED + WorkspaceNotGranted = as MoveProject's to_workspace. FAILED_PRECONDITION + NoMachine = to_workspace has no machine yet.

Request

project_id string
workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

One for each database the project is linked to, in Project.dependencies' order.

ListCommits List a project's commits

MCP toolRead-only

POST /pethost.panel.v1.PanelService/ListCommits

A github project's branch commits that change its directory, newest first, 30 a page, with whether the files are at it and its last deploy. To roll back: DeployProject with an older commit (volumes keep their current data). FAILED_PRECONDITION = a files project (it rolls back with DeployProject.rollback_deploy_id), no such branch, or before_commit not on it.

Request

project_id string

The previous page's last sha. Empty = from the newest.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

Newest first, at most 30.

more bool

Older ones exist: pass the last one's sha as before_commit.

RunProjectAction Run a project action

MCP toolDestructive

POST /pethost.panel.v1.PanelService/RunProjectAction

One project action: start, stop or restart services, recreate one, back up, restore, cancel an operation, change the source or a database's size, delete an undeclared volume or the project. Recreate, back up, restore, set_database_size, delete and set_source's deploy run as operations (operation_id), waited for (wait_seconds), as is the end of a cancelled one; the others are done on return. Answers with the project as it then is. With no services, start_services starts those with a container and restart_services the running ones. restore_snapshot takes the project's own snapshots only: a deleted app's data in a shared database is in that database's snapshots. A database's snapshot as a new database beside it is CreateDatabase's, with from_snapshot_id.

delete_project: a final backup while backups are on, then containers, volumes, files, hosts, logs, and an app's user and database of its own in a shared database, data and all. Snapshots stay (GetMachine.deleted_projects), and restoring one brings the project back, source included; with backups off there is none, and it is gone for good. The databases it was linked to stay: delete each with its own delete_project.

set_database_size gives a database another of its engine's sizes (Machine.database_engines; its size now is Project.database.memory_limit_bytes): the machine writes its compose.yaml anew for that size, with the settings that follow from it, so never edit them by hand, and with the image it runs and the other flags of its command as they were written, a server setting added or changed there included; what else was written there goes. The database restarts, and its apps lose their connections for a few seconds: one that does not connect again shows as restarting (GetMachine). A size changes nothing on the bill: a smaller one only leaves memory to the other projects. A Valkey whose data is more than the size keeps (its maxmemory, 70 % of the size) is refused before anything changes, and the refusal gives both figures: FAILED_PRECONDITION + DatabaseSizeRefusal, as for a Valkey that does not answer now, asked to shrink, and a database whose data is in another volume than the one the file names. FAILED_PRECONDITION alone = the project is no database. INVALID_ARGUMENT = a size its engine does not offer (the message lists them).

Request

project_id string
One of action: at most one of these is set.

Starts stopped services and reruns jobs, not their dependencies. FAILED_PRECONDITION = no container yet (deploy or recreate_service), or a published machine port is taken.

Stops services, each with its grace period. A machine restart may start them, per restart policy.

Restarts processes in the same containers. Codes as start_services.

A new container: a fresh filesystem outside volumes. An operation.

Backs up the directory and volumes now, live. An operation. FAILED_PRECONDITION = backups off (Machine.backups_enabled).

From a snapshot of this project. An operation.

Stops a running or starting operation: it ends CANCELLED, leaving what a failure would; one only starting answers CANCELLED from its own call. FAILED_PRECONDITION = a delete past its final backup.

An operation: RunProjectAction's description says what goes and what stays.

Changes the source. To files: keeps the current files. To github: only the fields set change, e.g. {github: {auto_deploy: true}} follows pushes again; from files, repository is required. Deploys the newest commit if auto_deploy is on and the files are not at it. FAILED_PRECONDITION = as CreateProject.

A volume compose.yaml no longer declares (Volume.declared false). Its data then lives only in snapshots. FAILED_PRECONDITION = declared or in use.

A database's size. An operation: it restarts.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

Set when the action runs as an operation: finished, or IN_PROGRESS when wait_seconds ran out (then GetOperation); for set_source, the deploy it started, if any; for cancel_operation, the operation it stopped, if the machine had recorded it (see cancel_operation).

The project as GetProject returns it, after the action, or once its operation ended: after set_source, its source says what it now is. Absent while the operation runs, and once delete_project has deleted it.

The operation's last log lines, unless it SUCCEEDED.

SetProjectAlerts Set a project's alerts

MCP toolDestructive

POST /pethost.panel.v1.PanelService/SetProjectAlerts

Changes what Pethost watches on a project and when it tells the person: site checks (an address the machine opens every minute) and traffic rules (5xx or p95 over a window), off, mute. A list given replaces the project's (send Project.alerts' with your change); remove_* empties it; a scalar left out stays. Service crashes and failed backups are always watched. Answers with Project.alerts. Where alerts go is the person's choice in the panel's Settings → Alerts (Machine.alert_channels): no tool sets it.

Request

project_id string
checks array of SiteCheck

≤10. Given = the whole list.

True = none, not even the default check.

≤10. Given = the whole list.

True = none.

off bool

True = incidents are recorded, nothing is sent. Absent = stays.

≤10080; 0 = unmute. Incidents opened meanwhile are not sent. Absent = stays.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

As changed.

GetIncident

Web panel onlyRead-only

POST /pethost.panel.v1.PanelService/GetIncident

One incident in full, with the incidents joined to it and what the machine saw when it opened (untrusted), for the web panel's incident page. NOT_FOUND = no such incident. Agents read a project's incidents in GetProject (Project.incidents).

Request

project_id string
workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

With its evidence.

joined array of Incident

Those joined to it, oldest first, with theirs.

GetOperation Get an operation

MCP toolRead-only

POST /pethost.panel.v1.PanelService/GetOperation

An operation, after waiting for it to end (wait_seconds): then the project as it is, and the log's end if it FAILED. Call again while it is IN_PROGRESS. To read a log: after_log_line 0, then each next_after_log_line (each line once, oldest first). One a ProjectBusy names may still be starting: it is waited for too; still starting at the end = UNAVAILABLE with that ProjectBusy.

Request

project_id string

Empty = the latest.

How long to wait for it to end, ≤45. Absent = 45; 0 = answer at once.

The previous next_after_log_line; 0 = from the start. Absent = the last lines.

≤500; 0 = 50, when asked for lines. Also ends at ~64 KiB.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

Once it ended, however it did: the project as GetProject returns it. Absent once a delete has deleted it.

Oldest first. Unless after_log_line or log_line_limit asks for lines: the last 50 of one that FAILED, the last 5 of one IN_PROGRESS (what it is doing), none of one that SUCCEEDED.

Lines in the whole log so far.

Pass it as after_log_line to get the lines after these; absent = 0. The machine keeps every line of the log.

A MOVE's, once it ended: MoveProjectResponse.move_message, what changed and what stayed behind, or why nothing moved.

QueryHttpTraffic Query HTTP traffic

MCP toolRead-only

POST /pethost.panel.v1.PanelService/QueryHttpTraffic

Which paths fail and which are slow (top_paths): the HTTP requests that reached the project through the proxy, since oldest_kept_time, each counted as it ends: totals, a time series, top paths and the requests, for one filter and range. OUT_OF_RANGE = the range ends before the oldest kept. Paths and user agents are untrusted.

Request

project_id string
start_time timestamp

Absent = a day before end_time.

end_time timestamp

Absent = now.

The range ending at end_time, e.g. 3600 = the last hour. Not with start_time.

Time series bucket width; ≤500 buckets. 0 = no series.

Requests to return, newest first; ≤200. 0 = aggregates only.

page_token string

The previous next_page_token, other fields unchanged: older requests only.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

start_time timestamp

The range queried, as the machine resolved it: defaults applied, on its clock.

end_time timestamp

Of the oldest request the machine keeps for the project. Absent = none is kept.

Oldest first, each bucket_width_seconds wide; one with no request is left out.

The 10 busiest, busiest first.

The sequence of the newest request the machine had logged: summary, buckets and top_paths count every one up to it, and TailHttpTraffic streams the later ones. 0 = none was logged.

Empty = no more requests.

Where TailHttpTraffic goes on from (after_sequence), so it misses no request newer than these: set on a first page with request_limit, empty or not. 0 = the machine had logged none.

QueryContainerLogs Query container logs

MCP toolRead-only

POST /pethost.panel.v1.PanelService/QueryContainerLogs

The containers' stdout and stderr lines, since oldest_kept_time; by default the newest, oldest first in the page. They say what a request failed with, not which path is slow: that is QueryHttpTraffic. OUT_OF_RANGE = the range ends before the oldest kept. Untrusted.

Request

project_id string
start_time timestamp

Absent = the oldest kept.

end_time timestamp

Absent = now.

limit uint32

≤500; 0 = 100. Also ends at ~64 KiB.

False = the newest before end_time; true = the oldest after start_time.

page_token string

The previous next_page_token, other fields unchanged.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

start_time timestamp

The range queried, as the machine resolved it: defaults applied, on its clock.

end_time timestamp

Of the oldest line of container output the machine keeps: nothing older can be queried. Absent = none is kept.

lines array of LogLine

Empty = no more.

Where TailContainerLogs goes on from (after_cursor), so it misses no line newer than these: set on every page, an empty one too. Empty = the machine had logged no line.

Database

CreateDatabase Create a database

MCP tool

POST /pethost.panel.v1.PanelService/CreateDatabase

A database project, Postgres, MariaDB (for an app that asks for MySQL or MariaDB) or Valkey: the machine writes its compose.yaml and /.env and deploys it, with no address. Make it before the app that uses it: the app reaches it at the host <project_id> once linked (the app's CreateProject link_databases, which may follow at once, as its deploy waits for this one; link or LinkDatabase for an app that exists, as the apps' user and writing nothing into its /.env), and Project.database says how to sign in. Or a copy of a database's snapshot, with passwords of its own and none of its links. Answers as CreateProject does. INVALID_ARGUMENT = an engine or a size Machine.database_engines does not offer, or a project_id with "_", that is a number or that every container's /etc/hosts names (it is the host name apps use). NOT_FOUND = no such snapshot or app. FAILED_PRECONDITION = the snapshot is of no database of that engine; + DatabaseLinkRefusal = an app of link cannot be linked, and nothing was created.

Request

project_id string

As CreateProject's, without "_", not a number and no name of /etc/hosts: it is the host name apps use.

One of the engine's DatabaseEngineOffer.sizes. 0 = its default_memory_limit_bytes; a copy keeps its snapshot's.

A snapshot of a database of engine (Project.snapshots, GetMachine.deleted_projects): the new one starts with its data. Empty = an empty database.

As DeployProject's operation_id.

As DeployProject's wait_seconds.

What people see, e.g. {name: "Postgres for Recipes"}. Absent = the machine's (the id).

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

LinkDatabase Link projects to a database

MCP toolDestructive

POST /pethost.panel.v1.PanelService/LinkDatabase

Lets projects that exist reach a database project: inside each linked project the database is the host <database_project_id> at its port. Takes effect at once and deploys nothing, and writes nothing into a project's /.env: put Project.database.connection's url there (GetProject include_secret_values) with DeployProject files. A project it links signs in as the apps' user, app (a Valkey's one user), or as its user of its own if CreateProject's link_databases made it one there (own_user), which nothing else makes. INVALID_ARGUMENT = a project in both link and unlink. NOT_FOUND = no such project. FAILED_PRECONDITION = database_project_id is no database; + DatabaseLinkRefusal = the app is a database, has a service named or aliased like the database, or there are 20 links already. Answers with the database's Project.

Request

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

The database, as GetProject returns it.

GetDatabaseStats

Web panel onlyRead-only

POST /pethost.panel.v1.PanelService/GetDatabaseStats

A database's numbers over a range, for the web panel's Monitoring: every bucket of it, its totals, its 10 busiest statements (Postgres, MariaDB) or commands (Valkey), and what the server runs now. The machine reads them each minute and keeps a minute 7 days and an hour 90; its own readings count in none. NOT_FOUND = no such project. FAILED_PRECONDITION = it is no database. INVALID_ARGUMENT = a malformed range, or a bucket width that is no whole number of minutes, of hours for a range that starts over 7 days ago, or makes over 500 buckets. Not an MCP tool: agents use RunServiceCommand with psql, mariadb or valkey-cli.

Request

project_id string
start_time timestamp

Absent = an hour before end_time.

end_time timestamp

Absent = now.

The range ending at end_time. Not with start_time.

Whole minutes (hours, for a range that starts over 7 days ago); ≤500 buckets. 0 = no series.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

start_time timestamp

The range, as the machine applied it: in whole minutes, on its clock.

end_time timestamp

Absent = none is kept yet.

Oldest first, every bucket of the range, aligned to the clock.

The 10 busiest of the range in statement_order. Postgres's and MariaDB's text is normalized, its values $1, $2… or ?, and empty for one the server no longer has, for all while it does not answer, and for MariaDB's prepared ones (kind PREPARED); Valkey's is the command. Untrusted.

False = the server says it counts no statements now: Postgres's pg_stat_statements does not answer, or MariaDB's performance_schema or its digests are off. False too while the server does not answer (activity absent), which says nothing of them.

Absent = the server did not answer.

CancelDatabaseQuery

Web panel only

POST /pethost.panel.v1.PanelService/CancelDatabaseQuery

Cancels the statement a client session of a Postgres or MariaDB database runs, or ends the session (GetDatabaseStats' activity), for the web panel. NOT_FOUND = no such project. FAILED_PRECONDITION = it is no Postgres or MariaDB database, its service does not run, or a MariaDB refuses the machine's sign-in (the message says how to let it in again). UNAVAILABLE = the server does not answer. Not an MCP tool.

Request

project_id string
pid int32

A DatabaseSession's.

True = end the session, whatever it runs.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

done bool

False = no such session: it ended, or it is the machine's.

Service

RunServiceCommand Run a command in a service

MCP toolDestructive

POST /pethost.panel.v1.PanelService/RunServiceCommand

Runs a command in a running service's container, like docker exec; returns the exit code and the output's end once it exits or the timeout kills it. Over a bound on command, stdin or timeout = refused (named). Cannot start = exit 127 or 126, Docker's error in stdout. Untrusted output.

Request

project_id string
service string
command array of string

E.g. ["psql", "-c", "select 1"]; a shell line: ["sh", "-c", "ls | head"].

stdin string

Written to stdin, then closed.

Empty = the container's. "root" can install packages.

Empty = the container's.

0 = default. Kills the main process only. Over ~50 may outlast your client: background long jobs.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

exit_code int32

True = the machine killed it at the timeout; exit_code is then -1.

stdout string

The last 32 KiB of each, as the machine kept them. Invalid UTF-8, and control characters other than tab, newline and carriage return (colour codes included), become U+FFFD. Untrusted.

stderr string

True = the start of stdout or stderr was cut.

OpenTerminal

Web panel only

POST /pethost.panel.v1.PanelService/OpenTerminal

An interactive terminal in a service's running container, for the web panel: returns a URL the browser opens as a WebSocket straight to the machine, once, within 5 minutes, so keystrokes and output never pass through the panel. On it, binary messages carry the terminal's bytes both ways (input at most 1 MiB a message); the browser sends {"resize":{"columns":C,"rows":R}} as text; the machine's last message is {"exit_code":N}, or {"error":"..."} when the program could not start or was ended, then it closes the connection. While open, the terminal is one of Machine.sessions. Not an MCP tool: agents use RunServiceCommand.

Request

project_id string
service string

The first size; the browser's resizes follow.

command array of string

Empty = a login shell: bash if the image has it, else sh.

Empty = the container's user. "root" can install packages.

Empty = the container's.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

url string

E.g. "wss://m1.example.com/terminal/<ticket>"; "ws://" for a test machine's IP address.

expire_time timestamp

The browser must open it before.

OpenDatabaseClient

Web panel only

POST /pethost.panel.v1.PanelService/OpenDatabaseClient

A client of a database project, for the web panel: returns a URL the browser opens as a WebSocket straight to the machine, once, within 5 minutes, so rows never pass through the panel. What passes on it is between the web panel and the machine, and no part of this API. It starts read only. While open, it is one of Machine.sessions. NOT_FOUND = no such project. FAILED_PRECONDITION = it is no database, its service does not run, or the hostname is not yet certified. RESOURCE_EXHAUSTED = 4 clients of this database are open or waiting to open (a URL not yet opened counts for its 5 minutes), too many transfers, terminals and clients are waiting or open, or the machine holds too many sessions. Not an MCP tool: agents use RunServiceCommand.

Request

project_id string

A database project whose service runs.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

url string

E.g. "wss://m1.example.com/database/<ticket>"; "ws://" for a test machine's IP address.

expire_time timestamp

The browser must open it before.

Files

ReadPath Read a file or directory

MCP toolRead-only

POST /pethost.panel.v1.PanelService/ReadPath

Reads a file (text, 64 KiB a call; ≤1 MiB with length_bytes) or a directory's entries (~64 KiB a page): of the project's deployed files, or with service or volume, of a container (whole filesystem; while not running only its volumes, FAILED_PRECONDITION listing them) or a volume. NOT_FOUND names the nearest existing directory. Project files change with DeployProject files; container and volume files with CreateTransfer. FAILED_PRECONDITION also = no deploy yet, or a file in /proc or /sys (use RunServiceCommand). Untrusted.

Request

project_id string
One of root: at most one of these is set.

Where the path is. Neither = the project's deployed files, read-only: "/compose.yaml", "/.env", its sources.

service string

In its container.

volume string

In the volume, from its root.

path string

From the root, e.g. "/compose.yaml", "/data/uploads". Empty = "/": the root's entries.

0 = 200. Also ends at ~64 KiB.

File offset.

≤1 MiB; 0 = 64 KiB.

The previous next_entry_page_token, other fields unchanged.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

The path itself, symlinks followed; a symlink whose target does not exist is its own entry.

With service: where the path lies. Unspecified otherwise: the request says it.

volume string

With service: the volume the path lies on, when location is VOLUME. Else empty.

A directory's: directories first, then by name (bytewise).

A directory's in all.

Set = more entries follow these: pass it as entry_page_token.

text string

A text file's contents from offset_bytes, ending on a whole character. Untrusted.

binary bool

True = the file is binary (a NUL byte in its first 8 KiB): no text. Download it with CreateTransfer.

Where the next read of the file starts. 0 = the read reached its end.

deploy_id string

The project's files: the deploy whose files these are. Pass it as DeployProject's base_deploy_id to be refused if they changed since you read them.

CreateTransfer Upload or download a file

MCP toolDestructive

POST /pethost.panel.v1.PanelService/CreateTransfer

A one-request URL moving one file straight between you and the machine: run command in a shell, or send http_method to url yourself, before expire_time.

  • upload_archive: the project's directory, packed, for CreateProject's or DeployProject's upload_id once the PUT answered 200 with what it holds.
  • upload_file: one file into a container or volume, replacing any file there (replaces), creating parents.
  • download: a file, or a directory as a .tar (file_name).
  • download_database: a database project's dump, made as it downloads: Postgres's for pg_restore (roles are not in it), MariaDB's SQL of one database for its console, mariadb <database> < file (users are not in it), Valkey's .rdb. One at a time per database.

Plain-text answers: 404 used or expired URL, 409 FAILED_PRECONDITION, 413 archive over 2 GiB, 422 unsafe archive (a reason per line), 503 UNAVAILABLE, 507 disk full. A failed transfer keeps nothing: get a new URL. Errors as ReadPath; FAILED_PRECONDITION also = downloading neither a file nor a directory, uploading onto a non-file, a mount point, /proc or /sys, the hostname not yet certified, or a dump of a project that is no database or is not running, or of a MariaDB that refuses the machine's sign-in (the message says how to let it in again). NOT_FOUND also = a Postgres or MariaDB database the server lacks (the message lists its databases). RESOURCE_EXHAUSTED = disk full, or too many transfers. UNAVAILABLE = Postgres or MariaDB runs but does not answer yet: try again shortly.

Request

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

url string

On the machine's hostname (Machine.hostname); it works once.

"PUT" or "GET".

expire_time timestamp

Start the request before this.

command string

Does it in a shell. upload_archive: packs the current directory and sends it, e.g. "tar czf - --exclude=.git --exclude=node_modules . | curl -sS --fail-with-body -T - '<url>'": run it in the project's directory (a ready archive: curl --fail-with-body -T <file> '<url>'). upload_file: "curl -sS --fail-with-body -T '<file>' '<url>'", with your file's path in place of its name. download: "curl -sS --fail-with-body -o 'photo.jpg' '<url>'".

upload_id string

upload_archive: for CreateProject.upload_id or DeployProject.upload_id once the machine answered the PUT with 200.

upload_file: a file is at path now; the upload replaces it.

file_name string

download: the name it saves as: a file's own; a directory's ends in ".tar", and "/" is named after the project and its service or volume. download_database: "<project_id>-<database>.dump" (Postgres), "<project_id>-<database>.sql" (MariaDB) or "<project_id>.rdb". Empty for an upload.

exclude_names array of string

upload_archive: the names command leaves out of the archive, wherever they lie in the directory. A program that packs the directory itself leaves out the same.

GetUpload

Web panel onlyRead-only

POST /pethost.panel.v1.PanelService/GetUpload

What an archive from CreateTransfer holds: files, the compose file it would run, /.env; or, if refused (422), the violations. For the web panel: the PUT's own answer says the same to an agent. FAILED_PRECONDITION = not arrived (PUT still going, or cut: CreateTransfer again). NOT_FOUND = expired, or used by a deploy.

Request

upload_id string

From CreateTransfer.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response

file_count uint32

Its files, as unpacked.

Of those files.

What a project of it runs: the compose file CreateProject will use ("pethost.compose.yaml", "compose.yaml", "docker-compose.yml", …), or "Dockerfile" (a compose.yaml is written for it). Empty = none of them at its root.

env_file string

Its /.env: the project's unless CreateProject.files writes /.env. Empty = none. Untrusted.

Why the machine refused it, such as an entry that leads outside it: it cannot be deployed, and the fields above are empty. Empty = the machine took it.

Streams, for the web panel and the SDKs

WatchOperation Watch an operation

SDK methodStream

Streams an operation's log from its start, then follows it; the last message is the finished operation. Without a stream: GetOperation.

Request

project_id string

Empty = the latest.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response, each message of the stream

One of message: at most one of these is set.

Always the last message.

With a MOVE's finished_operation: MoveProjectResponse.move_message.

TailContainerLogs Follow container logs

SDK methodStream

Streams container output after a cursor, then new lines as they are written. OUT_OF_RANGE = the machine no longer keeps the cursor's line, so lines after it may be gone too: start over with QueryContainerLogs and tail after its tail_cursor. Without a stream: QueryContainerLogs.

Request

project_id string

Empty = only lines written from now on.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response, each message of the stream

cursor string

To reconnect after this line.

TailHttpTraffic Follow HTTP traffic

SDK methodStream

Streams HTTP requests after a sequence number, then new ones as they finish. Without a stream: QueryHttpTraffic.

Request

project_id string

0 = only requests from now on.

workspace string

The workspace: its id or name (ListWorkspaces). Omit when the account has one.

Response, each message of the stream

Types

The messages and enums that the requests and responses are made of, in the order the API declares them. An enum's value for "not set" is left out: an absent field says it.

Workspace WorkspaceStatus WorkspaceRole Machine AlertDestination AlertChannelKind MachineSession MachineSessionKind DiskUsage SshKey GithubConnection GithubRepository DeletedProject MovedTo RestartMachineAction ProjectMetadata ProjectSummary ServiceSummary ProjectProblem ProjectProblemKind Project ProjectDependency RunningServicesAction ServicesActionKind ProjectSource GithubSource GithubCommit Service ServiceState PublishedPort VolumeMount RestartPolicy HealthCheck HealthStatus EnvironmentVariable Volume VolumeMountedBy Host Route CertificateSource Operation OperationKind OperationStatus DeployFailureReason Snapshot HttpTrafficSummary DatabaseLinkRequest MountVolume ProjectExtension FileChange SpecViolation DatabaseSwitch MoveChoice MoveTarget BranchCommit ServicesAction RecreateServiceAction BackUpAction RestoreSnapshotAction CancelOperationAction DeleteProjectAction SetDatabaseSizeAction DatabaseEngine Database DatabaseConnection DatabaseSummary DatabaseEngineOffer DatabaseSizeChoice DatabaseStatsBucket DatabaseStats DatabaseCommandStats DatabaseCommandKind PostgresStats ValkeyStats MariadbStats DatabaseStatement DatabaseStatementOrder DatabaseActivity DatabaseSession DatabaseSessionState DatabaseSlowCommand SiteCheck TrafficRule TrafficMetric ProjectAlerts SiteCheckState SiteCheckResult TrafficRuleState AlertStatus Incident IncidentQuietReason IncidentEvidence UptimeDay OperationLogLine HttpTrafficFilter HttpTrafficBucket HttpPathTraffic HttpRequest ContainerLogFilter OutputStream LogLine FileEntry FileType FileLocation ArchiveUpload FileUpload PathDownload DatabaseDump ProjectBusy ProjectChanged MachineUnreachable DatabaseLinkRefusal DatabaseLinkRefusalReason DatabaseSizeRefusal DatabaseSizeRefusalReason NoMachine PaymentOverdue NoMachineReason WorkspaceChoice WorkspaceNotGranted ProjectMoved TerminalSize

Workspace message

What one plan buys: a machine of the plan's size, its apps domain and its backups, and the projects on it. A call names it as workspace, by workspace_id or name.

8 characters of a-z and 2-7, e.g. "k7f3q2xy": what to keep, since it never changes and is never another workspace's.

name string

The person's, e.g. "Personal": unique among their workspaces, in any case, and they may change it.

location string

Where its machine runs, e.g. "Europe".

plan string

Its plan's name, e.g. "Starter".

The plan's.

What the projects leave of memory_total_bytes, in its machine's latest sample. Absent = not known: BEING_PREPARED, or the machine did not answer in time.

Likewise. Absent as memory_free_bytes.

Absent as memory_free_bytes.

hostname string

Its machine's name, as Machine.hostname: SSH, transfers, and where a domain of the person's own points (CNAME). Empty while BEING_PREPARED.

As Machine.apps_domain. Empty = none.

end_time timestamp

When it ends: the person removed it, and it works until then, its projects with it. Absent = it is not ending.

The caller's.

WorkspaceStatus enum

Its machine answers calls.

Paid, and its machine is being prepared: Pethost emails the person when it is ready. A call that names it is FAILED_PRECONDITION + NoMachine until then.

WorkspaceRole enum

Pays for it, and may do everything in it.

Machine message

name string

Its plan's name, e.g. "Starter".

location string

Where it runs, e.g. "Europe". Empty = not known.

sample_time timestamp

When the figures below were read.

By projects and builds.

Without page cache, as docker stats counts.

The machine's, less a reserve for the system.

The projects' disk. The operating system has its own partition outside it, and the machine's own files are left out: a new machine uses 0.

hostname string

The machine's name: what the person's own domains point at (a CNAME), and where they log in to a service's container (Service.ssh_command). CreateTransfer's URLs are on it as well, and no route can take it.

True = hostname is an IP address, not a name (a test machine's): no DNS record can point at it by name (a CNAME), so a domain must resolve to that address itself.

"SHA256:...", to check on the first connection.

ssh_keys array of SshKey

The person's public keys: each logs in to every container. Empty = none yet: nobody can log in until RunMachineAction.add_ssh_key adds one.

True = every project is backed up nightly, and on demand. False, always written = nothing is backed up: there are no snapshots, and a deleted project or volume is gone for good.

When the machine last read the backup repository's list of snapshots whole. Absent = not yet (snapshot_list_failure_message says why, once a read failed), or backups are off: snapshot counts, Volume.last_backup_time, Project.snapshots and GetMachine.deleted_projects are then not known, rather than none.

Why the machine could not read that list, while backups are on and snapshot_list_time is absent: the backup repository's error, e.g. a wrong password or a host that does not answer. The machine keeps trying. Empty = no read has failed, or the list is known, or backups are off.

Snapshots are pruned once they are this many hours older than their project's newest. 0 = kept forever: nothing deletes them.

True = a host that no certificate installed on the machine covers gets one from Let's Encrypt once it resolves to the machine. False, always written = such a host serves plain HTTP only.

The person's domain on Pethost, e.g. "sam.pethost.app": theirs alone, so "my domain" or "my Pethost domain" means this one unless they name another. A route's host <name>.<apps_domain>, or apps_domain itself, works at once over HTTPS, with no DNS record to make, and a web port a project publishes gets such a host by itself (CreateProject). Only the person changes it, in the panel's settings. Empty = there is none: every host is a domain the person owns, and published ports all open on the machine.

boot_time timestamp

When an update started to need a machine restart. Absent = none is needed.

When RunMachineAction.restart_machine will restart it; later while what it waits for is still going on (RestartMachineAction.interrupt_operations). Absent = not scheduled.

What people have open in the containers now, oldest first: at most 100, the most the machine holds at once.

Where Pethost tells the person of incidents: the account's channels that are on, email first, then the oldest. The person sets them in the panel's Settings → Alerts; no tool does. Empty = alerts reach nobody.

The databases the machine makes (CreateDatabase), one per engine, with the sizes they may take (RunProjectAction.set_database_size).

The sum of every service's mem_limit. Limits, not a reservation: they may add up to more than memory_total_bytes. What the projects use is memory_used_bytes.

AlertDestination message

A channel Pethost tells the person of incidents on (Machine.alert_channels).

label string

The chat's title, or "#ops · Acme". Empty for email.

AlertChannelKind enum

The account's email.

A Telegram chat or group.

A Slack channel.

MachineSession message

Something a person has open in a container: a web terminal (OpenTerminal), a database's client (OpenDatabaseClient), or, through SSH, a program, SFTP or one connection of a tunnel. It lasts until the program exits or the connection closes; RunMachineAction.end_session_id ends it sooner.

project_id string
service string
port uint32

TUNNEL: the container's port.

start_time timestamp

The person's IP address.

Through SSH: the key they logged in with, as it was then. Empty for WEB_TERMINAL and DATABASE_CLIENT.

MachineSessionKind enum

The web panel's terminal.

A program in a terminal, such as ssh's shell.

A program without a terminal, such as ssh ... <command> or rsync.

scp, sftp or sshfs.

One connection of an ssh -L tunnel to port.

The web panel's client of a database.

DiskUsage message

Where the disk goes; the rest of disk_used_bytes is the filesystem's own metadata and the machine's small files. Measured every few minutes.

Absent = not known: Docker cannot size the build cache.

What containers wrote outside volumes.

Project directories and operation logs.

Kept on the operating system's partition, outside disk_used_bytes; the machine bounds their age and size (QueryContainerLogsResponse.oldest_kept_time).

The HTTP request log.

SshKey message

public_key string

The public key, as in authorized_keys: "ssh-ed25519 AAAA..."; never a private key.

label string

Shown in the panel and session logs, e.g. "MacBook Pro".

"SHA256:...". Ignored on input.

GithubConnection message

The panel's GitHub App, one for every account: projects are created from the repositories of the installations of it the account connected, on the person's own GitHub account or on an organization's; of an organization's, only those the person who connected it can read on GitHub now. Absent = GitHub is not set up on this panel.

app_name string

As in https://github.com/apps/<app_name>.

The panel's page that sends a signed-in person to GitHub to install the app on their repositories or their organization's, or to change which. On the way it connects every installation GitHub lists for them, such as one an owner of their organization made.

The repositories of the account's installations, most recently pushed first, at most 200.

In all.

False = pushes reach the panel only by its check every 5 minutes, not at once.

GithubRepository message

repository string

"owner/name".

private bool
push_time timestamp

DeletedProject message

project_id string

Restore it to bring the project back as it was last backed up; GetProject then pages the older ones (snapshots_before).

In all.

Set when the latest move of the project from or to this workspace took it to another one, and this workspace has had no other project of the id since, as a call for it here would answer ProjectMoved: call it there (workspace), which answers for it as it is now. A restore here makes another copy here, as it was last backed up here, and calls here then act on that copy.

MovedTo message

Where a move took a project (MoveProject), and when.

move_time timestamp

RestartMachineAction message

restart_time timestamp

Absent = now, or at_maintenance_window. INVALID_ARGUMENT = in the past.

True = the next nightly window (Machine.scheduled_restart_time). Not with restart_time.

False = wait for operations and nightly backups to end; true = cut them short.

ProjectMetadata message

name string

Empty = none: people see the id.

emoji string

One line.

notes string

Free text.

ProjectSummary message

project_id string

Most urgent first. Empty = nothing wrong.

By name.

url string

The first route's host as a URL, e.g. "https://recipes.example.com". Empty = no route.

hosts array of string

Every host its routes use, in the routes' order.

The last day's requests, 5xx responses and latency, as in Project: QueryHttpTraffic says which paths. Absent = no request.

deploy_time timestamp

As in Project.

Operations in progress, newest first: a backup can run beside another one.

pinned bool

A github project stays on its commit: GithubSource.pinned.

Its volumes, files, what its containers wrote outside volumes, and its images: one it shares with another project counts in both. Measured every few minutes.

Set = a database project (CreateDatabase).

uid string

As Project.uid.

ServiceSummary message

ProjectProblem message

Something that needs attention. A service has at most one, its cause first.

service string

Empty = not about one service. DEPLOY_FAILED: the service that failed it, when one did.

DEPLOY_FAILED, DEPLOY_CANCELLED, BACKUP_FAILED, RESTORE_FAILED: the operation; GetOperation gives its log.

since_time timestamp

DEPLOY_FAILED, DEPLOY_CANCELLED, BACKUP_FAILED, RESTORE_FAILED: the operation's end. SERVICE_EXITED, RESTARTING and OUT_OF_MEMORY: when its last run ended, once it did; else its last start. AUTO_DEPLOY_REFUSED: when auto-deploy tried the commit. Absent = not known, as for UNHEALTHY.

One sentence for people, without a time of day (since_time has it), e.g. "bot fails its healthcheck: 11 failures in a row". A failed or cancelled deploy's also says whether it changed the project.

The open incident that records it (Project.incidents). Empty = none yet.

ProjectProblemKind enum

The latest deploy failed. Its operation says why, and with made_current whether its files were applied (then some containers may run the old configuration).

Running; its healthcheck fails.

Docker is restarting it, or it runs and Docker restarted it recently: likely a crash loop.

Its last run was killed for exceeding its memory, or a process of it was since it started. A loop whose runs last 10 s or more shows as RESTARTING: Docker forgets the kill when it starts it again.

The latest backup failed; its operation says why.

The latest deploy was cancelled; its operation says, with made_current, whether its files were applied.

It exited on its own with a non-zero code (Service.exit_code) and stays down: its restart policy does not restart it. A service a person stopped is no problem.

A restore failed or was cancelled, or a machine restart cut it short, and its harm remains: services it stopped are still stopped (starting them ends it); unless a restore that succeeded since replaced them, its volumes may be partly restored, and its operation's undo_snapshot_id holds them as they were. Or it brought a deleted project back, and no deploy has replaced it. The newest such restore counts; one that changed nothing does not.

Auto-deploy is on, and the machine refused the commit it last tried, the branch's newest then, which the files are not; the message says why. Each commit is tried once: fix it and push, or DeployProject with newest_commit, whose refusal gives the violations.

It runs and does not listen on the port a route sends to (or only at 127.0.0.1, which the proxy cannot reach): the route answers 502. The message names the ports it does listen on (Service.listening_ports): change the route's port with DeployProject.x_pethost, or the app.

A site check (Project.alerts) failed 3 times in a row; service: the one its route sends to.

A traffic rule on 5xx holds.

A traffic rule on p95 holds.

A database the machine has not set up for 2 minutes since it started, or whose apps' user is gone: the message says the engine's error.

Project message

project_id string
url string

As in ProjectSummary.

deploy_id string

The operation_id of the deploy whose files the project has. For a deleted project brought back, the RESTORE that did it. Empty = no deploy yet.

How that operation went, or is going. Unspecified = no deploy yet.

deploy_time timestamp

When the current deploy made its files the project's. Absent = no deploy yet, or one that failed or was cancelled leaving no service with a container: nothing runs.

True = the current deploy succeeded and every service has a container, so a deploy whose files differ only inside x-pethost (or not at all) applies at once, with no build or pull, and no restart but the one DeployProject names. False = the next deploy runs in full.

services array of Service

By name.

volumes array of Volume

Every one the machine holds for the project, by name.

routes array of Route

x-pethost.routes as the machine holds them, in order: the list x_pethost.routes replaces, so send these back with your change to add, change or remove one.

hosts array of Host

Every host of the routes, in the order of its first route.

True = every route asks visitors for the project's password (x_pethost.password). The password itself is never returned.

Newest first, every one the machine keeps: the newest 20, any still in progress, and however old, the current deploy's (deploy_id) and those whose files it keeps for a rollback (Operation.files_kept). Older ones are gone.

The newest 10, newest first, of those GetProjectRequest's snapshots_before and snapshots_volume select. Empty while backups are off or the list is not read yet (snapshot_list_time).

The project's, in all; see snapshot_list_time.

When the machine read the list of snapshots that snapshot_count, Volume.snapshot_count and Volume.last_backup_time come from (Machine.snapshot_list_time, as sampled with them). Absent = the list is not known: backups are off, or it is not read yet (Machine.snapshot_list_failure_message says why); a count of 0 then does not mean none.

Measured every few minutes.

The start_services, stop_services or restart_services that runs now, whoever called it (RunProjectAction waits for its end). Until then the project takes no other action or deploy, and Service.state is still what it was before. Absent = none.

What Pethost watches and how each part stands.

The newest 5 that GetProjectRequest.incidents_before selects, newest first: an open one in full but its evidence (GetIncident), a resolved one as its id, kind, times, message, after_operation_id, quiet_reason and flapping.

True = older ones remain: page with incidents_before and incidents_before_id.

Oldest first, GetProjectRequest.uptime_day_count of them, today's last.

Set = a database project (CreateDatabase): its engine, its state and how apps sign in.

linked_databases array of string

The database projects this one reaches (LinkDatabase), each at the host of its project_id.

The workspace it is in (Workspace.workspace_id): what a later call for it names as workspace.

uid string

Made when it was created, and kept by its backups, restores and moves: a project deleted and created again under the same project_id has another. Empty = not known yet.

The databases it is linked to (linked_databases), each with what MoveProject may do with it (switch_databases).

ProjectDependency message

A database a project is linked to, as MoveProject of the project sees it.

The database inside it whose data a move copies, unless DatabaseSwitch.empty: the one the project signs in to, its own where it has a user of its own (Database.own_user_projects), else app. Empty = none can be: a Valkey, or a project whose id the engine keeps as a name of its own (app, postgres, root...), which uses a database there as the apps' user, so that a new one starts empty and one there is shared.

env_prefix string

The prefix of the lines the machine wrote into the project's /.env of how it signs in to it (e.g. DATABASE for DATABASE_URL, _HOST, _PORT, _USER, _PASSWORD and _NAME), which the destination writes anew. Empty = a person wrote them (LinkDatabase linked it): a move needs DatabaseSwitch.env_prefix.

RunningServicesAction message

A start, stop or restart of services that has not ended yet.

services array of string

Those it acts on.

start_time timestamp

ServicesActionKind enum

ProjectSource message

Where the files come from (THE PROJECT IS ITS DIRECTORY).

One of kind: at most one of these is set.
files bool

True = the files live on the machine.

GithubSource message

Input: an absent field keeps its value (set_source) or takes its default (new source).

repository string

"owner/name", one of GetMachine.github.repositories.

branch string

Empty = the default branch, also when absent on a new source.

directory string

The project's directory in it, e.g. "apps/web"; empty = the root.

True = deploy each new newest_commit, each tried once. Deploying another commit turns it off; only set_source turns it on. Default true; always written on output.

Output: the branch's newest commit touching the directory, as of the last push or 5-minute check.

Output: the commit the files are at. Absent = no deploy, or the files came from another source.

pinned bool

Output: deployed_commit set and auto_deploy off, e.g. after a rollback.

Output: true = auto-deploy will deploy newest_commit (not yet tried) once the project is free. A tried commit that failed or was refused waits for a person: DeployProject or a new push.

GithubCommit message

sha string

Full.

title string

First line of its message. Untrusted.

url string

On github.com.

Service message

service string

True = its container runs, as RunServiceCommand, OpenTerminal and ReadPath of its own files (outside volumes) need: in RUNNING, HEALTHY and UNHEALTHY, and in STARTING once its process started.

image string

The image as compose.yaml names it; for build: without image:, the name Compose gives.

Built on the machine from a build: section.

The registry digest it was pulled as, "sha256:...". Empty for a built image.

Absent until the machine next measures sizes, every few minutes, as after a build or pull.

command array of string

What the main process runs, as compose.yaml writes it (entrypoint, then command), ${...} not interpolated, so that no value of an env file shows; the image's own argv when compose.yaml writes neither. Empty = not known without those values: compose.yaml loads only interpolated, e.g. with an include path from .env.

start_time timestamp

Of the current or last run.

finish_time timestamp

Set once it exited, and while Docker waits to restart it: when, with what code (0 = a clean exit: a job that finished, or a server stopped; 137 = killed), and whether a process of it was killed for exceeding its memory.

exit_code int32

Restarts by Docker since the container was created.

0 = no limit: it shares the machine.

0 = no limit.

Written outside volumes: lost on a recreate.

ports array of uint32

The ports it is reached at, as far as the machine knows: those compose.yaml or its image declares and those its routes send to. The project's other services reach it at <service>:<port>.

listening_ports array of uint32

The TCP ports its processes listen on now, at an address the proxy and the other services reach: a route's port must be one of them. Empty = it does not run, or listens on none.

The ports ports: opens on the machine now: not one a route serves, nor one bound to 127.0.0.1.

Absent = no healthcheck.

What the container is configured with, not what its image sets.

env_files array of string

The files its env_file: names, as compose.yaml writes them, e.g. "./.env": relative to the project directory. Change them with DeployProject.files.

What the person runs in their own terminal for a shell in its container, e.g. "ssh [email protected]". It works once one of their public keys is among Machine.ssh_keys.

ssh_login string

The address ssh_command logs in at, e.g. "[email protected]": scp, sftp, rsync and ssh -L tunnels take it too. Empty when ssh_command is.

ServiceState enum

Declared; no container yet.

Starting, or created while an operation that starts containers runs (deploy, recreate_service, restore); its healthcheck has not passed yet.

Running, without a healthcheck.

Running; its healthcheck passes.

Running; its healthcheck fails.

Exited and Docker is restarting it.

Not running: stopped by stop_services or a restore, never started, paused or dead.

Not running: it exited on its own (see exit_code; 0 = a job that finished).

PublishedPort message

A port that ports: opens on the machine directly, to anyone, bypassing the proxy.

0 = Docker picks one when the container starts.

protocol string

"tcp", "udp" or "sctp".

VolumeMount message

volume string

E.g. "/var/lib/postgresql/data".

RestartPolicy enum

Docker's restart policies: what happens when the process exits, and when the machine starts.

Never restarted.

Restarted when it exits non-zero. When the machine or Docker restarts it comes back unless it exited 0 (a finished job), so one stopped with stop_services comes back too. The default when compose.yaml sets none.

Always restarted, unless stopped with RunProjectAction.stop_services.

HealthCheck message

The healthcheck Docker runs: compose.yaml's, else the image's HEALTHCHECK.

command array of string

The program and its arguments, e.g. ["curl", "-f", "http://localhost:8000/health"]; a test written as a shell line is ["/bin/sh", "-c", <line>]. Written and known as Service.command is: compose.yaml's healthcheck.test, else the image's.

How often Docker runs it.

Absent while the service is not running.

recent_results_passed array of bool

Up to the last 5 checks, oldest first.

Of the latest failed check, at most 4 KiB. Untrusted.

HealthStatus enum

EnvironmentVariable message

name string
value string

Absent when empty, when secret and GetProject had no include_secret_values, or when value_left_out.

secret bool

True = its value is not empty and comes from an env file, directly or through ${...} in compose.yaml: env files hold the secrets. Empty values, and values written in compose.yaml itself, are not secret. The machine hides these values in operation logs too.

The file to edit to change it, absolute in the project's directory: "/compose.yaml" (the service's environment:, which wins) or the env file it comes from, e.g. "/.env", "/web.env". Empty = the machine cannot tell, as when compose.yaml takes that file's path from .env.

from_env_file_variables array of string

When compose.yaml builds it from ${...}: the .env variables to edit to change it.

True = the value is left out: the project's values together hold more than about 64 KiB. Read source_file with ReadPath.

Volume message

volume string
size_bytes uint64

Measured every few minutes.

Of the newest snapshot that holds this volume. Absent = no snapshot holds it, or the list is not known (Project.snapshot_list_time).

The snapshots that hold it, in all; GetProjectRequest.snapshots_volume lists them. See Project.snapshot_list_time.

False, always written = compose.yaml no longer declares it, so no service mounts it: it keeps its data and is in every backup until RunProjectAction.delete_volume or the project is deleted. ReadPath reads it with the volume root, restore_snapshot restores it, and declaring it again mounts it as it is.

VolumeMountedBy message

service string

Host message

A host of Project.routes, with its certificate.

host string

As x-pethost.routes[].host.

url string

"https://<host>" once its certificate is served, and plain HTTP is redirected there; until then "http://<host>", which reaches the services. For AUTOMATIC, the host must resolve to the machine first. A protected project (Project.password_protected) is never served over plain HTTP: it is always redirected, so the host answers only once its certificate is served.

When the certificate served expires. Absent = none is served yet.

Why the host answers nobody: a name under the panel's domain that is not one label under Machine.apps_domain (another account's, or two labels deep): change its host. One under a former apps_domain of this account moves by itself to the same name under the new one, within a minute of the change, unless the project's last deploy failed or another project has that name. Empty = it answers, or it is the person's own domain.

Route message

An x-pethost route: requests for host under path go to port of service. The field names are the YAML keys.

host string

<name>.<Machine.apps_domain>, the person's domain on Pethost: HTTPS at once, nothing to set up. Or a domain they own: a CNAME to Machine.hostname (an ALIAS at the apex, never an IP address), certified once it resolves.

path string

Whole segments, the longest wins. Empty = "/": every path.

service string
port uint32

The port the service listens on in its container, at 0.0.0.0.

True = the path's prefix is removed from the request.

CertificateSource enum

No certificate will come: plain HTTP only. As when Machine.acme_enabled is off, or for an IP address or another name Let's Encrypt does not issue for.

A certificate installed on the machine covers it.

From Let's Encrypt, renewed automatically.

Operation message

start_time timestamp
finish_time timestamp

Absent while in progress.

When FAILED: why, for people. The log says more.

DEPLOY or RECREATE_SERVICE that FAILED: why, to branch on.

DEPLOY, or a RESTORE that brought a deleted project back: true = it made its files the project's. It stays true once a later deploy replaces them: Project.deploy_id names the one whose files the project has now. A deploy switches the files partway, when it starts the containers, so one that FAILED or was CANCELLED without it left the files as they were: to retry, send all its changes again. A project's first deploy has it from its start: its files stay however it ends, to fix and deploy again.

service string

RECREATE_SERVICE: the service. A failed DEPLOY or RECREATE_SERVICE: the service that failed.

DEPLOY or RECREATE_SERVICE that failed CONTAINER_EXITED.

BACKUP, or DELETE's final backup, that succeeded: the snapshot taken. RESTORE: the snapshot restored.

restored_volumes array of string

RESTORE: the volumes it replaced.

RESTORE: the backup taken first; restore it to undo. Empty = none was taken.

DEPLOY of a github project: the commit its files are, also when it changed only /.env or x-pethost.

DEPLOY of an uploaded archive: its file name.

adjustments array of string

DEPLOY: what making that version changed that its request did not write, for people: the earlier deploy whose files it took, the compose file it took or wrote for a Dockerfile, the compose files it left out, the project's /.env and x-pethost kept in place of the version's own. Nothing else in the compose file is changed: it runs as written.

changed_paths array of string

DEPLOY: the paths its request changed, for people, the first 10: DeployProject.files, or CreateProject's files; a move lists both paths. A commit's or an archive's own files are not listed: github_commit or archive_name says what they brought.

DEPLOY: the paths its request changed, in all.

DEPLOY: true = the machine keeps the files it deployed, which are no longer the project's: DeployProject.rollback_deploy_id puts them back. It keeps the 3 newest versions of the files before the current one; of deploys that changed only /.env or x-pethost, whose files are the same, the newest has it.

DEPLOY: the deploy that first deployed its files: itself when its request brought or changed files (a commit, an archive, a file other than /.env); else an earlier one, as after a deploy that changed only /.env or x-pethost.

DEPLOY of a size change (RunProjectAction.set_database_size): the size it gave the database.

OperationKind enum

MoveProject's, of the project it moves, in both workspaces. Its operation_id is the move's, which GetOperation and WatchOperation answer in either, also with the project_id of a database the move holds.

OperationStatus enum

DeployFailureReason enum

A wrong name or tag, or a private image.

E.g. the command does not exist.

Includes a machine restart during the operation.

A ports: machine port is taken.

Exited, or kept restarting, after starting.

The image declares a VOLUME no mount covers: it would never be backed up. Mount a named volume there.

The running projects leave too little memory for a build; the message says how much.

Its user of its own in a linked database (DatabaseLinkRequest.own_user) could not be made: the database does not run or answer, or refused; the message says which. Start it, then deploy again.

Snapshot message

create_time timestamp
size_bytes uint64

Of its files, the directory and every volume. 0 = not known.

volumes array of string

The volumes it holds, besides the project's directory.

HttpTrafficSummary message

5xx responses.

Of responses: WebSockets, logged when they close, count as requests but not here.

DatabaseLinkRequest message

MountVolume message

Adds <volume>:<container_path> to the service, declaring the volume if needed.

service string

A service of compose.yaml.

volume string

New, or one of Project.volumes.

Absolute, e.g. "/data".

ProjectExtension message

x-pethost as data. Absent parts stay.

Sets the fields given; an empty one is removed.

routes array of Route

The project's routes from now on: these replace all it has, so send Project.routes with your change to add, change or remove one. Empty = they stay.

True = the project has no route from now on. Not with routes.

password string

Visitors of every route must enter it. Empty = it stays.

True = no password. Not with password.

FileChange message

path and exactly one change.

path string

Absolute in the project's directory.

One of change: at most one of these is set.
text string

Writes the file as UTF-8 text, creating parents.

data bytes

Writes the file as bytes, likewise.

True = creates it and its parents.

delete bool

True = deletes the file, symlink or empty directory.

True = deletes a directory recursively, if present.

rename_to string

Moves it to this path.

With text or data: mode 0755, not 0644.

SpecViolation message

service string

Empty = not about one service.

location string

In compose.yaml, down to the key it is about, e.g. "services.db.volumes[0]", "x-pethost.routes[2].host"; or a file's absolute path, e.g. "/.env".

What is wrong and what to write instead.

DatabaseSwitch message

A database the moved project is linked to, which stays here with its other apps, if any, and what the project uses instead in the destination: a database of the same engine, the lines of how it signs in to it in its /.env written anew. On Postgres and MariaDB it signs in there as a user of its own, to a database of its own, which gets the data of ProjectDependency .copy_database unless empty; a Valkey's it shares as its one user, and so does a project whose id the engine keeps as a name of its own (copy_database empty) on Postgres and MariaDB. Once the move succeeded, the user and database the project had of its own here, if it had them, are dropped with it, as any delete does: so empty, where it had them, deletes that data.

A database it is linked to, which stays.

A database of the same engine in to_workspace. On Postgres and MariaDB, where the project gets a user of its own there, it has no user or database named as the project. Empty = the destination's database of database_project_id's id and engine, if it has one, else a new one, made by the move under that id at that one's size where to_workspace offers it for the engine, else at the engine's default.

empty bool

True = nothing is copied: the project starts there with an empty database of its own, or, as the apps' user, with what a database there holds that it shares (a new one: nothing). A MariaDB database with a view, trigger, routine or event made by another account than the project's own user, as each in app is by the apps' user, cannot be copied: the move is undone; start it empty, or make those objects again as the project's own user.

env_prefix string

Where ProjectDependency.env_prefix is empty, as a person wrote the lines of how the project signs in to it: the prefix of those lines (e.g. DATABASE for DATABASE_URL), which the destination writes anew as a link with that env_prefix writes them, each of its names that /.env sets taking the new value, for the database copy_database names. Required there; refused elsewhere.

MoveChoice message

What a move may use in to_workspace instead of a database the project is linked to.

The dependency's, which a database used instead runs too.

owned bool

The project signs in to the dependency as a user of its own (Database.own_user_projects), which the move drops here with its database once it succeeded (DatabaseSwitch).

The databases of to_workspace of the engine, which into_database_project_id may name: each once among a move's switches.

A new database may be made there, under the dependency's id: to_workspace has no project of that id.

Where the dialog's switch goes first: the database of to_workspace of the dependency's id and engine, else its only one of the engine that no other choice suggests, else a new one where new_database, else the first of databases that no other choice suggests. Empty = a new one, or nothing fits (no databases, and no new_database).

MoveTarget message

A database of to_workspace that a switch may go to.

name string

As people call it: its metadata name, else its project_id.

data_bytes uint64

As in Database.

app_names array of string

The apps linked to it there, each as people call it.

BranchCommit message

author string

The author's GitHub login, else their name. Untrusted.

commit_time timestamp

When it was committed.

The project's files are this commit (GithubSource.deployed_commit).

The newest deploy of it among the operations the machine keeps; its status says how it went. Absent = none.

newest bool

True = the branch's newest commit that changes the directory, as GitHub answered this call: deploying any other turns auto_deploy off (see DeployProject).

ServicesAction message

services array of string

Empty = all.

RecreateServiceAction message

service string

True = pull the tag's newest image, or rebuild on the newest base images.

BackUpAction message

No fields.

RestoreSnapshotAction message

volumes array of string

Existing project: the volumes to replace (≥1); it is backed up first (Operation.undo_snapshot_id), stopped and restarted; files stay. Deleted project: files, source and volumes return, then it deploys.

CancelOperationAction message

Required.

DeleteProjectAction message

True = no final backup, while backups are on: changes since the newest snapshot are lost.

SetDatabaseSizeAction message

DatabaseEngine enum

MySQL's protocol: for an app that asks for MySQL or MariaDB.

Database message

A database project: one service running Postgres, MariaDB or Valkey, whose files the machine wrote.

As it was made, e.g. 18.

What the server says it runs, e.g. "18.6". Empty = not answering.

Its size: its service's mem_limit in compose.yaml. RunProjectAction.set_database_size changes it.

data_bytes uint64

Postgres, MariaDB: its databases' size; Valkey: its data in memory. On disk: Project.volumes.

Open now.

Valkey: maxclients.

linked_projects array of string

The projects that reach it: CreateProject's link_databases or LinkDatabase linked them. Each signs in as the apps' user (connection), but those of own_user_projects.

service string

The service of Project.services that runs the database.

volume string

The volume of Project.volumes that holds its data.

console_command array of string

The console, for OpenTerminal in service: psql or mariadb signed in as the superuser, or valkey-cli.

own_user_projects array of string

Of linked_projects, those linked with own_user (DatabaseLinkRequest): each signs in as a user of its own, to a database of its own, both named as it, with the password in its /.env. The others sign in as the apps' user, app (a Valkey's default), whether link_databases or LinkDatabase linked them; only link_databases wrote how into an app's /.env.

DatabaseConnection message

How a linked project signs in, as the apps' user.

host string

The database's project_id.

port uint32
user string

"app"; Valkey: "default".

database string

"app"; Valkey: "0".

password string

Only with GetProject's include_secret_values.

url string

For the app's .env, e.g. DATABASE_URL=<url>. Without include_secret_values, **** stands for the password.

local_url string

As url, at localhost (MariaDB's at 127.0.0.1, which a MySQL client does not take for its socket): what the SSH tunnel to its service gives (Service.ssh_command).

DatabaseSummary message

A database project in brief (ProjectSummary.database).

data_bytes uint64

As in Database.

linked_projects array of string

As in Database: all but own_user_projects sign in as the apps' user.

As in Database: empty = not answering, its figures are zero.

Its size, as in Database.

own_user_projects array of string

Of linked_projects, those with own_user, as in Database.

DatabaseEngineOffer message

An engine the machine makes databases of (Machine.database_engines).

The major a new database gets, e.g. 18.

Smallest first.

The size CreateDatabase gives when its memory_limit_bytes is 0, unless it copies a snapshot.

A project linked with own_user (DatabaseLinkRequest) gets a user and a database of its own in one of its databases, so several apps can share one. False = every app signs in as its one user, and own_user is refused (ONE_USER).

DatabaseSizeChoice message

A size a database may take.

DatabaseStatsBucket message

start_time timestamp

Absent = nothing is kept of it.

DatabaseStats message

What a database did over a time, and how high its levels went. Counts are of sampled_seconds, the time its server was read across.

0 = its server was not read twice in a row: no counts.

The last; measured minutes behind.

data_bytes uint64

The last, as Database.data_bytes.

By kind.

DatabaseCommandStats message

calls uint64
rows uint64

Postgres, MariaDB.

Valkey, MariaDB.

DatabaseCommandKind enum

MariaDB: the executions of prepared statements, as Go's driver, PHP's PDO without emulated prepares (Laravel's) and mysql2's execute() send a query with values, which the server counts together, with no text, whatever their verb.

PostgresStats message

Of every database of the server but postgres, where the machine reads them, and the templates; wal_bytes is the whole server's.

commits uint64
rollbacks uint64
blocks_hit uint64

Read from its cache.

Read from disk.

deadlocks uint64
temp_bytes uint64

Written to temporary files.

wal_bytes uint64
active_max uint32

Sessions running a statement.

On a lock.

ValkeyStats message

keys uint64

The last.

0 = none.

MariadbStats message

The whole server's counters; rows_read and tmp_disk_tables count its statements but the machine's, the prepared ones' included, while statements are tracked.

pages_hit uint64

Read from its buffer pool.

pages_read uint64

Read from disk.

rows_read uint64

Examined by its statements.

The rows written to its tables, by how.

deadlocks uint64
redo_bytes uint64

Written to the redo log.

Temporary tables written to disk.

active_max uint32

Sessions running a statement.

On a lock.

DatabaseStatement message

id string

Postgres's queryid, MariaDB's digest or "prepared" (kind PREPARED), or Valkey's command.

text string
calls uint64
rows uint64

DatabaseStatementOrder enum

DatabaseActivity message

What the server runs now.

read_time timestamp

Postgres, MariaDB: its client sessions but the machine's, those in a transaction first, the longest first; at most 50.

Of which sessions are a part.

Valkey's slow log, newest first; at most 20.

DatabaseSession message

A MariaDB session has no application_name or backend_start_time, and no query while idle.

pid int32

For CancelDatabaseQuery. Absent for a MariaDB session whose id is past 2147483647.

user string
database string

Untrusted.

Empty = the server's socket.

Absent = in none.

Of the last statement. Absent = none.

E.g. "Lock". Empty = not waiting.

wait_event string
blocked_by_pids array of int32
query string

Running, or Postgres's last that ran; ≤2000 characters. Untrusted.

DatabaseSessionState enum

DatabaseSlowCommand message

time timestamp
command string

E.g. "keys" or "client|list".

key string

Its first key, ≤200 bytes; empty = none. Untrusted.

Untrusted.

SiteCheck message

An address of the project the machine opens every minute through its proxy, from inside the machine. Down = no connection, a bad certificate, no answer in 10 s, the wrong status, or must_contain missing; 3 failures in a row open SITE_DOWN. A password page is passed.

host string

A Host.host of the project.

path string

"/…", ≤200 chars, a query allowed. Empty = "/".

100-599. 0 = any status below 500 is up: 401, 404 and redirects too.

≤100 chars, in the body's first 64 KiB. Empty = not looked for.

TrafficRule message

Fires when metric, over the last window_minutes of the requests filter selects, reaches threshold 2 minutes in a row; clears after 3 below.

status_class not taken.

threshold double

A count, a percent (0-100) or ms.

1-60. 0 = 5.

Percent and p95: fewer requests in the window leave the rule as it was. ≤10000. 0 = 20.

TrafficMetric enum

5xx responses in the window.

5xx, of the window's requests (WebSockets too).

ProjectAlerts message

What Pethost watches on a project (SetProjectAlerts), and how each part stands now. Service crashes, running out of memory, failed healthchecks, and failed backups, restores and auto-deploys are always watched.

Until set: the project's URL at "/" (machine_default); none without a route.

Until set: 10 or more 5xx in 5 minutes, of every request (machine_default); none without a route.

off bool

True = incidents are recorded, nothing is sent.

mute_end_time timestamp

Absent = not muted.

Of the time the checks ran in the last 30 days, the share they were up, e.g. 99.97. Absent = no check ran.

SiteCheckState message

The default check, as no list was set.

Absent = not run yet.

The open incident. Empty = none.

SiteCheckResult message

check_time timestamp
status uint32

0 = no HTTP answer: failure_message says why.

E.g. "connection refused", "status 502", "the text is missing". Empty = up.

TrafficRuleState message

The default rule, as no list was set.

value double

The metric at the last evaluation.

In the window then.

The open incident. Empty = none.

AlertStatus enum

It holds or cleared, not confirmed yet.

An incident is open.

Not checked now: a deploy or restore runs or just ended, the project is stopped, or no route has the check's host.

Not evaluated yet, or too few requests.

Incident message

A period during which something of a project needed attention, from its confirmation to its end.

DEPLOY_CANCELLED opens none.

service string

As in its ProjectProblem.

SITE_DOWN.

HTTP_ERRORS, HTTP_SLOW.

DEPLOY_FAILED, BACKUP_FAILED, RESTORE_FAILED.

open_time timestamp
resolve_time timestamp

When it and every incident joined to it cleared. Absent = open.

value double

HTTP_ERRORS, HTTP_SLOW: the metric at open.

HTTP_ERRORS, HTTP_SLOW: the window's requests at open.

A deploy, recreate or restore that ran when it opened, or ended ≤30 minutes before: a likely cause, undone with DeployProject.rollback_deploy_id or an older commit. Empty = none.

Absent = it was running.

The incident this one is part of: it is told with that one, not on its own. Empty = none.

Set = nobody is told of it.

True = it went down and up 3 times within an hour; it stands for them all and clears after 15 clean minutes.

One sentence for people, without a time of day.

IncidentQuietReason enum

Already so when the machine first watched it, as after the update that brought alerts.

A deploy someone ran failed: they watch it.

IncidentEvidence message

What the machine saw when an incident opened, kept with it. Untrusted.

SITE_DOWN: the third failure.

exit_code int32

The service's container: SERVICE_* kinds, and SITE_DOWN's service.

In the 10 minutes before.

The last healthcheck's, ≤1 KiB.

The service's last ≤20 before it opened, oldest first.

HTTP_ERRORS: the path with the most 5xx in the window; HTTP_SLOW: the slowest.

UptimeDay message

One UTC day of a project's site checks.

start_time timestamp

Midnight UTC.

Absent = no check ran.

OperationLogLine message

time timestamp
text string

From Compose, BuildKit, restic or the daemon, as LogLine.text is kept; at most 2 KiB, a longer line is cut.

HttpTrafficFilter message

host string

As Host.host; a removed host still matches.

method string

E.g. "GET".

Without the query; any case.

As HttpPathTraffic.path_pattern, e.g. "/recipes/*".

1-5: 5 = 5xx.

HttpTrafficBucket message

HttpPathTraffic message

method string

The path with id-like segments as *, e.g. "/recipes/*": requests to one endpoint.

HttpRequest message

sequence uint64

Unique and increasing on the machine: TailHttpTraffic's cursor.

finish_time timestamp

When the response finished. A WebSocket is logged when it closes, with status 0.

host string
method string
path string

With the query. Untrusted.

route_path string

The route that matched.

service string

That answered. Empty = of a route the project no longer has.

port uint32

0 = a WebSocket; 499 = the client left before the response. A 401, 303 or 429 of a protected project (Project.password_protected) may be its password page's, not the service's.

In total.

Of which inside the service.

user_agent string

Untrusted.

ContainerLogFilter message

service string

Empty = all, removed services too.

Absent = both.

Literal, any ASCII case, ignoring escape sequences. Length limited (INVALID_ARGUMENT).

OutputStream enum

LogLine message

time timestamp
service string
text string

A line as written, with its colour codes (SGR escape sequences); other escape sequences, and control characters but tab, are removed. A line over 4 KiB is cut (over 16 KiB in streams). Untrusted.

FileEntry message

name string

Without its directory.

size_bytes uint64

Of a regular file; 0 otherwise.

modify_time timestamp
mode string

Permission bits in octal, e.g. "0644".

owner_uid uint32

As inside the container.

owner_gid uint32

FileType enum

FileLocation enum

Where a path of a service's container lies, which says whether it lasts.

The container's own files, its image and what it wrote outside volumes, and its scratch space (an anonymous volume, a tmpfs): lost when it is recreated.

A named volume (ReadPathResponse.volume): kept across deploys and backed up.

The project's files, mounted read-only from its source as deployed: change them with DeployProject.

ArchiveUpload message

The project's directory as a zip, tar or tar.gz (told by content), for CreateProject's or DeployProject's upload_id: {} is enough. A single top folder is unwrapped; .git, __MACOSX, .DS_Store, ._* are dropped. Leave out what the build makes again (node_modules, .venv, target).

file_name string

The archive's name for people, e.g. "recipes.zip". Empty = "archive.tgz".

FileUpload message

project_id string
One of root: at most one of these is set.
service string

In its container.

volume string

In the volume, from its root.

path string

From the root, e.g. "/data/uploads/a.jpg".

PathDownload message

A directory comes as a .tar of what ReadPath shows; symlinks kept.

project_id string
One of root: at most one of these is set.

Where the path is. Neither = the project's deployed files.

service string

In its container.

volume string

In the volume, from its root.

path string

From the root. Empty = "/": the whole root.

DatabaseDump message

A database project's dump: Postgres's in its custom format, MariaDB's as SQL, Valkey's .rdb.

project_id string
database string

Postgres, MariaDB: the database to dump. Empty = "app", the apps'.

ProjectBusy message

Detail of an UNAVAILABLE error: an operation, or a short action, holds the project. The message says the same in words.

Empty = a short action, done while its caller waits: call again in a few seconds. Else wait for it with GetOperation, even while it is still starting; when it is your own operation_id, the first call with it is still starting it: call again.

Unspecified when operation_id is empty.

start_time timestamp

Since when it holds the project.

ProjectChanged message

Detail of an ABORTED error: base_deploy_id is not the current deploy: the project was deployed since you read it. Read it again (Project.deploy_id) and redo your change on its files.

No fields.

MachineUnreachable message

Detail of an UNAVAILABLE error: the machine does not answer now, as while it restarts. Call again later.

since_time timestamp

Since when Pethost has not reached it, once that is over 3 minutes: then the person was told (Machine.alert_channels). Absent = not known yet.

DatabaseLinkRefusal message

Detail of a FAILED_PRECONDITION error from LinkDatabase or CreateDatabase: a project of link cannot be linked to the database. Nothing changed.

project_id string

The first one refused.

service string

SERVICE_NAME_TAKEN: its service.

CreateProject's link_databases: the database refused, of those it names.

DatabaseLinkRefusalReason enum

DatabaseSizeRefusal message

Detail of a FAILED_PRECONDITION error from RunProjectAction.set_database_size: the database cannot take that size now. Nothing changed.

data_bytes uint64

DATA_TOO_LARGE: the Valkey's data in memory.

DATA_TOO_LARGE: what the size keeps, its maxmemory: 70 % of it.

volume string

VOLUME_MOVED: the volume its data is in.

DatabaseSizeRefusalReason enum

A Valkey whose data is more than the size keeps: take a larger size, or delete data first.

A Valkey that does not answer now, asked to shrink: how much it holds is unknown, so try again once it runs. A larger size is never refused so: a Valkey its limit keeps stopping can be given more.

Its data is in another volume (volume) than data, which the file the size writes keeps it in, so the database would start without it: change the size in its compose.yaml instead.

NoMachine message

Detail of a FAILED_PRECONDITION error: there is no machine to run projects on yet, since the caller has no workspace, or the workspace's machine is being prepared.

url string

Where the person goes on in the browser: for NO_PLAN the page they pay at, for BEING_PREPARED the workspace's page, which says it is. An MCP tool leaves it out.

BEING_PREPARED: the workspace. Empty for NO_PLAN.

PaymentOverdue message

Detail of a FAILED_PRECONDITION error: the workspace's last payment failed, and it stayed unpaid past the day its projects were to stop. Its machine is suspended, with every project on it stopped, and every call on the workspace is refused until it is paid, which its owner does in the workspace's settings in the panel. Still unpaid at end_time, it ends: its machine is deleted with every project on it, and its backups are kept for 30 days.

end_time timestamp
url string

Where its owner pays, in the browser: the workspace's settings in the panel. An MCP tool leaves it out.

NoMachineReason enum

The person has not chosen and paid for a plan: they do it at url.

The plan is paid and a machine is being prepared for the workspace: Pethost emails the person when it is ready. Call again later.

WorkspaceChoice message

Detail of an error that needs workspace: FAILED_PRECONDITION when the call named none and the caller has several, INVALID_ARGUMENT when it named none of theirs. Name one of these, by what the person asked for: a project that exists is in those of holding_project; for something new, ask the person, showing each one's size and what is free.

By name, at most 20: ListWorkspaces lists all.

total uint32

The workspaces the call may act on (this token's), in all.

holding_project array of string

The call names a project: the workspaces that have a project of that id, by workspace_id.

WorkspaceNotGranted message

Detail of a PERMISSION_DENIED error: the account has the workspace workspace named (or the connection is pinned to), but the person has not let this token reach it; or the call named none and the token reaches none of the account's workspaces.

The workspace it may not reach: the one named, else the account's only one. Empty = the call named none and the account has several.

url string

The panel's page where the person lets the token reach it.

ProjectMoved message

Detail of a FAILED_PRECONDITION error: the project moved to another workspace (MoveProject). Call there, naming it as workspace; ids of operations and snapshots from before stay behind.

project_id string

Where the move took it, which answers for it as it is now.

move_time timestamp

TerminalSize message

columns uint32
rows uint32