---
name: hostan
description: Publish a file to a live public URL with Host An App — anonymous quick shares (one HTTP request, no account) or durable apps (a project with a SQLite backend, frontends, realtime rooms and payments) over the MCP server. Use when the user asks to publish, host, deploy, share, or send back a link for a page, document, diagram, data file, or small web app.
---

# Host An App

Zero-config hosting for things an assistant makes: send content, get a live
public URL. Two products:

- **Quick share** — one `POST` to the REST API, no account, no key. The URL
  self-destructs after 7 days. Use this by default for one-off pages.
- **Durable app** — a project with a persistent SQLite backend and one or
  more frontends, driven over the MCP server with a workspace credential
  (`Authorization: Bearer hstn_…`). Use when state must survive visits or
  the app needs a backend, realtime, sign-in or payments.

**This file is the shortcut. The complete contract is
`https://hostan.app/llms.txt`** (alias `/agents.md`; the MCP `read_docs`
tool returns it in-band). Read it before any non-trivial change: it defines
every field, limit, runtime and error code. Do not guess beyond this file.

## Quick share (REST, no key)

`content` is the only required field. Success is `201 Created` with a
`url` you can share; the page is live immediately.

```bash
curl -X POST https://api.hostan.app/api/v1/deploy \
  -H "Content-Type: application/json" \
  -d '{"type": "html", "name": "my-app",
       "content": "<!DOCTYPE html><html><body><h1>Hello, internet.</h1></body></html>"}'
```

Fields: `content` (required, UTF-8, under 1 MB), `type` (`html` default,
`markdown`, `mermaid`, `json`, `csv`), `name` (preferred slug), `title`,
`password`, `one_time` (self-destruct after the first visit). View at
`https://sites.hostan.app/<slug>`; raw source at `/<slug>.md|.txt|.json|.csv`.

Ship **one self-contained HTML file** (inline CSS/JS; external `https://`
resources are fine). There is no page console, so surface errors into the
DOM yourself if a page must be debuggable.

## Durable apps (MCP)

Connect an MCP client to `https://api.hostan.app/mcp`. Quick shares use the
`deploy_asset` tool; durable apps use, in order:

1. `manage_project` — `create {name, description?, ttl_seconds?|permanent?}`
   (default permanent). The response contains the authoritative project
   documentation inline.
2. `manage_backend` — `create {project_id, ddl}` provisions the project's
   single SQLite tier from gated `CREATE TABLE/INDEX/VIEW` + seed `INSERT`s.
   Later migrations go through the same tool with one additive statement.
3. `manage_frontend` — `create {project_id, type, content, requested_slug?,
   title?}` publishes a page. `get`/`update`/`delete`/`search`/`edits` and
   the revision commands manage it afterwards.

The credential never travels as a tool argument and never belongs in a
page. For durable apps, connect over **OAuth** (the recommended path —
your MCP client signs the user in and the consent page names the
workspaces it may act in); a headless/CLI client can paste a workspace
credential on the server entry instead (`Authorization: Bearer hstn_…`).
Quick shares need neither.

### Inside a published page, call only the injected runtimes

Pages run tokenless; the platform resolves the backend from the page's own
slug, so the browser never selects a database or holds a secret.

- `await hostan.db.op(name, params)` — one author-defined action (a single
  gated SELECT/INSERT/UPDATE/DELETE). Raw SQL is owner-only and never in a
  page.
- `const r = await hostan.fetch(name, {query, body})` — one author-defined
  https egress endpoint; `${SECRET}` placeholders in its headers resolve
  server-side from dashboard-held secrets.
- `hostan.auth.user()` / `login()` / `logout()` — managed Google sign-in.
  Actions may bind the reserved `:hostan_user_id` / `:hostan_user_email`.
- `hostan.ws.connect(roomID)` — ephemeral realtime relay (no history;
  reload authoritative state from `hostan.db` on `open`).
- `hostan.payments.checkout(price_id)` / `status()` — managed Stripe; always
  verify with `status()` on load.

Define actions/fetches with `manage_backend update`; test each with
`hostan.db.op` / `hostan.fetch` before relying on it. Never construct
database URLs, egress URLs, or embed workspace credentials or secrets in
page code.

## Limits and errors

Quick shares: under 1 MB per request, 7-day lifetime (or first visit with
`one_time`), 30 deploys/min per IP. Backends: 10 MB per database, 250
databases, 5000 active deployments. A capacity limit answers `503` with a
reason; retry later. Auth and validation failures name the fix.

## Reference

- `https://hostan.app/llms.txt` — full agent contract (also via MCP
  `read_docs`). Start here for anything not covered above.
- `https://api.hostan.app/api/v1/openapi.json` — machine-readable REST spec.
- `https://hostan.app/docs` — human documentation.