Skip to content
← Blog

Your app is a container: take it anywhere

On floo, an app is your own Dockerfile and standard Postgres, configured by one floo.app.toml in your repo. There is no floo SDK in your code. Here is what moves with you, what is floo-specific, and what you would replace if you ran the same image somewhere else.

floo team

TL;DR

A floo app is a container image built from your Dockerfile, talking to standard Postgres. floo adds the URL, sign-in, schedules, and rollback around it, not inside it.

  • floo builds every service from a Dockerfile in your repo. It does not generate one or swap in its own runtime, so the same image runs with docker run.
  • Your code reads plain environment variables: PORT, DATABASE_URL, REDIS_URL, and storage credentials for an S3-compatible API. There is no floo SDK to remove.
  • The floo-specific parts are small and listed below: floo.app.toml, injected variable names, sign-in headers, app API keys, and cron definitions.
  • floo db dump exports your database to a file in one command, and the Leave floo anytime guide covers the whole move.

Agents write a lot of software now, and a fair question before you host any of it is: what happens if we want to run this somewhere else? The answer should be in the repo, not in a sales call. This post walks through what a floo app is made of, using the public docs and the code that runs it.

What does floo actually run?

Your Dockerfile. The Dockerfiles guide says floo builds every service from a Dockerfile in your repo, and floo init does not write one for you. There are no buildpacks and no floo base image you have to use.

The image has to meet a short container contract:

  • Listen on $PORT on 0.0.0.0.
  • Answer at the service's route root within 60 seconds of starting.
  • Leave /healthz alone; floo reserves it.
  • Declare ARG and ENV for build-time public variables like NEXT_PUBLIC_* and VITE_*, because floo passes them as Docker build args.
  • Run migrations through migrate_command, not at boot.

That is the same shape most container hosts expect. One detail, stated plainly: when floo deploys your image, it appends one layer with a small launcher at /opt/floo/floo-launch. The layer leaves your files, ENTRYPOINT, and CMD as they were. When the container starts, the launcher decrypts your secrets and then starts your app. The image you build yourself from the same Dockerfile does not need the launcher.

Run the same image yourself

Because it is your Dockerfile, the usual commands work:

docker build -t my-app .
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e DATABASE_URL="postgresql://user:password@host:5432/app?sslmode=require" \
  my-app

Set the environment variables your code reads, the same ones floo would have injected. For local development, floo also has floo dev and floo run, which inject your dev database credentials into processes on your machine without Docker.

Your data is plain Postgres

A managed database on floo is standard PostgreSQL. Your app gets a postgresql:// connection string with sslmode=require in DATABASE_URL, plus PGHOST, PGPORT, PGDATABASE, PGUSER, and PGPASSWORD for libraries that want separate values. The Postgres guide notes that Rails, Django, SQLAlchemy, Prisma, pg, and libpq read it directly. Your schema, migrations, and queries are yours.

The other managed services follow the same rule:

  • Redis comes as a standard rediss:// URL in REDIS_URL. It is a cache with no backup (Redis guide).
  • Storage is a bucket you reach through an S3-compatible API with STORAGE_BUCKET, STORAGE_S3_ENDPOINT, and an access key pair. Code that uses an S3 client points at a different S3-compatible endpoint by changing those variables (Cloud storage guide).

What is floo-specific, and what would you replace?

