{
  "schema": "leumas.docs.page/1",
  "id": "how-to:hosting-a-website",
  "slug": "how-to/hosting-a-website",
  "kind": "pages",
  "bucket": "how-to",
  "title": "Build-knowledge — hosting a website: on Leumas, or on your own machine",
  "name": "hosting a website",
  "eyebrow": "build knowledge",
  "chip": null,
  "summary": "Both lanes use the same site records, the same view modes and the same site types. Nothing you build in one is stranded in the other.",
  "keywords": [
    "hosting",
    "publish a website",
    "custom domain",
    "self hosting",
    "leumas studio",
    "leumas hosting",
    "how to host a website on leumas",
    "subdomain"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# Build-knowledge — hosting a website: on Leumas, or on your own machine\n\n> Two lanes, and the choice is not about capability — the same Imperium serves both. It is about\n> **who runs the server**. Let Leumas run it and you publish and walk away; run it yourself and you\n> own the domain, the box and the uptime.\n\n## Which lane\n\n| | Leumas hosts it | You host it |\n|---|---|---|\n| Where it serves from | a name under `leumas.tech`, or your own domain pointed at it | your machine, your domain |\n| What you install | nothing — Studio runs in the browser | Leumas Studio, plus a serving worker |\n| Who handles TLS and DNS | Leumas, for its own names | you |\n| Cost | building is free; publishing needs a plan | free |\n| Good for | getting something public today | keeping the data and the box yours |\n\nBoth lanes use the same site records, the same view modes and the same site types. Nothing you build\nin one is stranded in the other.\n\n## Lane 1 — Leumas hosts it\n\n### Make the site\n\nIn Studio, **New Website** walks five steps and never shows you JSON:\n\n1. **Start** — a template, a kind of site, or a copy of one of yours.\n2. **Name** — the site name and the subdomain, checked live against the real claim check.\n3. **Look** — a theme preset beside a live preview.\n4. **Content** — the mode's own form, beside the same preview.\n5. **Launch** — save as a draft, or publish immediately.\n\nUploading a build you already have is a shorter lane — Start, Name, Launch — because a built folder\nhas no theme or content payload to fill in. The files go up afterwards from the Files tab.\n\nOver HTTP the same thing is two calls:\n\n```\nPOST /api/hosting/sites   { subdomain, appName, mode, data }   → 201\nPOST /api/hosting/sites/<id>/publish                           → 200\n```\n\n**The site id IS the subdomain.** A new site is created as a draft with no domains attached.\n\n### Two things about subdomains that catch people\n\n**A subdomain is permanent.** There is no rename; create a new site to change it. Studio says so on\nthe Domains tab before you commit.\n\n**\"Unavailable\" does not say why, on purpose.** One message covers five different reasons — reserved,\nalready taken, colliding with a platform config, structurally invalid, or empty once normalised. It\nwill not confirm whether a particular name is taken by someone else.\n\nReserved names include `www`, `api`, `app`, `admin`, `studio`, `assets`, `cdn`, `mail`, `login`,\n`auth`, `db`, `mcp`, `library`, `index`, `social`, `downloads`, `hidden` and `ops`. One of those has a\nnon-obvious reason worth knowing: **`downloads` is routed away before the worker ever sees it**, so a\nsite claiming it would be authored, published, listed in your account — and permanently unreachable.\n\n### Publishing is the line, not building\n\nEvery account can create a website and preview it. The free floor allows **one** site and **zero**\npublished ones, so the thing a plan buys is a public address. Two different numbers, and confusing\nthem is the usual support question: how many you may **own**, and how many may be **live at once**.\n\nThe refusal is a `402` naming the quota, not a `403`, and it arrives at publish time rather than at\ncreate time. You can also ask before you try — the hosting API reports your limit, how many you have\nused and how many remain, so a refusal is predictable instead of a surprise.\n\n[warning] **Entitlement is re-checked on every request and fails closed.** If a plan lapses, the site swaps\nto a suspension page on the next page load — not at some renewal boundary. Nothing is deleted.\n\n### Your own domain\n\nTwo mechanisms, one state machine, and the same TXT record shape.\n\n**One hostname.** Add the domain to the site, publish a `TXT` record at `_leumas-verify.<your-host>`\nwith the token Studio shows you, then press Check now. A domain moves `pending → verified` when the\nrecord is found; only `verified` and `live` are ever served.\n\n**A whole domain.** Prove it **once** as a zone, then bind as many hostnames under it as you like\nwithout touching DNS again. Studio's Setup tab is a three-step checklist that ticks itself: prove\nownership, send traffic here, put a website on it.\n\nFacts that save an afternoon:\n\n- **Proving and pointing are separate steps.** A proved domain with no traffic pointed at it still\n  serves nothing. That is the third step, and it is the one people stop before.\n- **Point the wildcard too.** Whichever recipe you use — a tunnel, a CNAME, or an A record — add\n  `*.your-domain` alongside the apex. This is the single most commonly missed line.\n- **A transient DNS failure does not take a verified domain down.** Only a domain that was never\n  verified moves to `failed`.\n- **Bindings are exact.** An unbound hostname under a proved domain returns 404 rather than falling\n  back to the apex, because a fallback is how a typo becomes someone else's traffic.\n- **Longest verified suffix wins**, so a delegated subdomain can be a zone of its own.\n- Caps: 25 domains per site, 10 zones per account, 200 websites per domain.\n\n## Lane 2 — you host it\n\n### Install Studio\n\nStudio is a free desktop app, downloadable from `leumas.tech/downloads`. **It is Windows x64 only** —\nthere is no Mac or Linux build, and the download page says so rather than offering one that does not\nexist.\n\nOn first launch it does not show you the app. It checks whether the install has a licence and whether\nit has any accounts, and shows a first-run wizard until both are answered — see\n[accounts](accounts.md) for the two shapes that wizard takes.\n\nYour data stays on your machine: a local database in your user profile, migrated on first launch. The\nStudio API **binds to loopback**, so nothing on your network reaches it unless you deliberately put\nsomething in front of it. The licence is verified offline against a signed token with a grace period,\nso an unreachable platform never bricks the install.\n\n### Serving is a second process, and this trips people\n\n**The Studio desktop app cannot serve your websites to the internet.** It is loopback-only and it is\nthe *authoring* side. Serving is a separate worker you run, pointed at the same store.\n\nWhat has to be true:\n\n1. **Scaffold the worker.** A `create-imperium` command writes its configuration — the port, the base\n   domain, the data and storage roots, and a preview secret. It is idempotent.\n2. **A wildcard DNS record.** `*.your-domain` and the apex must both reach the worker.\n3. **Something terminating TLS in front of it.** A ready-made reverse-proxy configuration ships with\n   the worker: one wildcard site block, a health check, and — importantly — forwarding the visitor's\n   original `Host` header, because that header is how a site is identified.\n4. **The same preview secret on every worker** if you run more than one, or draft preview links fail\n   to verify.\n\n**The edge needs no per-site routes, ever.** Each worker resolves the incoming hostname to a site\nitself. That is the whole design: add the wildcard once and never touch the proxy again when you add\na website.\n\nWorkers cache resolves per process, so a freshly published change appears within a few seconds rather\nthan instantly. When probing after a publish, wait that out before concluding something is wrong.\n\n## Site types: where the bytes come from\n\nEvery site answers one question — **who produces the page?** The live list, with the fields each one\ntakes and which are operator-only, is at\n[docs.leumas.tech/modes](https://docs.leumas.tech/modes), generated from the registry the serving\ncode itself reads.\n\nThe short version:\n\n- **Imperium renders it** — you pick a view mode and fill in its form. No build, no deploy.\n- **You uploaded it** — a built folder, served from this site's own storage. Upload and deploy are\n  deliberately two actions: uploading is not publishing.\n- **You run it** — Imperium forwards to an app you keep running. It becomes *your* site on *your*\n  origin, with your TLS and your cookies, which is why this is a proxy and not an iframe.\n- **Somewhere else entirely** — a redirect.\n\nTwo of the six reach the host beyond that site's own data and are **operator-only**: an ordinary\nmember is refused when saving, not when serving. If you are on the Leumas-hosted lane and want to\nserve a folder from disk or have Imperium run a program, that is a self-hosted install.\n\n## What a site is made of\n\nOne website is one record, edited across four groups of tabs in Studio: **Build** (the home page,\nother pages, hand-written HTML, appearance), **Reach** (SEO, domains, analytics, and orders if it\nsells anything), **Connect** (what it serves, uploaded files, an app you run, an MCP tool server, the\nassistant widget), and **Advanced** (the raw config, per-site edge rules, and the dangerous\noperations).\n\n[critical] **Home and every other page are different lanes**, and this is the most common integration\nmistake: the home page is the site's own mode and data and needs an explicit save, while every other\npage is a route that persists on write. Sending routes to the site update endpoint is refused with a\nmessage telling you to use the route lane.\n\nPublishing re-validates the site **and every page**. A failure names an invalid *page*, which is\nusually not the one you were editing.\n\n## Related\n\n- [accounts](accounts.md) — creating an account, and which door your install opens.\n- [FAQ](faq.md) — the short answers.\n- [Imperium hosting](imperium-hosting.md) — the architecture underneath all of this.\n",
  "source": {
    "path": "shared/services/knowledge/build-knowledge/hosting-a-website.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 9684,
    "hash": "ca72b163f9dcb347e5c5b1683bd18a23cb8bf214"
  },
  "urls": {
    "html": "/p/how-to/hosting-a-website",
    "json": "/docs/how-to/hosting-a-website.json",
    "md": "/docs/how-to/hosting-a-website.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}