# What an agent can do on floo, end to end

The whole loop an agent runs on floo through the HTTP API, the CLI, and the hosted MCP server: create a project, deploy, read logs, roll back, manage env vars and secrets, run crons, and issue keys. With the first-deploy times we measured on 2026-11-09 and the two steps that still need a person.

Canonical URL: https://getfloo.com/blog/what-an-agent-can-do-on-floo-end-to-end

## TL;DR

An agent can run the whole loop on floo: create a project, deploy, read logs, roll back, set env vars and secrets, run crons, and issue keys, through the HTTP API, the CLI, or the hosted MCP server.

- Every step below exists on `main` and in the public docs. Each section links the page an agent would read.
- We timed one first deploy on floo's dev stack on 2026-11-09: about 94 seconds of machine time from installing the CLI to a deployed URL.
- Build and rollout took 81.4 seconds of that, and the Docker build itself about 5. Rollout is most of the wait.
- Two steps still need a person: approving the agent's sign-in and adding credits. We did not time those.

An agent that builds software needs somewhere to run it, and it needs to keep running it after the first deploy: read the logs when something breaks, roll back, rotate a secret, add a schedule. This post lists each of those steps on floo, the call an agent makes for it, and the numbers we have actually measured. Nothing here is a benchmark against anyone else.

## Three ways in

floo has three control surfaces, and they share one set of keys and permissions.

