https://<app>.getfloo.app, with server-rendered pages, managed Postgres, signed-in users, and your own domain.
New to floo? Start with the Quickstart.
What your agent controls
floo builds theDockerfile in your repository. Add one that specifies the runtime for your app:
- The base image and the exact Node version.
- System packages, such as
ffmpegor Chromium for headless browsing, each oneapt-get installline. - The build steps and the start command.
- More services from the same repository, such as a background worker or a cron job.
floo.app.toml. Store secrets outside git.
1. Add a Dockerfile
Server rendering needs the Node adapter in standalone mode:astro.config.mjs
Dockerfile
PORT from the environment. HOST=0.0.0.0 makes it listen on every interface, which floo needs to reach it. Add a .dockerignore listing node_modules and dist.
For a fully static Astro site, keep the default output: "static" and serve dist/ from a small web server image that listens on $PORT.
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.
floo.app.toml
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, and copy its config and migration files into the final stage. 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.
floo deploy --hosted has floo host the repository. See Deploy without GitHub.
When it’s done:
Your Astro app is live at
https://my-astro-app.getfloo.app.Every git push origin main ships to dev.4. Add a Postgres database
floo.app.toml
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. Read it from process.env, which the Node server sees when it starts. import.meta.env is filled in at build time, when the variable is not set:
src/lib/db.ts
src/pages/index.astro
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
Setaccess_mode = "accounts" and floo handles sign-in:
floo.app.toml
- Redirects unauthenticated requests to a hosted login page.
- Validates the session cookie on every request.
- Injects identity headers into every request that reaches your Astro server.
src/middleware.ts
src/env.d.ts
Astro.locals.user in any page or endpoint:
src/pages/dashboard.astro
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 infloo.app.toml:
owner/repo with your GitHub repository. For a floo-hosted project, see Environments.
show prints, then watch
activation:
site in astro.config.mjs to the custom domain so canonical URLs and the sitemap use it. DNS setup and troubleshooting: Custom domains.
7. Local development with dev credentials
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
/healthzis reserved. floo’s edge intercepts that exact path. Use/healthor/livez.--host 127.0.0.1indev_command. On macOS the dev server listens on::1by default, and thefloo dev --fixture-userproxy reaches it at127.0.0.1. Without the flag, proxied requests fail with an empty reply.--ignore-lockindev_command. When an agent runsastro dev, Astro moves the server to the background and the command exits, sofloo devreports the service stopped.--ignore-lockkeeps it in the foreground.HOST=0.0.0.0in the final stage. The standalone server bindslocalhostotherwise, which floo cannot reach.process.env, notimport.meta.env, for runtime values.import.meta.envis replaced at build time. floo passes onlyNEXT_PUBLIC_*,VITE_*, andREACT_APP_*to the build.- Prerendered pages. A page with
export const prerender = trueis built once, so it cannot read identity headers or query the database per request.
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.