Skip to main content
From a SvelteKit 3 project on GitHub to a live app at https://<app>.getfloo.app, with managed Postgres, signed-in users, and your own domain. New to floo? Start with the Quickstart.

What your agent controls

floo builds the Dockerfile in your repository. Add one that specifies the runtime for your app:
  • The base image and the exact Node version.
  • System packages, such as ffmpeg or Chromium for headless browsing, each one apt-get install line.
  • The build steps and the start command.
  • More services from the same repository, such as a background worker or a cron job.
Declare services, managed Postgres, sign-in, and domains in floo.app.toml. Store secrets outside git.

1. Add a Dockerfile

Build with @sveltejs/adapter-node, which outputs a standalone Node server:
SvelteKit 3 takes its configuration in vite.config.ts, not svelte.config.js:
vite.config.ts
Dockerfile
The adapter’s server reads PORT and listens on 0.0.0.0 by default. PROTOCOL_HEADER and HOST_HEADER tell it the public URL from floo’s edge, which form actions need to pass SvelteKit’s cross-site request check. Add a .dockerignore listing node_modules, build, and .svelte-kit.

2. Initialize the floo config

Install the CLI and sign in: curl -fsSL https://getfloo.com/install.sh | bash, then floo auth login. An agent can run the same journey over the HTTP API instead, starting from getfloo.com/agents.md.
For a single-service SvelteKit app:
floo.app.toml
After adding Postgres, set migrate_command under [services.web] to your migration tool, such as "npx drizzle-kit migrate". Keep that tool in dependencies, not devDependencies, so npm prune leaves it in the image. It runs as a one-off job with the new image before traffic moves to it. A failed migration stops the deploy. Use expand-then-contract migrations to keep the schema compatible with both old and new code.

3. Connect the repo and deploy

floo builds from your GitHub repository, not local files, so commit first. floo deploy pushes the commit and waits until the dev URL is live. The first time, it stops with one link if the floo GitHub App can’t read the repository yet: a human opens it and installs the App on the account that owns the repository, then you run floo deploy again. See Give floo access to your GitHub repository.
No GitHub repository? floo deploy --hosted has floo host the repository. See Deploy without GitHub. When it’s done:
Your SvelteKit app is live at https://my-sveltekit-app.getfloo.app.Every git push origin main ships to dev.

4. Add a Postgres database

floo.app.toml
Preflight warns MANAGED_CREDS_TO_WEB because the web service receives the database credentials. That is expected when the web service queries the database. DATABASE_URL is injected at runtime. SvelteKit 3 exposes only the variables declared in src/env.ts, so declare it there. floo sets it when the server starts, not during vite build, so the schema allows it to be missing while building:
src/env.ts
src/lib/server/db.ts
src/routes/+page.server.ts
postgres connects on the first query and reads the TLS settings in the URL. Dev and prod each get a separate Postgres database and credentials, with no shared state.

5. Add per-user auth

Set access_mode = "accounts" and floo handles sign-in:
floo.app.toml
From the next deploy onward, floo’s gateway:
  • Redirects unauthenticated requests to a hosted login page.
  • Validates the session cookie on every request.
  • Injects identity headers into every request that reaches your SvelteKit server.
Read them once in a server hook, with no auth code, callback handlers, or session storage:
src/hooks.server.ts
src/app.d.ts
Then use locals.user in any load function, form action, or +server.ts route:
src/routes/dashboard/+page.server.ts
Locally, run floo dev --fixture-user (see section 7) or send the headers yourself with curl -H 'X-Floo-User-Email: you@example.com' .... Access modes and identity headers in full: App sign-in.

6. Add a custom domain

Declare the domain in floo.app.toml:
Commit and push, wait for that commit’s dev deploy to go live, then release it to prod and read the DNS records: Replace owner/repo with your GitHub repository. For a floo-hosted project, see Environments.
Wait for the prod deploy to finish, then read the DNS records:
Publish the traffic and certificate CNAME records that show prints, then watch activation:
With HOST_HEADER set, event.url carries the custom domain, so it needs no extra config. DNS setup and troubleshooting: Custom domains.

7. Local development with dev credentials

Runs dev_command locally with DATABASE_URL and readable env vars from the app’s dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Write-only secrets are withheld; supply separate local values when needed. Prod credentials never reach a local session. The database exists after the first deploy that declares [managed.default]. Before that deploy, floo dev starts without DATABASE_URL. To test signed-in flows, add --fixture-user:
floo dev then puts a proxy in front of each accounts-mode service that injects the same X-Floo-User-* headers floo’s gateway adds in production. The output table shows the raw service URL and the auth-proxied URL; use the auth-proxied one for any path that reads identity headers.

Common gotchas

  • /healthz is reserved. floo’s edge intercepts that exact path. Use /health or /livez.
  • --host 127.0.0.1 in dev_command. On macOS the dev server listens on ::1 by default, and the floo dev --fixture-user proxy reaches it at 127.0.0.1. Without the flag, proxied requests fail with an empty reply.
  • An undeclared variable is undefined. A variable floo injects reaches your code only if src/env.ts declares it. Without the declaration, postgres falls back to PG* defaults and fails with connection is insecure.
  • static: true for runtime values. A static variable is inlined at build time, when DATABASE_URL and secrets are not set. Leave static off for anything floo injects.
  • #lib, not $lib. SvelteKit 3 imports from src/lib through the #lib mapping in package.json, with the file extension: #lib/server/db.js.
  • Form actions return 403 “Cross-site POST form submissions are forbidden”. PROTOCOL_HEADER or HOST_HEADER is missing from the final stage, so the server thinks its origin is not the public URL.
  • Values for the browser. Declare them with public: true in src/env.ts and import them from $app/env/public. Without static: true, they are read when the server starts, so floo needs no build arg for them.

Next steps

App sign-in

Identity headers, access policies, and access modes in detail.

Environment variables

Secrets, build-time variables, and per-service values.

Dockerfiles

Layer order for fast pushes and recommended multi-stage builds.

Production environments

Dev vs prod, promotion, env overrides.