--- name: host0 description: > host0 lets agents publish websites and apps to live URLs in seconds. Publish a folder and get a live URL at {slug}.host0.app — private by default, open to anyone with the link (unlisted) or public on the web on request. Apps can also declare record collections in an h0.json and get a shared database on their own origin, with no server code. Use when asked to "publish this", "deploy this", "host this", "put this online", "deploy to host0", "make this public", "give me a link", "share this site with someone", "roll back the last deploy", or to build a small team tool (todo list, tracker, sign-up sheet) several people use together. --- # host0 host0 hosts whatever your agent created — HTML, sites, apps with a shared database, Markdown, PDFs — at a link you can share, as easily as sharing a Google Doc. Works with any agent. The core primitive is an **app**: publish any file or folder — a directory of static files, or one file on its own that opens in a browser (a PDF, an image, a single HTML page, video, audio, Markdown, CSV, text; an archive or another download-only type is rejected — extract a zip and publish the folder) — and get a live URL at `https://{slug}.host0.app/` (local dev: `http://{slug}.localhost:3000/`). Every app is **private by default** — only the owner (signed in to host0) and people invited by email can open it. Opening it to anyone with the URL (no sign-in; unlisted and never indexed) is opt-in: `--visibility link`. `--visibility public` goes further — public on the web, search engines may index it — and is only for things the user wants found in search. A new app's URL is random (`k3x9q2m7ta.host0.app`); rename it to something readable (`team-todo.host0.app`) when the user wants a nicer link — see "Rename the URL" below. An app can also hold **shared data**: declare record collections in an `h0.json` and its frontend gets a database on its own origin, no server code involved. See "Shared data" below — that's what turns a page into a tool a team uses together. ## Current docs Full docs live at **https://host0.ai/docs** — read them when the user asks how something works, what's possible, or before telling them a feature is unsupported. The API also describes itself. The machine-readable index: ```bash curl -sS {base}/api/v1 ``` It returns the current endpoint list, file caps, and the platform contract (what host0 serves today). Send the API key (`-H "authorization: bearer $HOST0_API_KEY"`) and `limits` and `plan` are the user's own — caps depend on the account's plan; without a key you get the defaults for a new account. `GET {base}/api/v1/account` adds what the account has used this month. If this skill text and live API behavior disagree, trust the live API. To install or update this skill: `npx skills add host0-ai/skills` (any agent the [skills CLI](https://skills.sh) supports; source: https://github.com/host0-ai/skills), or `npx skills add https://host0.ai` to install it straight from host0 (that install doesn't keep the executable bit: run `chmod +x scripts/publish.sh` afterwards), or with no Node `curl -fsSL https://host0.ai/install.sh | bash` (no sudo; it won't replace a copy that differs unless you pass `--force`, so ask the user first), or fetch two files: `https://host0.ai/skill.md` → save as `SKILL.md`, and `https://host0.ai/publish.sh` → save as `scripts/publish.sh` next to it, then `chmod +x scripts/publish.sh`. The script's URL is `/publish.sh` — there's no `/scripts/` in it. ## Which tool: the host0 CLI or publish.sh Two tools do the same job. Decide once, at the start: 1. Run `node -v`. If it prints v18.18 or newer and `npx` exists, use the **host0 CLI**: `npx -y @host0/cli@latest ` (written `host0 ` below). Nothing to install. 2. Otherwise — no Node, an older one, or the first `npx` call can't fetch the package from the npm registry (some sandboxes block it) — use **`./scripts/publish.sh`**, exactly as this skill describes. Don't retry npm; switch straight away. claude.ai sandboxes usually have Node; if `npx` fails there, fall back to `publish.sh` at once. Both read and write the same `~/.host0/credentials`, `~/.host0/device.json` and `.host0/state.json`, and print the same stdout URL and `publish_result.*` / `pull_result.*` / `login_result.*` lines with the same exit codes (`0` ok · `1` error · `3` waiting for the user's approval). So every rule below keyed on those lines holds for both, and a folder published with one updates with the other. The examples use `publish.sh`; translate them with: | publish.sh | host0 CLI | | --- | --- | | `publish.sh {dir\|file} [flags]` | `host0 deploy {dir\|file} [same flags]` | | `publish.sh --login` | `host0 login` | | `publish.sh --login-wait` | `host0 login --wait` | | `--wait {seconds}` | `--timeout {seconds}` | | `publish.sh --pull --slug {slug} [dir]` | `host0 pull {slug} [dir]` | The CLI also manages apps, so you don't need raw curl for these: `host0 ls`, `inspect {app}`, `versions {app}`, `rollback {app} {n}`, `visibility {app} private|link|public`, `rename {app} [--slug s] [--name n]`, `share {app} {email…}` / `unshare {app} {email}`, `rm {app} --yes`, `analytics {app} [--period 7d]`, `records {app} [collection] [--export]`, `whoami`, `logout`, and `api {path} [-X METHOD] [-d json]` for anything else under `/api/v1`. `{app}` is a slug or an app id; `--json` prints the API's JSON body. The curl calls below are for the `publish.sh` path. ## Requirements - **CLI path:** Node 18.18+ with `npx`, and outbound HTTPS to the npm registry for the first run. - **publish.sh path:** `curl`, `jq` (the script dies with a clear message if either is missing); bundled helper `./scripts/publish.sh`. - An API key, from `$HOST0_API_KEY` or `~/.host0/credentials`. With none, a deploy starts a **device login** for you — the user approves a link + code in their own browser (see "Getting an API key") - Network: outbound HTTPS to **`host0.ai`** (the API) and **`host0.app`** (uploads and the live apps). In a sandbox with an egress allowlist, if a request fails with `SSL_ERROR_SYSCALL`, a proxy error, or a connection refused/reset every time, tell the user which domain to allow — don't loop on it. - Transient failures happen: some cloud sandboxes see occasional connection resets / `SSL_ERROR_SYSCALL` / connect timeouts reaching `host0.ai`. The CLI and `publish.sh` retry those by themselves (you'll see `host0: network hiccup … retrying 2/4` on stderr) — just let them run. If you're calling the API with raw curl, retry the request yourself; for GETs and the device-login poll you can add `--retry 3 --retry-all-errors`, never for POSTs that create something. ## Publish an app ```bash ./scripts/publish.sh {dir} [--name "my app"] ./scripts/publish.sh {file} [--name "my app"] # one file: a pdf, an image, a page ``` Prints the live URL on stdout (e.g. `https://k3x9q2m7ta.host0.app/` — new apps get a random slug; `--name` is only the display name). Add `--client {your-agent}` (e.g. `--client claude-ai`) when you're not Claude Code, Codex, Cursor or Gemini CLI — both tools detect those themselves. It only labels deploy stats. With the CLI: `host0 deploy {dir|file} [--name "my app"]` — same flags, same output. Under the hood this is a three-step flow: manifest → upload files → finalize. The app is not live until finalize succeeds. **File structure:** `index.html` must sit at the root of the directory you publish — the directory's contents become the site root. Publish `my-site/` where `my-site/index.html` exists, not a parent folder containing `my-site/`. **Many pages:** every file keeps its path. `/about` serves `about.html` or `about/index.html` (a folder index gets its trailing slash: `/docs` → `/docs/`), and `/docs/guide` serves `docs/guide.html`, so links can use either form. A `404.html` at the root is served for missing pages. Without one, a missing page path serves `index.html`, so client-side routes in a single-page app deep-link. **A single file:** pass the file itself (`./scripts/publish.sh report.pdf`) — no `index.html` needed. The app's root URL serves that file (in a browser tab it opens in host0's file viewer — see the badge note below; `?download` gets the original, and PDFs keep range support for large ones), and it's also reachable at `/{filename}`. Use this whenever the user just wants to share one document or image. **Deploy built output, not source:** if the project uses a build step (React/Vite/Next export, .ts/.tsx/.vue/.svelte), build first and publish the output directory (`dist/`, `build/`, `out/`). Never publish `node_modules/`, `package.json`, or secrets (`.env`, key files) — the API rejects server code and secrets with an actionable message. **The "Hosted on host0" badge:** apps without a paid plan — during the beta, on the free plan, or in a trial — get a small "Hosted on host0" badge on every HTML page, and you don't need to design around it. It sits bottom-right (about 28px tall, 12px from the edges) and moves by itself when one of the page's own buttons or links would be under it: to the first free corner (bottom-left, top-right, top-left), or to a small icon bottom-right if all four are taken. To choose its corner yourself, add `` to the page (`bottom-right`, `bottom-left`, `top-right` or `top-left`; it then stays there). Don't try to hide it. The moving is done by a same-origin script (`/.h0/b.js`): if you set a Content-Security-Policy, allow `'self'` in `script-src`, or the badge stays bottom-right. A PDF, image, video, audio or text file (`.txt`, `.csv`, `.md`, `.json`) opened directly in a browser tab opens in a host0 file viewer: the file fills the window, with a slim bar under it (file name, Download, "Hosted on host0") that never covers it. The raw file is still served to ``/`