Skip to main content
Requires a project directory with source code and a GitHub repository. Without a Dockerfile, floo init offers to write one for a detected runtime. For your own GitHub repository: install the GitHub App, link that installation to your floo organization, then connect the repository to deploy. For a floo-hosted repository without your own GitHub account, use the hosted-project setup.

​
With your agent

An agent drives floo through the floo CLI, where every command supports --json, or through the HTTP API at https://api.getfloo.com/v1, starting from agents.md with every operation in openapi.json. The steps below use the CLI. Paste into Claude Code, Cursor, or any agent in your project.
Connect deploys the commit you pushed. Every push after that deploys automatically.

​
Yourself

​
1. Sign in to floo

Finish sign-in in the browser. If you belong to several floo organizations, switch to the one that should own this app before linking GitHub. Replace acme with its slug:

​
2. Give floo access to your GitHub repository

Open Install the floo GitHub App.
  1. Choose the GitHub account or organization that owns the repository. For acme/storefront, choose acme. Installing on your personal account does not grant access to acme’s repositories.
  2. Under Repository access, choose Only select repositories and select the repository you want to deploy. If the App is already installed, update its repository access to include this repo.
  3. Install or save. If GitHub requires organization-owner approval, wait for approval before continuing.
In the browser it opens, authorize floo with the GitHub login that can access that installation. If floo asks you to choose a GitHub account, select the repository’s owner. Wait for GitHub access confirmed; the CLI then reports Linked the floo GitHub App to your org. This links the installation to the floo organization selected in step 1. It does not deploy your app. If the browser does not open, run floo apps github setup --no-browser and open the printed link. An expired link needs a fresh setup command; retrying does not require uninstalling the GitHub App.

​
4. Prepare and push the app

From your project directory:
Edit the generated floo.app.toml to declare your services, ports, and managed services. See Configuration. App names are lowercase and hyphenated.
Push the configuration before connecting. The first deploy reads the commit already on GitHub.

​
5. Connect the repository and verify the deploy

Replace owner/my-project with the repository you selected in step 2:
connect creates the app and starts its first deploy. Before opening its URL, confirm that github status names the intended repository and branch and that deploys status reports a live deploy. GitHub setup confirmation alone does not mean the app is live. Every later push to the connected branch deploys to dev. To publish to production, run floo releases promote --app my-app.

​
If GitHub setup stops

For command flags and connection details, see the GitHub reference.
Do not bind a route to /healthz; floo reserves that path, so use /health or /livez (see the container contract).

​
Next

CLI commands

Env vars, databases, domains, rollbacks, and debugging a failed deploy.

How floo works

Config in the repo, deploys from GitHub, the CLI or the API as the operating surface.

Build with your stack

End-to-end guides for Next.js, Rails, FastAPI, Django, and Express.