Some parts of a floo app only mean something on floo. They are the parts that save you work, so it is worth knowing exactly what each one does.

  • floo.app.toml declares services, ports, resources, managed services, access, and crons (config spec). Elsewhere, you write your new host's config. The file is plain TOML in git, so it doubles as a list of what to recreate.
  • Injected variable names. floo sets DATABASE_URL, PG*, REDIS_URL, STORAGE_*, and its own FLOO_ENV, FLOO_APP_URL, FLOO_PUBLIC_HOST, and FLOO_APP_ID. Elsewhere, you set the same names yourself or rename them in code. Most are standard already.
  • Sign-in headers. With access_mode = "accounts", floo's gateway signs people in and sends X-Floo-User-Email, X-Floo-User-Id, X-Floo-User-Name, X-Floo-User-Role, and X-Floo-Auth-Method, after stripping any X-Floo-* headers the client sent (app sign-in). Elsewhere, you put another auth proxy in front that sets headers your app can trust, or add sign-in to your own code.
  • App API keys. Routes with access = "api_key" are checked by the gateway before a request reaches you (app API keys). Elsewhere, the check moves into your proxy or your app.
  • Cron jobs. [cron.<name>] runs a shell command on a UTC schedule inside a service's image (cron jobs). Elsewhere, any scheduler that runs the same command against the same image does the job.
  • Model calls. Code that calls FLOO_AI_BASE_URL uses floo's model endpoint. Elsewhere, you point it at a provider's endpoint and key.

The pattern holds across the list: the floo-specific parts live at the edge of your app, as config and headers, rather than as imports in your code. Moving means recreating that edge, not rewriting the app.

Platform features like deploy history, rollback, preview environments, and logs belong to floo, not to your image. Elsewhere you would use that host's version of each.

Getting your data out

  • You can read your connection string. floo env get DATABASE_URL --app my-app --reveal-secrets prints it (floo env). Managed connection strings are stored as readable config, not write-only secrets, so this works for them. It is a normal Postgres URL, so standard tools like psql and pg_dump accept it.
  • Export the database in one command. floo db dump --app my-app --env prod -o my-app.sql runs your local pg_dump (PostgreSQL 17 or newer) against the environment's database and writes a plain SQL file. Add --format custom for a file pg_restore reads. The dump leaves out owners and grants, so it restores into any Postgres.
  • Restores are run by floo on request. floo keeps change history for managed Postgres, and the backups guide explains how to ask for a restore. Storage keeps 30 days of object versions you can restore yourself.

The Leave floo anytime guide walks through the full move: code, database, environment variables, storage, running the same image elsewhere, and deleting the app.

Why build it this way

A container and a Postgres database are the most widely understood way to describe a running app. Agents know how to write a Dockerfile, every engineer can read one, and nearly every host can run one. floo's job is the part around that container that teams otherwise build themselves: a URL, sign-in, managed data, schedules, rollback, and an API an agent can drive. Keeping the app itself standard means that work never has to be undone.

If you want to see the shape for yourself, the config spec and the container contract are the two pages to read first.

Frequently asked questions

Does my app need a floo SDK or runtime library?

No. floo builds the Dockerfile in your repo and passes configuration as environment variables, such as DATABASE_URL and PORT. Your code reads them the way it would on any host. If you turn on floo sign-in, the gateway also sends the signed-in user as request headers.

Can I build and run my floo app somewhere else?

Yes. floo builds a standard image from your own Dockerfile, so docker build and docker run work on your machine or any host that runs containers. The app must listen on $PORT, which is the same contract most container hosts use. You set the environment variables floo would have injected, and replace the few floo-specific pieces: sign-in headers, cron schedules, and floo.app.toml itself.

Can I export my floo database?

Yes. floo db dump --app my-app --env prod -o my-app.sql runs your local pg_dump against the app's standard PostgreSQL database and writes the dump to a file you restore with psql or pg_restore. floo env get DATABASE_URL --reveal-secrets also prints the connection string, which any Postgres tool accepts. The Leave floo anytime guide walks through the whole move.

What is floo-specific in a floo app?

floo.app.toml, the names of the environment variables floo injects (DATABASE_URL, REDIS_URL, STORAGE_* and FLOO_*), the X-Floo-User-* sign-in headers when access_mode is accounts, app API keys enforced at the gateway, and [cron.<name>] schedules. Each one has a plain replacement on another host.

Get your app live.

read https://getfloo.com/agents.md and set me up on floo

Get an API key
Usage-based pricing. See plans →