Building sites with MicroHost

This page is the map. The material that used to live here has been split into focused pages; the developer index lists them all.

I want to...

Goal	Page
Understand what happens to a request	How a site works
Ship a first site, then one with a database	Quickstart
Know what `Request`, `Response`, `Headers`, `URL` offer, and what is missing	Handler API
Use the database, storage, secrets, mail or outbound HTTPS	Context (`ctx`)
Get object rows, table objects and paging	Database SDK
Add logins and sessions	Auth and sessions, guide
Choose and switch SDK modules	SDK modules
Map URLs to handlers, use `/posts/:slug`	Routing
Organize files, imports and what is public	Site layout
Declare permissions, routes, limits	Manifest or the config script
Create and evolve tables	Migrations
Build admin screens for my content	Admin extensions
Understand a status code or an error code	Limits and errors
Deploy, stage, roll back	Deploying
Test before deploying	Testing sites
See complete example sites	Examples
Know what works on which engine	Engine differences and status

Two kinds of JavaScript

Location	Runs in	Can use
`public/app.js`, loaded by your HTML	The visitor's browser	The DOM and the browser's `fetch`.
`api/*.js` and other handler files outside `public/`	A MicroHost engine (QuickJS)	The Handler API and the granted capabilities.

MicroHost does not execute JavaScript embedded in HTML on the server, and does not run PHP, Python or server-side TypeScript. Compile TypeScript before you deploy. A framework's Node.js server cannot run unchanged as a handler; a framework's static output can go in public/.

Capabilities and live grants

A manifest requests capabilities; an administrator grants them per site; the effective access is the intersection of the active release's request, the current grant and resource availability (details in Manifest).

Who can grant what:

Capability	Super Admin	Workspace Admin or Site admin	Developer	Editor
Site database, storage, secrets	grant and revoke	grant and revoke in their workspace	grant and revoke on sites they develop	read status
Workspace-database switch	grant and revoke (a catalog grant per database is still required)	grant and revoke	grant and revoke the switch only	read status
Mail	grant and revoke	revoke only	read status	read status
External HTTP hosts and public egress	grant and revoke	revoke or disable only	read status	read status
Workspace capability template (copied into new sites)	set	read	read	no access

Grants live under Settings, Permissions of the site, or at GET/PATCH /admin/api/v1/sites/{id}/capabilities (the PATCH carries the current policy_version; a stale one is refused).
The template is applied only when a site is created, defaults to deny, and can never enable mail or egress. Existing sites are never changed by a template edit.
Missing grants do not stop a deploy or an activation. They produce a visible reason and leave the capability absent (ctx.db is undefined, and the runtime code is capability_denied).
Grant changes apply to the next broker call, also inside a running execution; revoking is enforced without a grace period. An outbound request already handed to a provider cannot be recalled, and queued mail is re-checked at delivery time.
A grant does not raise a quota, supply a secret value, or activate an inactive release. Never put secret values in a manifest.
Site capability grants are separate from the named workspace database catalog grants and from quotas.

Current implementation boundaries

The code is ahead of some older pages and behind some design documents. Every reference page marks partial features with a Status note, and Engine differences and status lists them in one table. The most important ones: sessions are Wasm-only, static.root and static.spaFallback are not applied, there is no local handler dev server and no release preview, mail delivery is not configured in the production CLI, and the production composition has not been run as an integrated deployment (see the progress log).