Dokumentasjon
Alt du trenger for å publisere.
Ny her? Start med den enkle guiden. Skriver du kode selv, finner du alle detaljene i den tekniske referansen.
Teknisk referanse
Dette trenger Hosait fra repoet ditt
Koble til et repo – fra GitHub, GitLab, Bitbucket eller Azure DevOps – så finner Hosait ut hvordan det skal kjøres, bygger det isolert og serverer det på din egen adresse. Her står alt plattformen forutsetter – så verken du eller KI-kodeverktøyet i repoet ditt trenger å gjette.
Getting started
- 1
Koble til stedet der koden din ligger — GitHub, GitLab, Bitbucket eller Azure DevOps — under Konto → Tilkoblinger, eller i veiviseren. Hosait ber om lesetilgang til repoene dine og tillatelse til å legge til push-webhooken, ikke noe mer.
- 2
Start a new project, pick the repository and the branch. Hosait inspects it before anything is built and tells you what it found.
- 3
Fill in the required variables. They are read from your repo; for secret-shaped ones there is a Generate button so you never have to make one by hand.
- 4
Publish. From then on, every push to that branch deploys automatically, and the project page shows each deploy with its commit, its log and its outcome.
Code providers
What Hosait detects
Without any configuration, Hosait looks at the repository and picks one of three ways to run it. A hosait.json file overrides the guess.
static
An index.html at the root or in a common output folder. If there is a build script, it is run first in an isolated container and the output is served.
node
A package.json with a start script and no static output. Built, then run as a container; the package manager is read from the lockfile.
compose
A docker-compose file. The whole stack is started — database, workers, one-shot jobs and all — and one service is chosen as the web front.
APIs: Hosait publishes any HTTP service. That can be a Node server with a start script, or a project in any language through a Dockerfile and a docker-compose.yml. An API without a front page works: if / answers 404 it counts as running, only a server error or no answer counts as down. Services that do not use HTTP (TCP or UDP) are not supported. Keys, rate limits and API documentation are part of your own code.
Steg for steg: Publiser en Node.js-app fra GitHub.
hosait.json
Optional. Put it at the root of the repository when detection guesses wrong or you want to be explicit. When present it wins over every heuristic; when present but invalid, the deploy fails loudly rather than guessing.
{
"$schema": "https://hosait.com/schema/hosait.json",
"runtime": "compose",
"compose": { "file": "docker-compose.yml" },
"web": { "service": "site", "port": 8080 }
}
{
"runtime": "node",
"build": "npm run build",
"start": "node dist/server.js",
"port": 3000,
"migrate": "npx prisma migrate deploy"
}
Start the file with "$schema": "https://hosait.com/schema/hosait.json" and an editor with JSON Schema support (VS Code, JetBrains, Zed) checks it and completes the keys as you type. The schema describes exactly what Hosait reads. A key it does not know is named as a warning in the precheck and in the deploy log.
| Field | Meaning |
|---|---|
| runtime | static, node or compose. The only required field. |
| build | Build command for static and node. Defaults to the package manager's build script. |
| output | Folder the build writes static files to (static only). |
| start | Start command (node only). Defaults to the package manager's start script. |
| port | The port the app listens on (node only). Hosait proxies to it. |
| migrate | A command run before the app starts, on every deploy and restart — migrations, seeds (node only). If it fails, the app is not started, the deploy fails with release_failed, and the previous version keeps running. |
| compose.file | Which compose file to use, if not docker-compose.yml. |
| web.service | The service that answers HTTP (compose). Set it when the automatic choice is wrong. A name the compose file does not have stops the deploy with web_service_unknown. |
| web.port | The container port of that service Hosait routes to (compose). Without it, the first port the container exposes. |
| compose.web | The older spelling of web.service, still read. If both are set they must name the same service. |
| compose.rolling | true (default): a redeploy rolls the changed services that take traffic, without downtime. false: every changed service is recreated in place, with a short gap. |
| storage | Object storage for the app: true for a private bucket, or { "public": "public/" } to also let anyone read files under that folder. Hosait creates the bucket, a key for it alone and the S3_* variables before the first start, and never replaces a value the project has. A compose file that names S3_BUCKET gets the same without this field. |
| afterPublish | What a person must do once the site is live, in order: up to 10 steps, each { "text": "…", "open": "/admin" } or { "text": "…", "action": "upload", "to": "public/" }. Shown as a checklist on the project page and in the dialog after publishing, and returned to agents as nextSteps. Write one for every step the app cannot do by itself: creating the first admin user, importing content, uploading files. |
| seed | Content put in place once, after the first successful publish (runtime compose): { "database": "seed/content.sql.gz" } is imported into the empty PostgreSQL, MySQL or MariaDB service, { "files": "seed/media" } is copied into the project's bucket under storage.public (or public/), and { "run": "npm run seed" } runs once in the web service. Never again on later deploys; "Run seed again" on the project page repeats it. Put the app's own import command in run rather than asking people to click buttons in the app's admin. |
| schedule | A list of jobs Hosait runs on a clock in a compose stack, at most 10: { "name": "nightly-report", "cron": "0 3 * * *", "service": "api", "command": "npm run report" }. cron is five fields in UTC (numbers, lists, ranges, steps) and never more often than every 5 minutes. Each run is like run_task, stopped after timeoutMinutes (1–15, default 5). A job waits while a deploy or another task runs, or while many projects are due at once, and then runs up to 10 minutes late; after that the run is recorded as missed. Hosait reads the list at every successful publish: a rollback does not bring back an older one, and removing the key removes the jobs. The 10 most recent runs of each job, with their output, are on the project page. |
| redirects | Redirects and rewrites for a static site, at most 50, checked in order: { "from": "/old", "to": "/new", "status": 301 }. from is a path, or a path ending in one *; :splat in to stands for what the * matched. status is 301 (the default), 302, 303, 307 or 308, answered before Hosait looks for a file, or 200: a rewrite used only when no file matches, so { "from": "/*", "to": "/index.html", "status": 200 } is the single-page-app fallback. The query string is kept. Hosait serves a site with rules itself instead of straight from disk. |
| headers | Response headers for a static site’s files, at most 20 rules: { "path": "/assets/*", "set": { "Cache-Control": "public, max-age=31536000, immutable" } }. path works as in redirects ("/*" is every file). Every rule that matches applies, in order, and a later one wins for the same header; a rule’s Cache-Control replaces Hosait’s own. Set-Cookie, Location, Content-Length and other headers that change how a response is framed are refused, and so is anything starting with X-Accel-, X-Hosait-, X-Forwarded- or Proxy-. |
Docker Compose
A compose stack runs as-is. These are the conventions Hosait applies around it.
Steg for steg: Kjør Docker Compose-stakken din som den er.
- Which service is the web front
- In order:
web.service(orcompose.web) from hosait.json; then the service picked under Advanced on the project page; then the one service that publishes or exposes port 80 or 443; then a service named web, frontend, proxy, nginx, caddy, www, app or gateway; then the first service that publishes a port; then the first service. A database or cache is never chosen by itself. Setweb.service— andweb.portif the app listens on another port than the first one it exposes — when that lands on the wrong one. - One-shot services and release steps
- A migrate or seed service that runs and exits with 0 is not a failure; Hosait health-checks only the web service. To make a migration a release step, let the web service wait for it with depends_on: condition: service_completed_successfully. If the step exits with another code, the services that wait for it are not started, the deploy fails with release_failed naming the service and its exit code, and Hosait puts the previous version back. The stack is down for a moment while that happens, and whatever the migration changed before it failed stays changed.
- Redeploys without downtime
- When a live stack is deployed again, every changed service that takes traffic — the web service and services that listen on a port — starts as a new container beside the old one. Traffic moves once the new one answers, then the old one stops; a new one that never answers is removed and the old version keeps serving. Databases, caches and other data services, one-shot jobs and workers that take no traffic are recreated in place as before, so a change to those still means a short gap. Turn it off with compose.rolling: false in hosait.json.
- Published host ports are removed
- Hosait proxies straight to the container, so ports: entries are stripped before the stack starts. They would collide with the host, with other tenants, and a published database port would be exposed. You do not need to change your file.
- Volumes survive deploys
- Deploys are in place: named volumes and the compose project keep their identity, so your database is still there after a redeploy, after a failed deploy (the previous version starts again on the same volumes), and after a rollback (it restores code, not data), a restart, a pause or maintenance. Renaming a volume in the compose file starts a new, empty one. Volumes are removed only when you delete the project, and then all of them, including ones the file no longer names.
- Until the first success, a failed deploy starts over
- A stack that has never been live has no data to protect, so a failed deploy removes its volumes too. The next attempt creates the database with the variables you have now. Once a deploy has succeeded, volumes are kept. The live database starts empty: users and data from your own machine do not come along.
- Required variables come from the file
- Every
${VAR}reference without a default is required, and publishing is blocked until it has a value. - Isolation
privileged,cap_add,network_mode: host,pid: host,devices,security_opt,sysctls,volumes_from, bind mounts outside the repository (including the docker socket), external volumes and networks, and secrets from host files are refused withcompose_unsafebefore anything is built. Every service runs withno-new-privilegesand a resource ceiling (1 GB RAM, 1 CPU, 512 processes by default).- Every path is yours
- On your address, every path — including /api — reaches your app. Hosait reserves nothing on a customer's domain.
Maler
- (
nextjs-postgres): - (
streamlit): - (
supabase): - (
n8n):
Environment variables
- Values are masked everywhere in the interface; click the eye to reveal one.
- A required secret a compose file asks for (PASSWORD, SECRET, KEY, SALT … in its name) that has no value is generated once at deploy, saved on the project and named in the log. Someone else's keys (API keys, tokens) you add yourself.
- Hosait sets HOSAIT_COMMIT_SHA and HOSAIT_COMMIT_SHORT (the deployed commit) for every compose command. PATH, HOME, TMPDIR, XDG_RUNTIME_DIR, SSL_CERT_* and DOCKER_* come from the server and cannot be set, so a default for them in the compose file never applies: use your own names for your own settings. Nothing else from the server reaches your stack.
- HOSAIT_URL is the app's public address: your verified own domain when it has one, otherwise its address on hosait.com, starting with https:// and without a trailing slash. Every container gets it, and a compose file can use ${HOSAIT_URL}. PUBLIC_URL, APP_URL, BASE_URL, SITE_URL, NEXT_PUBLIC_SERVER_URL, NEXT_PUBLIC_SITE_URL and NEXTAUTH_URL are filled with it when your app uses them, as is any variable with "from": "url" in hosait.json. They follow the address when you add a domain, and a value you set yourself under Variables wins. Values built into the app (NEXT_PUBLIC_…) change at the next publish, not at a restart.
- A Node app gets NODE_OPTIONS=--max-old-space-size set to 75 % of its memory limit, so Node frees memory before it reaches the limit. Your own NODE_OPTIONS is kept, and a heap size you set there wins. In a compose stack this applies to services that run the official node image without a build. A service that still runs out of memory is restarted, and you get an e-mail and a notice on the project page.
- Save stores the values and restarts nothing. Apply by restart recreates the running containers with them — compose up without a build, or a single app started again next to the old one — with no fetch and no build, listed in the deploy history as “Applied by restart”. Save & publish fetches, builds and starts again.
- Values used at build time cannot be applied by restart: names starting with VITE_, NEXT_PUBLIC_, REACT_APP_, VUE_APP_, NUXT_PUBLIC_, GATSBY_, PUBLIC_ or EXPO_PUBLIC_, and any variable a compose file uses under build: (build args) or in image:. Apply by restart names them, saves nothing and offers Save & publish. When Hosait cannot tell for certain (a compose file with include:, say), it asks for a publish too.
- Do not change a database password after the first deploy. Postgres keeps the password its volume was created with; changing the variable alone locks the app out of its own database.
- After each publish, Hosait looks for secret keys in the files every visitor can read: a static site’s published files, and for an app the files in its repository’s public folders (public/, static/, dist/, build/ and out/), as they are before the build. It looks for private keys, Supabase service keys, Google service accounts, Stripe and AI service keys, GitHub, Slack and AWS keys, database addresses with a password, and the values of this project’s own secret variables. What it finds is named, masked, in the deploy log and on the project page, and your AI coding tool can read it (get_project_status). It never stops a publish. Keys meant for the browser (Stripe pk_…, Firebase AIza…, the Supabase anon key) are not reported.
Deploys, logs and rollback
- Build locally with Docker before you push (docker compose build, or docker build for a Dockerfile). A deploy is a production build on a clean machine: it catches type errors, a lockfile out of sync and files that were never committed — and each of those is otherwise a failed deploy.
- Every deploy is a row in the project's history: who triggered it, which commit, how long it took, what happened.
- Logs are captured for successful runs too — build output, then what the app printed once it was up. A failure that happens before there is any output stores its reason instead.
- Runtime logs — what get_runtime_logs and GET /logs read — are the output Docker keeps for each running container: up to 30 MB per service (three files of 10 MB, the oldest dropped first). A restart keeps them. When a deploy replaces a container — a single app on every deploy, a compose service when its image or settings changed — Hosait keeps the replaced version's last log for 7, 14 or 30 days (Starter, Pro, Scale; at most 5 per service and 100 MB per project). get_runtime_logs reads it with previous: true.
- Hosait resolves the branch tip before fetching and deploys that exact commit, so the SHA it shows is the code that ran.
- One deploy runs at a time per project. A push during a deploy waits in the history as queued; if more pushes arrive, only the newest waits, and it deploys the latest commit. Until it starts, a waiting deploy can be cancelled from the project page — it is then shown as cancelled, not failed. A deploy that has started cannot be cancelled.
- A failed deploy never takes a working site down. The previous version keeps serving, and the failure is shown to you on the project page — not to your visitors.
- Roll back restores the previous version with one click. The button is shown only when one exists.
Operations reference
Fakta en driftsansvarlig eller en tilgangsliste trenger: hvor Hosait kjører, adressene og grensene, og hvordan stacken din behandles. Kommandoer, filnavn og innstillinger vises nøyaktig slik du skriver dem.
- Region
- Én: Oslo, Norge. Alle prosjekter – med tjenester, databaser, volumer og objektlagring – kjører der, og API-et oppgir
region: "oslo"for hvert av dem. Det finnes ikke noe annet anlegg, ikke noe kantnettverk og ingen automatisk omkobling til et annet sted. En region nummer to kommer når etterspørselen forsvarer et nytt anlegg. - Utgående IP-adresse
- Alle forespørsler stacken din sender ut, går fra én fast adresse:
213.184.208.76(Norge). Legg den inn i tilgangslisten hos databaseleverandøren din, betalings-API-et eller en tjeneste du drifter selv. Den endres ikke mellom publiseringer. - Ferdigbygde images, uten bygg fra repoet
- En compose-fil der tjenestene bruker
image:(fra Docker Hub, GHCR eller et annet offentlig register), publiseres uten at noe bygges. Bland fritt:build:for dine egne tjenester,image:for resten. Private images (på ghcr.io, Docker Hub, registry.gitlab.com eller quay.io) virker også, både forimage:og forFROMi en Dockerfile: legg inn brukernavn og tilgangsnøkkel under prosjektets Innstillinger → Private registre. Tilgangsnøkkelen lagres kryptert, brukes bare til publiseringer av det prosjektet og vises aldri igjen. Hver publisering henter imagene på nytt, så en tag som er pushet på nytt, blir plukket opp; en tilbakerulling bruker imagene som allerede ligger på verten. Lås til commiten: Hosait girHOSAIT_COMMIT_SHA(ogHOSAIT_COMMIT_SHORT) til compose-filen, såimage: ghcr.io/acme/api:${HOSAIT_COMMIT_SHA}kjører nøyaktig det CI bygde for den publiserte commiten – også ved omstart og tilbakerulling. - Minne og CPU per tjeneste
- En tjeneste kjører med det compose-filen oppgir –
deploy.resources.limits.memoryog.cpus, eller de eldremem_limitogcpus– og med 1 GB og 1 CPU når den ikke oppgir noe. Planen din setter et tak for hver tjeneste og for hele prosjektet: Starter 2 GB / 2 CPU-er per prosjekt (2 GB / 1 CPU per tjeneste), Pro 2 GB / 2 CPU-er (2 GB / 2), Scale 16 GB / 8 CPU-er (8 GB / 4). CPU deles med andre prosjekter på serveren: dette er tak, ikke en reservert andel. Over et tak starter ingenting, og publiseringen feiler medcompose_limits_exceeded, som navngir tjenesten. Hver tjeneste uten egne grenser teller som 1 GB i totalen, så gi små tjenester små grenser (nginx128m, redis256m). Veiviseren for nye prosjekter sjekker filen mot planen din før første publisering og foreslår planen som passer. - Forbruk mot grensen
- Prosjektsiden (Oversikt → Forbruk per tjeneste) og MCP-verktøyet
get_usageviser for hver tjeneste hvor mye minne og CPU den bruker nå mot grensen den kjører med, toppen det siste døgnet og toppen siden containeren sist startet (hold musen over minnelinjen; en publisering starter nye containere). Hosait måler hver kjørende container én gang i minuttet meddocker stats; toppene holdes i serverens minne og begynner på nytt når Hosaits backend startes på nytt. En topp er den høyeste målingen, så en kort topp på under ett minutt kan bli oversett – men at en tjeneste stoppes fordi den gikk tom for minne, registreres alltid. En tjeneste som går over minnegrensen sin, stoppes av kjernen og startes igjen hvis den har enrestart:-regel: siden viser «gikk tom for minne» med tidspunktet for hver stopp det siste døgnet (fra Dockersoom-hendelse), og antallet omstarter Docker teller for containeren. CPU vises i antall CPU-er (0,25 = en firedel av én); en tjeneste som når CPU-grensen sin, går saktere, men stoppes ikke. Iget_usagestår tallene iservices[]:limit,current,peak24h,peakSinceStart,restarts,oomKilled,lastExitCode(137 = stoppet) ogooms, ogsamplingforteller hvor ofte det måles og siden når. - Ferdigbygde images fra CI
- Selve forespørselen er beskrevet under Deploy-API (CI). To innstillinger får den til å passe i en pipeline som bygger images: slå av Publiser automatisk ved push (Innstillinger → Avansert), så en push ikke publiserer før CI har pushet imagene; og tag imagene med commiten,
image: ghcr.io/acme/api:${HOSAIT_COMMIT_SHA}, så publiseringen kjører nøyaktig det CI bygde. En låst publisering som først starter etter at en nyere commit har gått live, registreres som hoppet over i stedet for å sette den eldre commiten tilbake. - Byggecache
- Bygg kjører med BuildKit og deler en lagcache per vert. Et lag der ingenting av det som går inn, har endret seg, gjenbrukes (
CACHEDi publiseringsloggen); cache som er eldre enn sju dager, og images som ingenting viser til, ryddes bort hver dag. En uendret stack publiseres på nytt på 12–50 s; et helt nytt bygg tar så lang tid som Dockerfilen din gjør. - Privat som standard
- Nøyaktig én tjeneste i en stack kan nås fra internett: webtjenesten (se Docker Compose ovenfor). Alle andre tjenester – databaser, arbeidere, cacher – kan bare nås fra stackens eget nettverk.
ports:-oppføringer fjernes før start, så ingenting du publiserer ved et uhell, blir offentlig. Prosjektsiden viser hvilken tjeneste som er offentlig. - Helsesjekker og omstarter
- Compose følger
healthcheck:ogrestart:slik du har skrevet dem. Hosait helsesjekker webtjenesten over HTTP under publiseringen og sender trafikk til den så snart den svarer; en container som dør senere, startes på nytt av Docker etter sin egenrestart:-regel. - Datatjenester: snutter å kopiere
- Alle images kan kjøres, på et navngitt volum. Redis:
image: redis:7-alpinemedcommand: ["redis-server", "--save", "60", "1"]ogredis_data:/data. Meilisearch:image: getmeili/meilisearch:v1.10,MEILI_MASTER_KEY: ${MEILI_MASTER_KEY},meili_data:/meili_data. Objektlagring: bruk den innebygde S3-bøtta (se Objektlagring nedenfor) i stedet for å kjøre MinIO i stacken din. Postgres: se compose-eksempelet ovenfor. - Egne domener
- Prosjektsiden → Oversikt → Koble til eget domene: en veiledet flyt (hvilken adresse, hvor DNS styres, sjekk av eierskap, DNS og HTTPS). Hele listen, wildcard-navn og manuelle sertifikater finner du under Innstillinger → Avanserte domeneinnstillinger. Legg til hvilket navn du vil, apex eller underdomene; adressen på hosait.com beholder du for alltid. Eierskap bevises med én TXT-post (
_hosait.<name>); for å peke navnet hit bruker du en A-post til213.184.208.76for et apex-domene eller en CNAME tilcustom.hosait.comfor et underdomene. Legg til disse postene og endre ingenting annet i sonen din – MX, SPF og andre verifiseringsposter må bli stående. Ett navn er primært; de andre videresendes til det med 308. Sertifikatet kan utstedes før DNS flyttes: med et API-token fra Domeneshop (utstedes og fornyes automatisk, DNS-01), med DNS-delegering – én CNAME fra_acme-challenge.<name>til et mål underacme.hosait.com, og deretter utsteder og fornyer Hosait på egen hånd – eller ved at du legger til_acme-challenge-TXT-postene vi viser deg; uansett virker https fra første forespørsel etter flyttingen. - Wildcard-domener
- Legg til
*.example.comfor å betjene alle navn ett nivå under det – ett underdomene per kunde i en SaaS – medHost-headeren uendret, så appen din kan velge leietaker ut fra den. Tre poster: TXT_hosait.example.com(eierskap), CNAME*.example.com→custom.hosait.com, og delegerings-CNAME-en_acme-challenge.example.com. Et wildcard-sertifikat kan bare bevises via DNS, så det kommer via delegering (eller et Domeneshop-token) og fornyes automatisk. Et eksakt navn går alltid foran et wildcard, oga.b.example.comdekkes ikke av*.example.com. - Underdomener av Hosait-adressen
- Har du ikke eget domene? Slå på Underdomener av Hosait-adressen på hosait-raden under Innstillinger → Domener, så når alle navn ett nivå under
<project>.hosait.com–customer.<project>.hosait.com– appen din medHost-headeren uendret. Du legger ikke til noen DNS-poster: Hosait oppretter*.<project>.hosait.comi sin egen sone og utsteder og fornyer wildcard-sertifikatet selv (det første tar et minutt eller to). Rut etter den første delen avHost, og behandle selve<project>.hosait.comsom ingen leietaker. Av som standard; slår du det av, fjernes posten og sertifikatet.a.b.<project>.hosait.comdekkes ikke. - Objektlagring
- En S3-kompatibel bøtte i Oslo (MinIO): endepunkt
https://s3.hosait.com, path-style-adressering, regionoslo, én bøtte per prosjekt. Prosjektet fårS3_ENDPOINT,S3_REGION,S3_BUCKET,S3_ACCESS_KEY_IDogS3_SECRET_ACCESS_KEY. Nøkkelen virker bare i sin egen bøtte: liste (ListObjectsV2,aws s3 ls), hente, legge inn og slette, og det samme for gamle versjoner; den kan lese versjoneringsstatusen til bøtta, men ikke endre noen innstilling, og ser aldri en annen bøtte. To innstillinger finnes på prosjektsiden under Innstillinger → Objektlagring, begge av som standard. Behold gamle versjoner (S3-versjonering): en overskriving eller sletting beholder forrige versjon. Hent tilbake en slettet fil ved å slette slettemarkøren dens:aws s3api list-object-versions --bucket <bucket> --prefix <key>, deretteraws s3api delete-object --bucket <bucket> --key <key> --version-id <marker id>. Gamle versjoner teller med i lagringen i planen din til du sletter dem (delete-objectmed deres--version-id). Slår du innstillingen av, lages ingen nye versjoner, men de gamle blir liggende (S3 kaller dette suspended). Offentlig mappe: ett prefiks, for eksempelpublic/(1–3 mappenavn som slutter på/, aldri hele bøtta), som alle kan lese over HTTPS uten nøkkel, påhttps://s3.hosait.com/<bucket>/public/<file>, for bilder, CSS og andre statiske filer. Ingen kan liste innholdet, og alt annet forblir privat. Det som ligger der, er offentlig for hele internett, og vilkårene våre gjelder for det akkurat som for nettstedet ditt; blir et prosjekt suspendert, stenges den offentlige mappen. Sett riktigContent-Typenår du laster opp, for det er det nettleserne får. Sletter du prosjektet, slettes bøtta med alle versjonene i den. - Størrelse på repoet
- Hosait henter grenen din som ett arkiv. Arkivet kan være på høyst 100 MB komprimert og kan pakkes ut til høyst 1 GB og 200 000 filer; et større arkiv avvises med
repo_too_largefør noe bygges. Bilder, PDF-er, videoer og andre filer som allerede er komprimert blir ikke mindre i arkivet, så omtrent 100 MB av dem er grensen, langt under 1 GB. Hold mediefiler og datasett utenfor git og legg dem i prosjektets S3-lagring, og holdnode_modulesog byggeresultater i.gitignore. Publiseringsnotatet sier hvilken grense som ble nådd. - Sikkerhetskopier
- Ikke slått på ennå. I forhåndsversjonen finnes det ingen automatiske sikkerhetskopier – ta vare på din egen kopi av kode og data. Funksjonen er bygget og forblir av til et lager for sikkerhetskopier med testet gjenoppretting er på plass; frem til da står det Sikkerhetskopiering er ikke slått på ennå på prosjektsiden. Når den er slått på, blir hver Postgres-, MySQL-, MariaDB- og MongoDB-tjeneste i en compose-stack dumpet hver natt med sitt eget verktøy, inne i sin egen container, og deretter komprimert og kryptert per prosjekt. Det beholdes 7 daglige og 4 ukentlige kopier (Scale: 14 daglige, 8 ukentlige, 6 månedlige). Innstillinger → Sikkerhetskopier viser dem og tilbyr Ta kopi nå, Last ned (den dekrypterte dumpen, som du kan beholde) og Gjenopprett, som først tar en ny sikkerhetskopi, stopper resten av stacken, laster inn dumpen og starter stacken igjen. Dumpen kjører med de offisielle imagenes egne variabler for innloggingsdata (
POSTGRES_USER,MYSQL_ROOT_PASSWORD,MARIADB_ROOT_PASSWORD,MONGO_INITDB_ROOT_USERNAME). Kopiene lagres kryptert i et S3-kompatibelt lager på en annen maskin enn den som kjører appene dine, så går den serveren tapt, går ikke sikkerhetskopiene tapt med den. Gjenopprettingen testes: omtrent én gang i uken gjenopprettes den nyeste kopien av hver database i en midlertidig database uten nettverk, og kopien av et volum leses tilbake i sin helhet; listen over sikkerhetskopier viser da Gjenoppretting testet med datoen. Sletter du et prosjekt, slettes sikkerhetskopiene. - For agenter
- Denne siden i maskinlesbar form: llms.txt og Hosait-skillen (Markdown, versjonert, hentes direkte av MCP-serverens
get_hosait_guide).
Connect your AI coding tool
The Hosait MCP server lets the AI coding tool in your repository inspect and operate the project it belongs to: status, deploys, logs, variables, redeploy, rollback, restart. It runs on your machine and talks to Hosait over HTTPS with a token scoped to one project.
Steg for steg: Publiser med KI-kodeverktøyet ditt.
Add Hosait to your AI coding tool
Find your tool below. The first time the tool uses Hosait, you sign in in the browser, choose one project and see the permissions. No token to copy.
Simplest: the Hosait plugin for your AI coding tool. One command installs the Hosait tools and a skill that always reads the current guide. Nothing to copy:
claude plugin install hosait --marketplace Hosait/claude-plugin
Then type /mcp in your AI coding tool, choose hosait and log in. In the browser you choose one project and see the permissions (read and deploy, and for a blank project also connecting it to a repository). The connection is listed under that project's Settings → API tokens, where you can revoke it.
Other tools, or without logging in through the browser: use the MCP server on your machine with a project token.
- On the project page, open Settings → API tokens and create one. It is shown once.
- Register the server with your AI coding tool, for example:
claude mcp add hosait --env HOSAIT_TOKEN=hosait_pat_… -- npx -y hosait-mcp-server
Teach your AI coding tool the conventions on this page: install the Hosait skill, and it writes hosait.json, compose files and Dockerfiles the way Hosait expects — and knows what every error code means.
mkdir -p ~/.claude/skills/hosait && curl -fsSL -o ~/.claude/skills/hosait/SKILL.md https://hosait.com/skills/hosait-stub/SKILL.md
Other AI coding tools
These can log in the same way: add the address to the tool's settings (for one common tool that is ~/.codex/config.toml, as below) and log in. These steps follow the tool maker's documentation and may change between versions; the token commands below work too.
# ~/.codex/config.toml
[mcp_servers.hosait]
url = "https://hosait.com/mcp"
codex mcp login hosait
codex mcp add hosait --env HOSAIT_TOKEN=hosait_pat_… -- npx -y hosait-mcp-server
codex mcp list
mkdir -p ~/.agents/skills/hosait && curl -fsSL -o ~/.agents/skills/hosait/SKILL.md https://hosait.com/skills/hosait-stub/SKILL.md
AI assistants in the browser
Add https://hosait.com/mcp as a custom MCP server in the assistant's developer mode. When you use a project tool, log in to Hosait, choose one project and approve the permissions shown. The connection is listed under that project's Settings → API tokens, where you can revoke it at any time. Commands and other sensitive changes still ask for a separate approval in Hosait.
Deploy-API (CI)
Publiser fra din egen pipeline, for eksempel GitHub Actions når testene har gått gjennom. Lag et token med tillatelsen deploy under prosjektets Innstillinger → API-tokens, og lagre det som en hemmelighet i CI-en din (aldri i repoet).
POST /api/mcp/v1/redeploy publiserer siste commit på grenen prosjektet følger. Send {"ref": "<commit-SHA>"} for å sikre at akkurat den commiten – for eksempel den CI nettopp testet – er den som går live. Hosait sjekker først hos GitHub at commiten finnes, ligger på grenen prosjektet følger og fortsatt er den siste der; ellers startes ingenting (ref_not_found, ref_not_on_branch, ref_not_latest hvis en nyere commit er pushet – den publiseres av sin egen push). Vil du publisere en eldre commit med vilje, legger du til "allowOlder": true. Eieren godkjenner det i Hosait først, som en tilbakerulling.
Svaret inneholder en deployId. Spør GET /api/mcp/v1/deploys/<deployId> med noen sekunders mellomrom til deploy.status er succeeded, failed eller rolled_back; hvis den feiler, forteller GET /api/mcp/v1/deploys/latest/diagnostics hvorfor.
# .github/workflows/publish.yml — after your tests
- name: Publish on Hosait
env:
HOSAIT_TOKEN: ${{ secrets.HOSAIT_TOKEN }}
run: |
id=$(curl -fsS -X POST https://hosait.com/api/mcp/v1/redeploy \
-H "Authorization: Bearer $HOSAIT_TOKEN" -H "Content-Type: application/json" \
-d "{\"ref\": \"${{ github.sha }}\"}" | jq -r .deployId)
[ -n "$id" ] && [ "$id" != null ] || exit 1
for i in $(seq 1 60); do
s=$(curl -fsS -H "Authorization: Bearer $HOSAIT_TOKEN" \
https://hosait.com/api/mcp/v1/deploys/$id | jq -r .deploy.status)
[ "$s" = succeeded ] && exit 0
case "$s" in failed|rolled_back) exit 1;; esac
sleep 10
done; exit 1
Ferdigbygde images: la compose-filen hente taggen fra en variabel, f.eks. image: ghcr.io/deg/app:${IMAGE_TAG}. Sett den med PATCH /api/mcp/v1/env (tillatelsen env:write) og kall deretter redeploy. Offentlige images på GHCR, Docker Hub og andre registre virker uten videre. Private images virker også: legg inn brukernavn og tilgangsnøkkel under prosjektets Innstillinger → Private registre.
Tools
| get_project_status | Status, address, deploy kind, source. |
| list_deploys | Recent deploys, newest first. |
| get_deploy | One deploy by id, as it is now. |
| wait_for_deploy | Waits until a deploy has ended, then answers its outcome: status, error code, commit, duration and, on failure, the end of its log. |
| get_deploy_log | The captured log, secrets redacted. |
| get_env | Variable names; secret-looking values come back masked. |
| set_env | Set or update variables by key. Unmentioned keys are untouched; a masked value means keep what is stored. |
| delete_env | Remove one variable. |
| redeploy | Deploy the branch tip again. Returns the deploy id. |
| rollback | Restore the previous version. |
| restart | Restart the running app or stack without rebuilding. With applyEnv: true it recreates it with the stored variables instead (after set_env); a variable used at build time is refused with env_needs_redeploy — redeploy for those. |
| get_runtime_logs | What the running app prints now — one service or all, last N lines, since a point in time, filtered by text or level. |
| run_task | Run one command in a compose service (migration, seed, script), time-limited; the output lands in the history. |
| get_task | One task by id — status, exit code and output. |
| list_services | The compose services and their state — the names run_task and the log filter take. |
| get_deploy_diagnostics | Why a deploy failed, in one answer: error code, missing variables, service states, rollback availability, log tail. With explain: true, also an AI-written cause and fix for a failed deploy — if the owner has turned AI explanations on. |
| check_live_site | Request the public address now: status, latency, and whether a holding page answers. |
| get_domain_diagnostics | Per domain: records to add, a fresh DNS check and the certificate state. Read-only. |
| get_usage | Disk, memory and CPU now and the ceiling each service runs under; per service also the 24-hour peak, restarts and out-of-memory kills. |
| analyze_repository | What Hosait would run for a GitHub repository: runtime, start command, required variables, findings. Read-only. |
| get_build_plan | The same for this project's own repository and branch: what the next deploy will do, with the project's settings applied. Read-only. |
| connect_repository | Point a blank project at a repository, set its variables and deploy. The owner approves first. |
| open_connect_pr | Open a pull request that adds .mcp.json and a Hosait section in AGENTS.md, so AI tools in the repository know how it is hosted. Changes no other branch. |
| upload_to_storage | Upload a folder from your computer to the project’s storage; files already there are skipped. Local MCP server only. |
| import_database | Import a .sql or .sql.gz dump into the project’s database. The owner approves first. Local MCP server only. |
| set_maintenance | Maintenance mode on or off: the address shows a holding page while the app keeps running. |
Revoke the token from the same tab at any time; it stops working immediately.
Error codes
Every failed deploy carries a stable code alongside its explanation. The code is what to search for or paste into an AI tool; the text follows your language.
| github_connection_expired | |
| github_rate_limited | |
| github_forbidden | |
| github_unreachable | |
| github_member_no_access | |
| repo_not_found | |
| branch_not_found | |
| no_repo | |
| scm_connection_expired | |
| scm_not_connected | |
| scm_forbidden | |
| scm_rate_limited | |
| scm_unreachable | |
| repo_empty | |
| builder_disabled | |
| build_failed | |
| build_timeout | |
| no_build_output | |
| nothing_to_deploy | |
| compose_file_missing | |
| monorepo_root | |
| env_missing | |
| compose_unsafe | |
| compose_start_failed | |
| compose_start_timeout | |
| web_service_unknown | |
| compose_limits_exceeded | |
| storage_full | |
| payment_required | |
| image_pull_failed | |
| app_start_failed | |
| release_failed | |
| storage_setup_failed | |
| manifest_invalid | |
| bad_domain | |
| domain_unverified | |
| domain_unsupported | |
| nothing_to_roll_back | |
| rollback_data_changed | |
| rollback_failed |
API errors
Every refused request to the API or the MCP tools answers JSON with ok: false, a stable code and, for the codes below, a docs link to its row here.
| abuse_category | |
| abuse_description_long | |
| abuse_description_short | |
| abuse_email_invalid | |
| abuse_email_missing | |
| abuse_failed | |
| abuse_good_faith | |
| abuse_name_missing | |
| abuse_not_hosait | |
| abuse_rate_limited | |
| abuse_report_open | |
| abuse_url_invalid | |
| abuse_url_missing | |
| access_bad_mode | |
| access_not_on_this_server | |
| access_not_ready | |
| access_password_required | |
| access_password_too_long | |
| access_password_too_short | |
| access_save_failed | |
| access_unavailable | |
| acme_failed | |
| acme_no_dns01 | |
| ai_gateway_off | |
| ai_not_used | |
| ai_tool_required | |
| already_issued | |
| apex | |
| approval_denied | |
| approval_limit | |
| approval_pending | |
| approval_required | |
| backup_busy | |
| backup_corrupt | |
| backup_failed | |
| backup_not_ready | |
| backup_store_failed | |
| backups_not_configured | |
| bad_branch | |
| bad_category | |
| bad_command | |
| bad_env | |
| bad_env_name | |
| bad_favicon | |
| bad_favicon_size | |
| bad_grep | |
| bad_history | |
| bad_id | |
| bad_image | |
| bad_installation | |
| bad_json | |
| bad_key | |
| bad_level | |
| bad_mode | |
| bad_name | |
| bad_plan | |
| bad_ref | |
| bad_repo | |
| bad_request | |
| bad_role | |
| bad_service | |
| bad_since | |
| bad_source | |
| bad_state | |
| bad_token | |
| bad_upload | |
| billing_cancel_failed | |
| billing_unconfigured | |
| branch_preview_app_limit | |
| branch_preview_app_new_account | |
| branch_preview_busy | |
| branch_preview_interrupted | |
| branch_preview_kind_unsupported | |
| branch_preview_limit | |
| branch_preview_needs_app | |
| branch_preview_not_github | |
| branch_preview_not_hosait | |
| branch_preview_unavailable | |
| busy | |
| card_needed | |
| cert_failed | |
| challenge_bad_request | |
| challenge_bad_signature | |
| challenge_expired | |
| challenge_replayed | |
| challenge_required | |
| challenge_wrong | |
| chat_unconfigured | |
| confirm_mismatch | |
| consent_required | |
| csrf | |
| current | |
| data_browser_unavailable | |
| data_no_database | |
| data_not_running | |
| data_query_failed | |
| data_query_refused | |
| data_query_timeout | |
| data_table_unknown | |
| database_none | |
| delegation_dns_failed | |
| delegation_missing | |
| delegation_not_configured | |
| delegation_not_visible | |
| delegation_zone_mismatch | |
| delegation_zone_missing | |
| deploy_in_progress | |
| deploy_not_queued | |
| deploy_running | |
| dns_error | |
| domain_held_by_deleted | |
| domain_not_verified | |
| domain_pending_elsewhere | |
| domain_taken | |
| draft_conflict | |
| edge_not_configured | |
| email_taken | |
| email_unverified | |
| empty_message | |
| empty_zip | |
| env_conflict | |
| env_decrypt_failed | |
| env_needs_redeploy | |
| env_required | |
| env_wipe | |
| explain_failed | |
| explain_unavailable | |
| favicon_too_large | |
| forbidden | |
| github_app_bad_repo | |
| github_app_disabled | |
| github_app_lookup_failed | |
| github_app_permissions | |
| github_app_token_failed | |
| github_app_unconfigured | |
| github_app_uninstalled | |
| github_disabled | |
| github_installation_not_yours | |
| github_unavailable | |
| google_failed | |
| google_unconfigured | |
| history_not_found | |
| hosa_busy | |
| hosa_unavailable | |
| image_rate_limited | |
| image_too_large | |
| import_bad_file | |
| import_not_found | |
| invalid | |
| invalid_ai_tool | |
| invalid_credentials | |
| invalid_email | |
| invalid_token | |
| invalid_zip | |
| is_current | |
| is_owner | |
| last_owner | |
| masked_unknown_key | |
| message_too_long | |
| microsoft_failed | |
| microsoft_unconfigured | |
| missing_token | |
| no_cname | |
| no_customer | |
| no_domeneshop_token | |
| no_file | |
| no_messages | |
| no_runtime_logs | |
| no_subscription | |
| no_txt | |
| not_applicable | |
| not_blank | |
| not_compose | |
| not_connected | |
| not_ending | |
| not_failed | |
| not_found | |
| not_github | |
| not_pointing | |
| not_repo_source | |
| not_restartable | |
| not_running | |
| not_verified | |
| not_zip | |
| nothing | |
| nothing_to_update | |
| nothing_verified | |
| password_required | |
| password_too_long | |
| password_too_short | |
| pause_failed | |
| permanent | |
| plan_favicon | |
| plan_project_limit | |
| plan_unavailable | |
| policy_violation | |
| preview_closed | |
| preview_free | |
| price_not_configured | |
| project_deleted | |
| project_limit | |
| project_paused | |
| project_suspended | |
| provider_unavailable | |
| rate_limited | |
| reauth_required | |
| ref_not_found | |
| ref_not_latest | |
| ref_not_on_branch | |
| ref_not_supported | |
| registry_auth_failed | |
| registry_decrypt_failed | |
| registry_not_allowed | |
| registry_not_found | |
| registry_token_invalid | |
| registry_token_short | |
| registry_unreachable | |
| registry_username_invalid | |
| repo_connect_failed | |
| repo_connect_needs_app | |
| repo_connect_not_github | |
| repo_connect_permission | |
| repo_connect_protected | |
| reserved | |
| restart_failed | |
| restore_expired | |
| restore_failed | |
| restore_warnings | |
| resume_failed | |
| scope_missing | |
| seed_busy | |
| seed_unavailable | |
| server_error | |
| server_unavailable | |
| site_accept_required | |
| site_busy | |
| site_check_failed | |
| site_check_missing | |
| site_check_not_yellow | |
| site_check_red | |
| site_check_running | |
| site_check_scope | |
| site_check_stale | |
| site_check_unknown | |
| site_daily_limit | |
| site_dns_not_found | |
| site_error | |
| site_host_limit | |
| site_http_only | |
| site_invalid_url | |
| site_owner_required | |
| site_parked | |
| site_timeout | |
| site_tls_invalid | |
| site_unavailable | |
| site_unreachable | |
| source_already_set | |
| state_too_large | |
| storage_bad_files | |
| storage_bad_prefix | |
| storage_bad_request | |
| storage_elsewhere | |
| storage_no_key | |
| storage_none | |
| storage_public_needs_trust | |
| storage_quota_full | |
| storage_taken | |
| storage_unconfigured | |
| subdomains_budget | |
| subdomains_busy | |
| subdomains_cert_valid | |
| subdomains_dns_failed | |
| subdomains_dns_not_visible | |
| subdomains_issuing | |
| subdomains_not_hosait | |
| subdomains_off | |
| subdomains_reserved | |
| subdomains_unavailable | |
| subscription_active | |
| subscription_ending | |
| token_expired | |
| too_large | |
| too_many | |
| too_many_deleted | |
| too_many_entries | |
| too_many_images | |
| try_busy | |
| try_claimed | |
| try_limit | |
| try_needs_account | |
| try_not_found | |
| try_password_form | |
| try_secrets | |
| try_unavailable | |
| two_factor_already_enabled | |
| two_factor_email_unverified | |
| two_factor_expired | |
| two_factor_invalid | |
| two_factor_locked | |
| two_factor_not_enabled | |
| two_factor_required | |
| two_factor_setup_expired | |
| two_factor_sign_in_again | |
| two_factor_unavailable | |
| unauthenticated | |
| undo_delete_off | |
| unknown_address | |
| unknown_provider | |
| unknown_service | |
| unverified | |
| upload_busy | |
| upload_disabled | |
| use_subdomains_switch | |
| version_is_live | |
| version_not_found | |
| version_not_kept | |
| volume_not_mounted | |
| volume_read_only | |
| wildcard_needs_dns | |
| wrong_password | |
| wrong_target | |
| wrong_txt | |
| zip_too_large_extracted | |
| zip_unsafe_path | |
| zone_unavailable |
Holding pages
When there is nothing to serve yet — a first deploy in progress, a project that has never run, an unclaimed address — Hosait answers with a holding page in the visitor's language. It is distinguishable from your app by machine:
X-Hosait-Placeholder: queued | provisioning | failed | maintenance | paused | suspended | available | unknown_address | upstream_down
Cache-Control: no-store
# with Accept: application/json
{ "ok": false, "code": "not_live", "placeholder": "queued" }
Every method gets the same answer — GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS alike: 503 while a project is queued, being set up or failed, with Retry-After: 60 while a deploy is on its way. A request with Accept: application/json gets the JSON body, anything else the HTML page.
A running app is proxied untouched — none of this is added to your responses.
Recipes
Compose files you can copy for things an app often needs and Hosait does not build itself.
Add login to an app
Sign-up, sign-in and sessions with e-mail and password, using SuperTokens. Its login core and its database stay private: only your app gets an address, and it serves the sign-in API under /auth.
- 1
Add the three services to your compose file, next to your app. Your app keeps its own service and gets the three variables shown and a memory limit.
services: app: build: . # your own app environment: AUTH_CORE_URL: http://auth-core:3567 AUTH_CORE_SECRET: ${AUTH_CORE_SECRET:?generated on the first deploy} APP_URL: ${HOSAIT_URL:-http://localhost:3000} depends_on: - auth-core mem_limit: 256m auth-core: image: supertokens/supertokens-postgresql:12.3.1 environment: POSTGRESQL_CONNECTION_URI: postgresql://auth:${AUTH_DB_PASSWORD:?generated on the first deploy}@auth-db:5432/auth API_KEYS: ${AUTH_CORE_SECRET} DISABLE_TELEMETRY: "true" depends_on: auth-db: condition: service_healthy mem_limit: 512m auth-db: image: postgres:16-alpine environment: POSTGRES_USER: auth POSTGRES_PASSWORD: ${AUTH_DB_PASSWORD} POSTGRES_DB: auth volumes: - auth_db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U auth -d auth"] interval: 5s timeout: 3s retries: 10 mem_limit: 256m volumes: auth_db: - 2
Tell Hosait which service answers HTTP in
hosait.json. The login core and its database are never given an address.{ "$schema": "https://hosait.com/schema/hosait.json", "runtime": "compose", "web": { "service": "app", "port": 3000 }, "healthcheck": "/health" } - 3
In your app, install the SDK and add the setup.
verifySession()protects a route and gives you the signed-in user.// npm i express supertokens-node const express = require('express'); const supertokens = require('supertokens-node'); const Session = require('supertokens-node/recipe/session'); const EmailPassword = require('supertokens-node/recipe/emailpassword'); const { middleware, errorHandler } = require('supertokens-node/framework/express'); const { verifySession } = require('supertokens-node/recipe/session/framework/express'); const site = process.env.APP_URL; supertokens.init({ framework: 'express', supertokens: { connectionURI: process.env.AUTH_CORE_URL, apiKey: process.env.AUTH_CORE_SECRET }, appInfo: { appName: 'My app', apiDomain: site, websiteDomain: site, apiBasePath: '/auth', websiteBasePath: '/login' }, recipeList: [ // The default sender would post users' e-mail addresses to SuperTokens. This one does nothing. EmailPassword.init({ emailDelivery: { override: (original) => ({ ...original, sendEmail: async () => {} }) } }), Session.init(), ], }); const app = express(); app.get('/health', (req, res) => res.send('ok')); app.use(middleware()); app.use(express.static('public', { extensions: ['html'] })); app.get('/me', verifySession(), (req, res) => res.json({ id: req.session.getUserId() })); app.use(errorHandler()); app.listen(3000); - 4
Add a sign-in page. The header
st-auth-mode: cookiematters: without it the SDK hands the tokens back in headers and sets no cookie.<!doctype html> <meta charset="utf-8"> <title>Sign in</title> <form id="f"> <input name="email" type="email" placeholder="E-mail" required> <input name="password" type="password" placeholder="Password" required> <button data-path="signin">Sign in</button> <button data-path="signup">Create account</button> <p id="msg"></p> </form> <script> document.querySelectorAll('button').forEach((b) => b.addEventListener('click', async (e) => { e.preventDefault(); const f = new FormData(document.getElementById('f')); const r = await fetch('/auth/' + b.dataset.path, { method: 'POST', // st-auth-mode: cookie is what makes the session a cookie headers: { 'content-type': 'application/json', rid: 'emailpassword', 'st-auth-mode': 'cookie' }, body: JSON.stringify({ formFields: [{ id: 'email', value: f.get('email') }, { id: 'password', value: f.get('password') }] }), }); const d = await r.json(); if (d.status === 'OK') return (location.href = '/'); document.getElementById('msg').textContent = d.status === 'FIELD_ERROR' ? d.formFields.map((x) => x.error).join(' ') : d.status === 'WRONG_CREDENTIALS_ERROR' ? 'Wrong e-mail or password.' : d.status; })); </script> - 5
Publish.
AUTH_CORE_SECRETandAUTH_DB_PASSWORDare generated on the first deploy and saved on the project. Never changeAUTH_DB_PASSWORDafterwards: the database keeps the one it was created with.
- E-mail is left out: Hosait has no mail relay for customer apps. The SDK's default sender would post a user's address to SuperTokens, so the setup above replaces it with one that does nothing. Password reset and e-mail verification need your own e-mail service.
- Telemetry is switched off in the core, and with these settings the stack makes no calls to SuperTokens' own services. Checked at start-up and on a password-reset request.
- The sign-in cookie lasts an hour. A page renews it with
POST /auth/session/refreshand the headerrid: session, and signs out withPOST /auth/signoutand the same header. - The core uses about 180 MB and its database about 50 MB. The declared limits keep the stack inside the 512 MB per service that new accounts get, and well inside a Starter plan.
- Pin the core's image tag: Hosait pulls images again on every deploy, so a floating tag changes under you. The core is open source (Apache-2.0); some SuperTokens features need a license key under their own terms. This recipe uses only sign-up, sign-in and sessions.
Send a contact form to your inbox
A contact form that saves each message in your own database and e-mails it to you. It runs inside your own app, with no extra service, and sends through your own e-mail provider.
- 1
Add a database next to your app, and the variables for the e-mail. Your app keeps its own service. You fill in
SMTP_URL,MAIL_TOandMAIL_FROMyourself; Hosait generates the database password.services: app: build: . # your own app environment: DATABASE_URL: postgresql://forms:${FORMS_DB_PASSWORD:?generated on the first deploy}@db:5432/forms SMTP_URL: ${SMTP_URL:?your e-mail provider, for example smtps://user:password@smtp.example.com:465} MAIL_TO: ${MAIL_TO:?the address that receives the messages} MAIL_FROM: ${MAIL_FROM:?an address your e-mail provider lets you send from} APP_URL: ${HOSAIT_URL:-http://localhost:3000} depends_on: db: condition: service_healthy mem_limit: 256m db: image: postgres:16-alpine environment: POSTGRES_USER: forms POSTGRES_PASSWORD: ${FORMS_DB_PASSWORD} POSTGRES_DB: forms volumes: - forms_db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U forms -d forms"] interval: 5s timeout: 3s retries: 10 mem_limit: 256m volumes: forms_db: - 2
Tell Hosait which service answers HTTP in
hosait.json. The database is never given an address.{ "$schema": "https://hosait.com/schema/hosait.json", "runtime": "compose", "web": { "service": "app", "port": 3000 }, "healthcheck": "/health" } - 3
In your app, install the three packages and add the handler. It checks the input, saves the message, e-mails it and answers. A hidden field, a size limit, a check of where the post comes from and a cap on how many messages it accepts limit what a bot can do.
// npm i express nodemailer pg const express = require('express'); const nodemailer = require('nodemailer'); const { Pool } = require('pg'); const db = new Pool({ connectionString: process.env.DATABASE_URL }); const mail = nodemailer.createTransport(process.env.SMTP_URL); const origin = new URL(process.env.APP_URL).origin; // E-mail one saved message and mark it sent. A failure leaves it for the retry below. async function send(m) { await mail.sendMail({ from: process.env.MAIL_FROM, to: process.env.MAIL_TO, replyTo: m.email, subject: 'New message from the contact form', text: `From: ${m.name} <${m.email}>\n\n${m.message}`, }); await db.query('UPDATE messages SET sent_at = now() WHERE id = $1', [m.id]); } const app = express(); app.get('/health', (req, res) => res.send('ok')); app.use(express.static('public', { extensions: ['html'] })); let recent = []; // when the latest messages came in: at most 20 in 10 minutes app.post('/contact', express.urlencoded({ extended: false, limit: '20kb' }), async (req, res) => { const { name = '', email = '', message = '', website = '' } = req.body; if (req.get('origin') && req.get('origin') !== origin) return res.sendStatus(403); if (website) return res.send('Thanks!'); // the hidden field: only bots fill it in if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || email.length > 200 || name.length > 200 || !message.trim() || message.length > 5000) return res.status(400).send('Please check the form.'); recent = recent.filter((t) => Date.now() - t < 600000); if (recent.length >= 20) return res.status(429).send('Too many messages right now. Try again later.'); recent.push(Date.now()); const { rows } = await db.query('INSERT INTO messages (name, email, message) VALUES ($1, $2, $3) RETURNING *', [name, email, message]); send(rows[0]).catch((e) => console.error('mail failed:', e.message)); res.send('Thanks! We will reply soon.'); }); (async () => { await db.query(`CREATE TABLE IF NOT EXISTS messages ( id serial PRIMARY KEY, created_at timestamptz NOT NULL DEFAULT now(), name text NOT NULL, email text NOT NULL, message text NOT NULL, sent_at timestamptz)`); // Every 5 minutes: send what failed (for up to 7 days), and delete messages older than 90 days. setInterval(async () => { const { rows } = await db.query("SELECT * FROM messages WHERE sent_at IS NULL AND created_at > now() - interval '7 days' ORDER BY id LIMIT 20"); for (const m of rows) await send(m).catch((e) => console.error('mail failed:', e.message)); await db.query("DELETE FROM messages WHERE created_at < now() - interval '90 days'"); }, 300000).unref(); app.listen(3000); })(); - 4
Add the form. The field
websiteis hidden from people; a message that fills it in is thrown away.<!doctype html> <meta charset="utf-8"> <title>Contact</title> <form method="post" action="/contact"> <input name="name" placeholder="Your name" required maxlength="200"> <input name="email" type="email" placeholder="Your e-mail" required maxlength="200"> <textarea name="message" placeholder="Message" required maxlength="5000"></textarea> <input name="website" tabindex="-1" autocomplete="off" aria-hidden="true" style="position:absolute;left:-9999px"> <button>Send</button> </form> - 5
Set
SMTP_URL,MAIL_TOandMAIL_FROMunder Variables, then publish. Until they are set the deploy stops and names them.FORMS_DB_PASSWORDis generated on the first deploy and saved on the project. Never change it afterwards: the database keeps the one it was created with.
- Hosait has no mail relay for customer apps, and sending straight to other mail servers on port 25 is not allowed. Use your own e-mail provider on port 465 or 587, and send from an address the provider has verified for your domain. In
SMTP_URL, write special characters in the password as percent codes: an@becomes%40. - The message is saved before it is e-mailed. If your provider is down, it waits in the
messagestable and is sent within five minutes of the provider coming back, for up to seven days. A failure is written to the app's log. - Messages hold personal data. This recipe deletes them after 90 days; change that to fit your own privacy notice.
- The cap is 20 messages in 10 minutes for the whole site, kept in memory, so a restart resets it. A bot can use it up and shut real visitors out for ten minutes; for a busy public form, add a CAPTCHA from a provider of your choice.
- The app uses about 25 MB and the database about 25 MB. The declared limits keep the stack well inside the 512 MB per service that new accounts get, and inside a Starter plan.
Call AI models through your own gateway
A small private service in your stack that holds your AI provider key, wants a key of its own from your app on every call, and stops at a monthly spending limit. Your app calls the gateway instead of the provider, so the provider key never reaches your app's code or the browser.
- 1
Add the gateway next to your app. It is built from a Dockerfile and a settings file in a
gatewayfolder (the next two blocks). You fill inOPENAI_API_KEYandAI_MODELyourself; Hosait generates the keys the two services share.services: app: build: . # your own app environment: GATEWAY_URL: http://gateway:8080 GATEWAY_KEY: sk-bf-${GATEWAY_SECRET:?generated on the first deploy} AI_MODEL: ${AI_MODEL:?provider/model, for example openai/gpt-4o-mini} depends_on: gateway: condition: service_healthy mem_limit: 256m gateway: build: ./gateway environment: OPENAI_API_KEY: ${OPENAI_API_KEY:?your key from OpenAI} GATEWAY_KEY: sk-bf-${GATEWAY_SECRET} BIFROST_ENCRYPTION_KEY: ${BIFROST_ENCRYPTION_KEY:?generated on the first deploy} BIFROST_ADMIN_PASSWORD: ${BIFROST_ADMIN_PASSWORD:?generated on the first deploy} volumes: - gateway_data:/app/data healthcheck: test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"] interval: 5s timeout: 3s retries: 12 mem_limit: 512m volumes: gateway_data: - 2
The Dockerfile pins the gateway version and copies the settings in at every start, so a new deploy applies them. The gateway keeps its own state in a volume.
FROM maximhq/bifrost:v2.3.1 COPY config.json /app/config.json # The gateway keeps its state (budgets, logs) in the volume at /app/data; the # settings file is copied there at every start, so a new deploy applies it. ENTRYPOINT ["sh", "-c", "cp /app/config.json /app/data/config.json && exec /app/docker-entrypoint.sh"] - 3
The settings, in
gateway/config.json: one provider, one key for your app, a limit of 20 US dollars a month and 60 calls a minute. The gateway's management interface is locked with a generated password and has no address outside the stack.{ "$schema": "https://www.getbifrost.ai/schema", "encryption_key": "env.BIFROST_ENCRYPTION_KEY", "client": { "enforce_auth_on_inference": true, "disable_content_logging": true, "log_retention_days": 30 }, "providers": { "openai": { "keys": [ { "name": "main", "value": "env.OPENAI_API_KEY", "models": ["*"], "weight": 1.0 } ] } }, "governance": { "auth_config": { "is_enabled": true, "admin_username": "admin", "admin_password": "env.BIFROST_ADMIN_PASSWORD", "disable_auth_on_inference": true }, "virtual_keys": [ { "id": "vk-app", "name": "app", "value": "env.GATEWAY_KEY", "is_active": true, "rate_limit_id": "rl-app", "provider_configs": [ { "provider": "openai", "allowed_models": ["*"], "key_ids": ["*"], "weight": 1 } ] } ], "budgets": [ { "id": "budget-app", "max_limit": 20, "reset_duration": "1M", "virtual_key_id": "vk-app" } ], "rate_limits": [ { "id": "rl-app", "request_max_limit": 60, "request_reset_duration": "1m" } ] } } - 4
Tell Hosait which service answers HTTP in
hosait.json. The gateway is never given an address.{ "$schema": "https://hosait.com/schema/hosait.json", "runtime": "compose", "web": { "service": "app", "port": 3000 }, "healthcheck": "/health" } - 5
In your app, send the usual chat request to the gateway with the header
x-bf-vkand a model named as provider and model. For a streamed answer, addstream: trueand pass the events on.// npm i express const express = require('express'); const app = express(); app.use(express.json({ limit: '20kb' })); app.get('/health', (req, res) => res.send('ok')); app.post('/ask', async (req, res) => { const r = await fetch(process.env.GATEWAY_URL + '/v1/chat/completions', { method: 'POST', headers: { 'content-type': 'application/json', 'x-bf-vk': process.env.GATEWAY_KEY }, body: JSON.stringify({ model: process.env.AI_MODEL, // provider/model, for example openai/gpt-4o-mini messages: [{ role: 'user', content: String(req.body.question || '').slice(0, 2000) }], }), }); const data = await r.json(); if (!r.ok) { // 402: the monthly limit is reached. 429: too many calls in a minute. console.error('gateway said', r.status, data.error && data.error.message); return res.status(502).json({ error: 'The AI service is not available right now.' }); } res.json({ answer: data.choices[0].message.content }); }); app.listen(3000); - 6
Set
OPENAI_API_KEYandAI_MODELunder Variables, then publish. Until they are set the deploy stops and names them.GATEWAY_SECRET,BIFROST_ENCRYPTION_KEYandBIFROST_ADMIN_PASSWORDare generated on the first deploy and saved on the project. Leave them as they are: the app and the gateway must share the first, and the gateway encrypts what it stores with the second.
- The sample route
/askanswers anyone who can reach it. The monthly limit caps what misuse can cost, but put the route behind your own sign-in (the login recipe above) before real use. - When the monthly limit is reached the gateway answers 402, and when the rate limit is reached 429; the sample turns both into a plain 502. A model name the gateway does not know is refused with 403. Change the numbers in
config.jsonand publish: what has been spent so far is kept. - Prompts and answers are not stored: the log keeps only model, tokens, cost and time, for 30 days. The gateway downloads a price list from its maker's site, getbifrost.ai, when it starts and once a day, and a fresh gateway needs to reach that site once; your prompts and keys go only to your provider.
- To add another provider, add it under
providerswith its key as a variable (anthropicandANTHROPIC_API_KEY, say) and ask foranthropic/.... Pin the image version as shown: Hosait pulls images again on every deploy. - The gateway uses about 250 MB and the app about 30 MB, and the gateway takes about ten seconds to start. The declared limits (512 MB and 256 MB) fit the 512 MB per service that new accounts get, and a Starter plan.
- The gateway is Bifrost, open source under Apache-2.0. Its maker also sells an enterprise edition; this recipe uses none of it.
Take payments with Stripe
Sell something with Stripe Checkout: your app sends the visitor to Stripe's own payment page, and Stripe tells your app when the payment has gone through. Card details are typed on Stripe's page and never reach your app. You need your own Stripe account.
- 1
Add the Stripe variables next to your app. Your app keeps its own service. You fill in
STRIPE_SECRET_KEYandSTRIPE_WEBHOOK_SECRETyourself; Hosait gives the app the address it runs at asHOSAIT_URL.services: app: build: . # your own app environment: STRIPE_SECRET_KEY: ${STRIPE_SECRET_KEY:?your secret key from Stripe, starting sk_test_ or sk_live_} STRIPE_WEBHOOK_SECRET: ${STRIPE_WEBHOOK_SECRET:?the signing secret of the webhook in Stripe, starting whsec_} APP_URL: ${HOSAIT_URL:-http://localhost:3000} mem_limit: 256m - 2
Tell Hosait which service answers HTTP in
hosait.json.{ "$schema": "https://hosait.com/schema/hosait.json", "runtime": "compose", "web": { "service": "app", "port": 3000 }, "healthcheck": "/health" } - 3
In your app, install
expressandstripeand add the two routes./checkoutopens Stripe's payment page, with the amount set on the server so a visitor cannot change it./stripe/webhookchecks that a message really comes from Stripe before it is trusted.const express = require('express'); const Stripe = require('stripe'); const stripe = new Stripe(process.env.STRIPE_SECRET_KEY); const app = express(); app.get('/health', (req, res) => res.send('ok')); // Stripe's message must reach constructEvent as the raw bytes, so this route comes before any express.json(). app.post('/stripe/webhook', express.raw({ type: 'application/json' }), (req, res) => { let event; try { event = stripe.webhooks.constructEvent(req.body, req.get('stripe-signature'), process.env.STRIPE_WEBHOOK_SECRET); } catch (e) { return res.sendStatus(400); // not from Stripe, or the wrong signing secret } if (event.type === 'checkout.session.completed' && event.data.object.payment_status === 'paid') { // Your own part: mark the order paid. Stripe can send the same event twice, so look at event.id first. console.log('paid:', event.data.object.id, event.id); } res.sendStatus(200); }); app.use(express.static('public', { extensions: ['html'] })); app.post('/checkout', async (req, res) => { try { const session = await stripe.checkout.sessions.create({ mode: 'payment', // The amount is in the smallest unit: 19900 is 199.00 NOK. line_items: [{ quantity: 1, price_data: { currency: 'nok', unit_amount: 19900, product_data: { name: 'Example product' } } }], success_url: process.env.APP_URL + '/thanks', cancel_url: process.env.APP_URL + '/', }); res.redirect(303, session.url); } catch (e) { console.error('stripe failed:', e.message); res.status(502).send('The payment could not be started. Try again.'); } }); app.listen(3000); - 4
Add a button. After paying, the visitor lands on
public/thanks.html, a page you write yourself.<!doctype html> <meta charset="utf-8"> <title>Buy</title> <form method="post" action="/checkout"> <button>Pay with Stripe</button> </form> - 5
In Stripe, in test mode, copy the secret key (it starts with
sk_test_) and add a webhook tohttps://your-address/stripe/webhookfor the eventcheckout.session.completed; your address is on the project's page. Copy the webhook's signing secret (whsec_…). Set both under Variables, then publish. Until they are set the deploy stops and names them.
- A visit to the thank-you page proves nothing: the visitor can type the address without paying, or close the page before they get there. Mark an order as paid only when the webhook says so, and keep the event's
idin your own database, because Stripe can send the same event more than once. Some payment methods confirm later; for those, also handlecheckout.session.async_payment_succeeded. - To go live, swap in the live secret key (
sk_live_) and add a second webhook for the same address in Stripe's live mode. It has its own signing secret; the test one does not work for it. If you connect your own domain later, change the webhook's address in Stripe too. - This is your own Stripe account, separate from Hosait's billing. Stripe receives your customers' payment and e-mail details, so name it in your privacy notice.
Put an Expo app online: the web version and its API
An Expo app can run on phones and in the browser. Hosait hosts the parts that need a server: the browser version and the API it talks to. The apps for the App Store and Google Play are still built and submitted with Expo. You need an Expo project that already runs with npx expo start --web.
- 1
Let Hosait build the browser version. Put
hosait.jsonin the root of the repository. The build writes the finished pages todist, and Hosait serves them.{ "$schema": "https://hosait.com/schema/hosait.json", "runtime": "static", "build": "npx expo export --platform web", "output": "dist" } - 2
In
app.json, setweb.outputtostatic, and install the web packages withnpx expo install react-dom react-native-web @expo/metro-runtime. Hosait does not send an unknown address to the front page, so withstaticevery Expo Router page becomes its own file and reloading any page works.{ "expo": { "web": { "bundler": "metro", "output": "static" } } } - 3
Give the app the API's address in one variable. Under Variables, set
EXPO_PUBLIC_API_URLto the address of your API, then publish. Hosait passes variables that start withEXPO_PUBLIC_to the build, and Expo writes them into the pages.// The address comes from the variable you set under Variables in Hosait. const API = process.env.EXPO_PUBLIC_API_URL; export async function getItems() { const res = await fetch(API + '/items'); if (!res.ok) throw new Error('The API answered ' + res.status); return res.json(); } - 4
Run the API as its own Hosait project, an ordinary Node app or compose stack. A browser lets the web version call it only when the API allows that address, so set
WEB_ORIGINto the address of the web version. The apps on phones are not affected by this.const cors = require('cors'); // WEB_ORIGIN is the address of the browser version, for example https://my-app.hosait.com app.use(cors({ origin: process.env.WEB_ORIGIN })); - 5
Build and submit the phone apps with Expo (EAS). Give that build the same variable in
eas.json, and use your own domain for the API: an installed app keeps calling the address it was built with.{ "build": { "production": { "env": { "EXPO_PUBLIC_API_URL": "https://api.example.com" } } } }
- A change to an
EXPO_PUBLIC_variable needs a new publish. The value is written into the pages when they are built, so Hosait refuses to apply it by restart. - Anyone can read what is in the pages and in an app on a phone. Never put a secret key in an
EXPO_PUBLIC_variable; keep it in the API.
Add a “Deploy to Hosait” button to your README
A link that opens Hosait with your repository already chosen. A visitor whose GitHub account can reach the repository gets to its check in a few clicks. You need a repository on GitHub.
- 1
Put this in your
README.md. Replaceowner/namewith your repository. To start from a branch other than the default, add&branch=your-branchto the address.<a href="https://hosait.com/app.html?repo=owner/name"><img src="https://hosait.com/hosait-deploy-button.png" alt="Deploy to Hosait" width="260"></a> - 2
A visitor signs in or registers, connects GitHub if needed, and Hosait picks the repository and checks it. Nothing is published until they press publish.
- It works for repositories the visitor's GitHub account can reach: yours, your organisation's, or a copy they made. For a template repository, tell people to press “Use this template” on GitHub first.
- If the repository cannot be reached, the visitor is told so and picks another one.
Move to Hosait
Short guides for moving a project from another service. Each one says what to take with you and what you have to redo. Your code stays in your own repository; Hosait publishes from it.
From Heroku
Take with you: the code (already in a repository), the variables and the database. Redo: add-ons and extra processes from the Procfile become services in a compose file.
- 1
Put the app in maintenance mode with
heroku maintenance:onso nothing is written while you copy. Runheroku pg:backups:capture, thenheroku pg:backups:download, and turn the file into SQL withpg_restore --no-owner --no-acl -f dump.sql latest.dump. - 2
Create the project from your repository in Hosait and enter the variables from
heroku config. If the app has a database, add it as a service in a docker-compose file (see Docker Compose). - 3
Import
dump.sqlinto the project’s database with theimport_databasetool in the MCP server, and open the Hosait address. The live database starts empty, so nothing comes along unless you import it.
From Fly.io
Take with you: the code and the database. Redo: the secrets. Fly.io does not let you read a secret’s value back, so take it from where you made it, or make a new one, and add it as a variable in Hosait.
- 1
Open a connection to the database with
fly proxy(Fly’s guide for your type of database has the exact command) and make a dump withpg_dumpthrough it. - 2
Create the project from your repository in Hosait. Hosait reads the repository itself (see Detection), so
fly.tomlis not needed. Enter the variables and secrets. - 3
Import the dump with the
import_databasetool in the MCP server, check the Hosait address, and turn the Fly app off when everything works.
From Koyeb
Take with you: the code (in your repository), the variables and the database. Redo: Koyeb’s services and secrets, which you enter again as variables in Hosait.
- 1
Copy the environment variables from the service’s settings in Koyeb. A secret’s value is not shown again, so take it from where you made it. Make a dump of the database with
pg_dumpand the connection string from Koyeb. - 2
Create the project from your repository in Hosait and enter the variables. If the app has a database, add it as a service in a docker-compose file (see Docker Compose).
- 3
Import the dump with the
import_databasetool in the MCP server, check the Hosait address, and turn the Koyeb service off when everything works.
From Firebase Studio
Firebase Studio closes on 22 March 2027, and what is left in it is deleted for good. Take the code out first. Firestore, Authentication and the rest of Firebase keep working outside Firebase Studio, so an app on Hosait can keep using them.
- 1
Push the workspace’s code to a GitHub repository (the Git panel, or
git pushin the terminal), or download it. Environment files are not in the repository, so write down the variables you use. - 2
Create the project from the repository in Hosait and enter the variables, for example the Firebase keys from Project settings in the Firebase console.
- 3
Add your Hosait address under Authentication → Settings → Authorized domains in Firebase, so sign-in works from the new address.
From v0
v0 builds a Next.js app and can keep a GitHub repository in sync with it. Take with you: the code. Redo: the variables, which stay in v0 and Vercel.
- 1
In v0, connect a GitHub repository so the code is pushed to it. Write down the variables the app uses: the Neon database address,
BETTER_AUTH_SECRETif it uses Better Auth, andAI_GATEWAY_API_KEYif it calls models through Vercel’s AI Gateway. - 2
Create the project from the repository in Hosait and enter the variables. A Neon database works from Hosait with the same address. Set
BETTER_AUTH_URLto your Hosait address. - 3
Check sign-in and the pages that use the database. A note about Vercel Blob or the AI Gateway after the check means that part still needs a Vercel account.
From Base44
Base44 keeps an app’s data, sign-in and functions on its own servers, and the Base44 SDK in the code calls them. Moving the code does not move them.
- 1
Get the code out through Base44’s GitHub connection, or with
base44 eject(install the CLI withnpm install -g base44@latest; it needs Node.js 20.19 or newer). Eject makes a new Base44 project with the entity definitions and no data. - 2
Create the project from the repository in Hosait. The pages run on Hosait; data, sign-in and functions stay at Base44, so keep the Base44 account.
- 3
To leave Base44 completely, the backend has to be rebuilt: the entity definitions in the
base44/folder show which tables you need, and the data has to be exported separately. Hosait runs the result but does not convert it.
From Antigravity
Google points Firebase Studio users to Antigravity, an editor that works on a folder on your computer. Take with you: the code, which is already yours.
- 1
Put the folder in a Git repository and push it to GitHub, or upload the folder in the Hosait wizard.
- 2
Create the project in Hosait and enter the variables the app needs. For Firebase, add your Hosait address under Authentication → Settings → Authorized domains in the Firebase console.
When the Hosait address works, point your own domain to Hosait (see Custom domains under Operations) and only then turn the old service off.
Uptime and where Hosait runs
Hosait runs in one region: a data centre in Oslo, Norway. There is no second site, so an outage there affects every project. We don't promise a percentage. During the preview there is no uptime guarantee at all; from launch, Scale plans get an uptime target agreed in writing. Planned maintenance is announced at least 48 hours ahead. Redeploys of your own app can cause a short gap while the new version starts.