- **The HTTP API** at `https://api.getfloo.com/v1`. Every operation is in the OpenAPI spec at `https://api.getfloo.com/openapi.json`. An agent with no CLI starts at [getfloo.com/agents.md](https://getfloo.com/agents.md), which walks it from a key to a live deploy.
- **The CLI.** Every command that produces output takes `--json`, and `floo commands --json` prints the whole command tree, so an agent can discover commands instead of guessing ([CLI discovery](https://getfloo.com/docs/cli/discovery)). Install is `curl -fsSL https://getfloo.com/install.sh | bash` ([install](https://getfloo.com/docs/guides/install)).
- **The hosted MCP server** at `https://api.getfloo.com/mcp`. Clients sign in with OAuth, which mints an org API key named after the client; revoking that key disconnects it. Named tools cover common operations, and `search_api`, `read_api`, and `write_api` reach any `/v1` operation ([MCP guide](https://getfloo.com/docs/guides/mcp)).

The [agent setup guide](https://getfloo.com/docs/guides/agent-setup) covers choosing between them.

## The loop, step by step

### Sign in and get a key

`floo auth login` uses a device flow: the CLI prints a code and a person approves it on their own device. An agent can also be handed a key with `floo auth login --api-key`. Keys come from `POST /v1/auth/api-keys` with a `read`, `write`, or `admin` scope, and a key can never exceed the role of the person who made it ([team access](https://getfloo.com/docs/guides/team-access)).

### Create a project

`floo init` writes `floo.app.toml`. It does not write a Dockerfile; the agent does that. `floo deploy --preflight --json` checks the config before anything is created. Over the API, `POST /v1/deploy/plan` creates nothing and answers with the next action: push, connect GitHub, create a GitHub repo, or create a repo floo hosts. `floo deploy --hosted` takes the last path and needs no GitHub account ([deploy without GitHub](https://getfloo.com/docs/deploy/without-github)). On MCP, the tools are `plan_deploy` and `create_app`.

### Deploy and wait

`floo deploy` builds, deploys, and waits until the deploy is live. Over the API, `POST /v1/apps/{app_id}/deploys` starts one and `GET /v1/apps/{app_id}/deploys/{deploy_id}?wait=` waits on its status. `floo status --wait` and the `get_deploy` MCP tool do the same ([floo deploy](https://getfloo.com/docs/cli/deploy), [floo status](https://getfloo.com/docs/cli/status)). Branch deploys and pull requests can get their own [preview environments](https://getfloo.com/docs/guides/preview-environments).

### Read logs

`GET /v1/apps/{app_id}/logs` filters by time, severity, service, cron, search text, environment, and deploy. The CLI has `floo logs query`, `floo logs tail`, and `floo logs build` for a deploy's build output. The MCP tool is `get_logs` ([logs guide](https://getfloo.com/docs/guides/logs)).

### Roll back

`floo deploys` lists what is live and which deploy IDs are valid targets. `floo rollback my-app <deploy-id> --yes`, `POST /v1/apps/{app_id}/rollback`, or the `rollback_deploy` MCP tool moves traffic back to that deploy's image. A rollback does not run `migrate_command` and does not restore config: env vars and secrets keep their current values ([releases and rollbacks](https://getfloo.com/docs/guides/rollbacks)).

### Manage env vars and secrets

`floo env set KEY --stdin --secret` stores a secret. Secrets are write-only: they cannot be read back, only overwritten. Plain config can be read with `floo env get`. The API is `POST /v1/apps/{app_id}/env` with `is_secret`, and the MCP tool is `set_env_var` ([environment variables](https://getfloo.com/docs/guides/environment-variables), [floo env](https://getfloo.com/docs/cli/env)).

### Schedule crons

A cron is a `[cron.<name>]` block in `floo.app.toml` with a UTC schedule and a shell command that runs in one service's image; every deploy syncs them. `floo cron list`, `floo cron show`, and `floo cron run` inspect and trigger them, and `POST /v1/apps/{app_id}/cron/{name}/run` queues a run. A run's output is in the logs with `floo logs query --cron <name>` ([cron jobs](https://getfloo.com/docs/guides/cron-jobs)).

### Issue keys for other programs

When another program needs to call the app, the agent creates a consumer and a key for it: `floo apps consumers create`, then `floo apps keys create`, or `POST /v1/apps/{app_id}/consumers/{consumer_id}/keys`. The key is shown once, and routes marked `access = "api_key"` check it at the gateway ([app API keys](https://getfloo.com/docs/guides/app-api-keys)).

## What we measured

On 2026-11-09 we timed one first deploy on floo's dev stack with CLI version 2026.11.09. The app was a single static `index.html` served by `python:3.12-alpine`. The org was already signed in and had credits, so the human steps were skipped. This is one run, not an average.

| Step | Time |
| - | - |
| Install the CLI with `install.sh` | 1.9 s |
| `floo init` | under 0.1 s |
| `floo deploy --preflight --json` | 0.4 s |
| `floo deploy --hosted`: plan, create the app, push | 9.1 s |
| Build and rollout until the deploy is live | 81.4 s |
| Total for `floo deploy` | 92.2 s |
| Install to deployed URL, machine time | about 94 s |

Two things stand out. The steps an agent drives directly, from install through push, take about 12 seconds. And of the 81.4 seconds of build and rollout, the Docker build took about 5; the rest was rolling the new service out. That is the number to watch as we keep working on deploy speed.

We have not measured rollback time, log query latency, or how long the human steps take, so we make no claims about them here.

## Where a person still comes in

An agent cannot run all of this alone, and it is better to know where it will stop:

- **Sign-in.** A person approves the device flow, or copies a floo API key from settings for the agent.
- **Credits.** floo has no free plan. Until the org has credits and a saved card, an agent cannot plan or create an app.
- **GitHub, if you use it.** Someone installs the floo GitHub App. The hosted path skips this.

After that, the loop above is the agent's to run. Start with [getfloo.com/agents.md](https://getfloo.com/agents.md) if your agent talks HTTP, or the [agent setup guide](https://getfloo.com/docs/guides/agent-setup) if it uses the CLI or MCP.

## FAQ

### How does an agent control floo?

Through any of three surfaces. The HTTP API at api.getfloo.com/v1 is described by an OpenAPI spec. The floo CLI returns JSON from every command that produces output. The hosted MCP server at api.getfloo.com/mcp signs in with OAuth and can reach any /v1 operation. All three use the same floo API keys and permissions.

### How long does a first deploy take on floo?

In one run we measured on floo's dev stack on 2026-11-09, a small static app took about 94 seconds of machine time from installing the CLI to a deployed URL. floo deploy took 92.2 seconds of that, and 81.4 seconds of it was build and rollout. Human steps such as signing up and adding credits were not timed.

### Can an agent roll back a bad deploy on floo?

Yes. POST /v1/apps/{app_id}/rollback, floo rollback, or the rollback_deploy MCP tool moves traffic back to an earlier deploy's image. A rollback does not run migrations and does not restore env vars, which keep their current values.

### What does a person still have to do?

Approve the agent's sign-in, or paste a floo API key, and add credits to the org. floo has no free plan, so an org without credits cannot plan or create an app. On the GitHub path, someone also installs the floo GitHub App.
