Pethost for Python

The Python SDK for Pethost, hosting for Docker Compose projects on a machine of your own. It has the 13 calls of Pethost's API, the ones an agent has through its MCP server: read the machine and its projects, deploy, read logs and HTTP requests, run commands, move files. Everything is typed, there is a synchronous client and an asyncio one, and the whole package is generated from the API's definition, so its methods, its fields and their documentation are the API's own.

Install

pip install pethost

Python 3.10 or newer. With uv: uv add pethost.

A token

The SDK signs in with an API token. Make one in the panel's Settings, under "API tokens", and give it to the SDK in the environment variable PETHOST_TOKEN, or as the client's first argument. A token acts as you: keep it out of your code and your repository.

A first program

It reads the machine and its projects, then deploys to the project notes by writing one file, /hello.txt.

from pethost import FileChange, Pethost

with Pethost() as pethost:  # The token: PETHOST_TOKEN.
    answer = pethost.get_machine()
    machine = answer.machine
    if machine is None:
        raise SystemExit("the answer has no machine")

    print(machine.hostname)
    for project in answer.projects:
        print(project.project_id)

    deployed = pethost.deploy_project(
        "notes",
        files=[FileChange(path="/hello.txt", text="Hello from the Pethost SDK\n")],
    )
    for violation in deployed.violations:  # The file was refused: nothing was deployed.
        print(violation.location, violation.violation_message)

    if deployed.operation is not None:
        print(deployed.operation.status.name)
    if deployed.project is not None:  # The project as it is once the deploy ended.
        print(deployed.project.url)

AsyncPethost has the same methods for asyncio:

import asyncio

from pethost import AsyncPethost


async def main() -> None:
    async with AsyncPethost() as pethost:
        print(await pethost.get_machine())


asyncio.run(main())

Methods

A read-only call changes nothing; a destructive one may delete or overwrite something. A request's fields are its method's keyword arguments, a message is a frozen dataclass of the same name, and each docstring is the API's own description: help(Pethost) and your editor show it. What the API calls absent is None where a type allows None, and the zero value anywhere else.

Errors

A failed call raises a PethostError, and its class is the code: CanceledError, UnknownError, InvalidArgumentError, DeadlineExceededError, NotFoundError, AlreadyExistsError, PermissionDeniedError, ResourceExhaustedError, FailedPreconditionError, AbortedError, OutOfRangeError, UnimplementedError, InternalError, UnavailableError, DataLossError, UnauthenticatedError. error.message is prose for people. What a program branches on, beside the class, is error.detail: ProjectBusy, ProjectChanged, MachineUnreachable, NoMachine, or None.

from pethost import NotFoundError, Pethost, PethostError

with Pethost() as pethost:
    try:
        project = pethost.get_project("notes").project
    except NotFoundError as error:
        print(error.message)  # No such project: the message lists the ones there are.
    except PethostError as error:  # Any other code.
        print(type(error).__name__, error.message, error.detail)

A wrong argument the SDK sees itself, such as two members of one oneof, is Python's own TypeError, ValueError or OverflowError, raised before anything is sent.

Links

• The API's reference: every call, message and field.
• The panel: your machine, your projects and your API tokens.
• pethost.dev: what Pethost is and what it costs.

Docker Compose hosting at one flat price

Pethost is managed hosting for Docker Compose projects. A subscription rents one virtual machine that only your account uses. Pethost's software on it deploys your projects, gives them HTTPS addresses, keeps their request logs and backs them up every night. You run it through your agent or from a web panel: both show the same projects, logs and requests.

• A machine of your own: nobody else's projects on it. No cold starts, nothing sleeps. Security updates install themselves.
• HTTPS addresses: anything.yourname.pethost.app at once, or your own domain with one DNS record. Certificates renew themselves. A password page in front of the whole site: one sentence to your agent.
• Deploys from GitHub: every push deploys itself, and an earlier commit is one step back.
• Request logs: every request with its status and time, the busiest paths and the error rate, kept for 30 days.
• Nightly backups: encrypted, stored off the machine, kept for 14 days.
• SSH and SFTP into any container, and a terminal in the panel.
• Docker Compose, as written: a project is a Compose file, and the same file runs anywhere else Docker does. A database is one more service in it, at no extra cost.
• In the EU: your data lives on your machine, and requests to your sites go straight to it, never through our panel.

Pricing. Starter is €9.99 a month for 2 vCPU, 3 GB of memory and 30 GB of SSD. Grow is €17.99 for 4 vCPU, 6 GB and 60 GB. Prices are without VAT. As many projects, containers and databases as fit: nothing is metered, and nothing is billed on top. There is no free tier. See the plans.

Who it is for. Solo developers and early startups who host several projects, bots or small apps and want one fixed monthly bill, and people who build with an AI agent and want it to deploy and run what it wrote. It is not for large teams whose applications need several regions or autoscaling: the machine is the limit.

How Pethost compares

About Pethost has each comparison in full, with prices.

Questions

Which AI agents does Pethost work with? Almost any agent that supports skills and MCP. The ones we tested ourselves: Claude Code, Codex, Cursor, ChatGPT, Gemini CLI, OpenClaw, Hermes and Pi.

What can I deploy? Anything that runs in Docker: web apps, APIs, bots, workers, databases. No Dockerfile? With the plugin installed, your agent knows the details and writes it for you.

Do I need an agent? No. The web panel does the same, and shows the same projects, logs and requests.

Can I use my own domain? Yes. One DNS record, and the certificate comes by itself.

Is there a free tier? No: €9.99 rents a real machine, so nothing sleeps. Cancel any time: refunds and cancellation has the rules.