| name | openhost-context |
| description | Deploy and debug apps on OpenHost, a platform for self-hosting apps. Use when working with the `oh` CLI, deploying or reloading an app on an OpenHost zone, or building an openhost app. |
OpenHost
OpenHost is a platform for self-hosting apps. Each app runs in its own
container; the OpenHost router terminates TLS, handles auth, and
proxies requests to apps by subdomain (https://{app_name}.{zone_domain}/).
You interact with a zone through the oh CLI, which injects auth for you.
Prefer oh over raw HTTP requests so you never have to handle tokens by hand.
First time: install and log in
If oh isn't installed:
uv tool install "oh @ git+https://github.com/imbue-openhost/openhost.git#subdirectory=compute_space_cli"
Then the user logs in (this is interactive — ask them to run it):
oh instance login
A zone you've logged into is called an instance. List configured
instances and the URL each is reachable at (if none are listed, the user needs to do oh instance login)
oh instance list
Targeting an instance
Most users have one instance; some have several. Ask the user which
instance to use, and only touch that one, if multiple are available — don't deploy to, reload, or
otherwise modify instances you weren't asked to.
Pass --instance <name> to target a specific one (works on any subcommand):
oh status --instance my-zone
oh app list --instance my-zone
If a single default instance is configured, --instance can be omitted.
Safety
Zones serve the public internet. Be careful with anything that could open
unauthenticated access:
- By default every route requires the zone owner to be logged in. Routes
listed in
public_paths in openhost.toml are reachable by anyone —
only expose paths that are meant to be public.
- Don't put API tokens in code, commits, or anything that might be pushed.
oh already injects auth; reach for a raw token only if truly necessary
(oh instance token --instance <name>), and keep it out of the repo.
Deploy / update workflow
Deploy an app from a git repo URL (public, or private with auth):
oh app deploy https://github.com/you/my-app --name my-app --wait --instance my-zone
You can deploy from a branch with https://github.com/you/my-app@branch_name.
The router reads openhost.toml from the repo, builds the image from the
app's Dockerfile, and starts routing to it.
The common iterate loop — commit + push your changes, then pull & rebuild
on the zone:
git commit -am "..." && git push
oh app reload my-app --update --wait --instance my-zone
oh app logs my-app --instance my-zone
Other app commands: oh app status|list|stop|rename|remove. Run
oh --help (or oh app --help) for the current, complete list.
Debugging
- Logs:
oh app logs my-app --follow --instance my-zone (app logs);
oh logs --instance my-zone (zone/router logs).
- Shell on the zone:
oh instance ssh --instance my-zone.
- Authenticated HTTP:
oh curl https://my-app.<zone-domain>/some/path
— runs curl with the user's API token token injected, so it behaves like an
owner-logged-in request.
- Test a page in a browser the way a logged-in owner sees it: drive it
with Playwright and inject the API token as an
Authorization: Bearer <token> header. This matches the behavior of a request carrying the
owner's login cookies. Get a token with oh instance token (handle it
carefully — see Safety).
Building a new app
Start from the template and build on top of it:
github.com/imbue-openhost/app-template
An app is any OCI container reachable over HTTP. It needs an openhost.toml
manifest and a Dockerfile at the repo root; it should listen on
0.0.0.0:<port> matching runtime.container.port in the manifest.
For the full app-authoring reference (manifest fields, the runtime
contract, injected env vars, data storage, auth, cross-app services):
- Read the manual on your own zone at
https://<zone-domain>/docs/ — it
always matches the OpenHost version you're running.
- Or read the source docs at
github.com/imbue-openhost/openhost/tree/main/docs/src (start with
creating_an_app.md and manifest_spec.md).
- You can also always clone `github.com/imbue-openhost/openhost
To reference OpenHost's code and docs directly, you can always just clone the openhost repo locally:
git clone https://github.com/imbue-openhost/openhost.git
