Build-knowledge — hosting a website: on Leumas, or on your own machine

Two lanes, and the choice is not about capability — the same Imperium serves both. It is about who runs the server. Let Leumas run it and you publish and walk away; run it yourself and you own the domain, the box and the uptime.

Which lane

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.

Lane 1 — Leumas hosts it

Make the site

In Studio, New Website walks five steps and never shows you JSON:

1. Start — a template, a kind of site, or a copy of one of yours.
2. Name — the site name and the subdomain, checked live against the real claim check.
3. Look — a theme preset beside a live preview.
4. Content — the mode's own form, beside the same preview.
5. Launch — save as a draft, or publish immediately.

Uploading a build you already have is a shorter lane — Start, Name, Launch — because a built folder has no theme or content payload to fill in. The files go up afterwards from the Files tab.

Over HTTP the same thing is two calls:

POST /api/hosting/sites   { subdomain, appName, mode, data }   → 201
POST /api/hosting/sites/<id>/publish                           → 200

The site id IS the subdomain. A new site is created as a draft with no domains attached.

Two things about subdomains that catch people

A subdomain is permanent. There is no rename; create a new site to change it. Studio says so on the Domains tab before you commit.

"Unavailable" does not say why, on purpose. One message covers five different reasons — reserved, already taken, colliding with a platform config, structurally invalid, or empty once normalised. It will not confirm whether a particular name is taken by someone else.

Reserved names include www, api, app, admin, studio, assets, cdn, mail, login, auth, db, mcp, library, index, social, downloads, hidden and ops. One of those has a non-obvious reason worth knowing: downloads is routed away before the worker ever sees it, so a site claiming it would be authored, published, listed in your account — and permanently unreachable.

Publishing is the line, not building

Every account can create a website and preview it. The free floor allows one site and zero published ones, so the thing a plan buys is a public address. Two different numbers, and confusing them is the usual support question: how many you may own, and how many may be live at once.

The refusal is a 402 naming the quota, not a 403, and it arrives at publish time rather than at create time. You can also ask before you try — the hosting API reports your limit, how many you have used and how many remain, so a refusal is predictable instead of a surprise.

[warning] Entitlement is re-checked on every request and fails closed. If a plan lapses, the site swaps to a suspension page on the next page load — not at some renewal boundary. Nothing is deleted.

Your own domain

Two mechanisms, one state machine, and the same TXT record shape.

One hostname. Add the domain to the site, publish a TXT record at _leumas-verify.<your-host> with the token Studio shows you, then press Check now. A domain moves pending → verified when the record is found; only verified and live are ever served.

A whole domain. Prove it once as a zone, then bind as many hostnames under it as you like without touching DNS again. Studio's Setup tab is a three-step checklist that ticks itself: prove ownership, send traffic here, put a website on it.

Facts that save an afternoon:

• Proving and pointing are separate steps. A proved domain with no traffic pointed at it still

serves nothing. That is the third step, and it is the one people stop before.

• Point the wildcard too. Whichever recipe you use — a tunnel, a CNAME, or an A record — add

*.your-domain alongside the apex. This is the single most commonly missed line.

• A transient DNS failure does not take a verified domain down. Only a domain that was never

verified moves to failed.

• Bindings are exact. An unbound hostname under a proved domain returns 404 rather than falling

back to the apex, because a fallback is how a typo becomes someone else's traffic.

• Longest verified suffix wins, so a delegated subdomain can be a zone of its own.
• Caps: 25 domains per site, 10 zones per account, 200 websites per domain.

Lane 2 — you host it

Install Studio

Studio is a free desktop app, downloadable from leumas.tech/downloads. It is Windows x64 only — there is no Mac or Linux build, and the download page says so rather than offering one that does not exist.

On first launch it does not show you the app. It checks whether the install has a licence and whether it has any accounts, and shows a first-run wizard until both are answered — see accounts for the two shapes that wizard takes.

Your data stays on your machine: a local database in your user profile, migrated on first launch. The Studio API binds to loopback, so nothing on your network reaches it unless you deliberately put something in front of it. The licence is verified offline against a signed token with a grace period, so an unreachable platform never bricks the install.

Serving is a second process, and this trips people

The Studio desktop app cannot serve your websites to the internet. It is loopback-only and it is the authoring side. Serving is a separate worker you run, pointed at the same store.

What has to be true:

1. Scaffold the worker. A create-imperium command writes its configuration — the port, the base

domain, the data and storage roots, and a preview secret. It is idempotent.

1. A wildcard DNS record. *.your-domain and the apex must both reach the worker.
2. Something terminating TLS in front of it. A ready-made reverse-proxy configuration ships with

the worker: one wildcard site block, a health check, and — importantly — forwarding the visitor's original Host header, because that header is how a site is identified.

1. The same preview secret on every worker if you run more than one, or draft preview links fail

to verify.

The edge needs no per-site routes, ever. Each worker resolves the incoming hostname to a site itself. That is the whole design: add the wildcard once and never touch the proxy again when you add a website.

Workers cache resolves per process, so a freshly published change appears within a few seconds rather than instantly. When probing after a publish, wait that out before concluding something is wrong.

Site types: where the bytes come from

Every site answers one question — who produces the page? The live list, with the fields each one takes and which are operator-only, is at docs.leumas.tech/modes, generated from the registry the serving code itself reads.

The short version:

• Imperium renders it — you pick a view mode and fill in its form. No build, no deploy.
• You uploaded it — a built folder, served from this site's own storage. Upload and deploy are

deliberately two actions: uploading is not publishing.

• You run it — Imperium forwards to an app you keep running. It becomes your site on your

origin, with your TLS and your cookies, which is why this is a proxy and not an iframe.

• Somewhere else entirely — a redirect.

Two of the six reach the host beyond that site's own data and are operator-only: an ordinary member is refused when saving, not when serving. If you are on the Leumas-hosted lane and want to serve a folder from disk or have Imperium run a program, that is a self-hosted install.

What a site is made of

One website is one record, edited across four groups of tabs in Studio: Build (the home page, other pages, hand-written HTML, appearance), Reach (SEO, domains, analytics, and orders if it sells anything), Connect (what it serves, uploaded files, an app you run, an MCP tool server, the assistant widget), and Advanced (the raw config, per-site edge rules, and the dangerous operations).

[critical] Home and every other page are different lanes, and this is the most common integration mistake: the home page is the site's own mode and data and needs an explicit save, while every other page is a route that persists on write. Sending routes to the site update endpoint is refused with a message telling you to use the route lane.

Publishing re-validates the site and every page. A failure names an invalid page, which is usually not the one you were editing.

Related

• accounts — creating an account, and which door your install opens.
• FAQ — the short answers.
• Imperium hosting — the architecture underneath all of this.