> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview Environments

> Create pull request previews and command-line preview sandboxes with isolated managed services and preview database branches.

Preview environments are short-lived deploys with their own URL and their own preview-owned managed resources. Open a pull request, and floo deploys that branch to a preview URL. Agents can also create the same kind of sandbox from the CLI for a pushed remote branch. Push again, and the same preview updates in place. Delete the preview, close the PR, or let the TTL expire, and floo tears it down.

The important part: a preview does not reuse floo-managed dev or prod Postgres credentials. When a preview has managed Postgres attached, floo creates a **preview database branch** for that preview.

## Enable Previews

Enable pull request previews in `floo.app.toml`:

```toml theme={null}
[preview]
enabled = true
ttl_hours = 72
```

Commit and push the config. The next pull request creates or refreshes a preview environment when GitHub sends the PR webhook.

`ttl_hours` controls how long an idle preview stays around. Closing or merging the PR tears it down earlier.

## Create A Sandbox From The CLI

Use `floo previews up` when an agent needs an isolated sandbox for a feature branch before opening or relying on a pull request preview:

```bash theme={null}
git push origin feat/foo
floo previews up --app my-app --branch feat/foo --wait
```

The command deploys GitHub source only. It never uploads local dirty files or an archive from your checkout, so push the branch or pass a remote ref before creating the sandbox.

Useful lifecycle commands:

```bash theme={null}
floo previews list --app my-app
floo previews status --app my-app feat/foo
floo previews logs --app my-app feat/foo --follow
floo previews delete --app my-app feat/foo --yes
```

The preview argument can be the exact slug, a preview URL, the source branch, or `#123` when that PR number resolves to one preview.

Agents should use `--json` for stable output:

```bash theme={null}
floo previews up --app my-app --branch feat/foo --wait --json
```

JSON output includes the app, preview slug, `source_branch`, `deploy_id`, status, URL, expiry, `database_branches`, and `dev_prod_untouched: true`. `--wait` exits non-zero when the deploy fails. Managed-resource isolation failures surface as `PREVIEW_MANAGED_SERVICE_ISOLATION_UNAVAILABLE`; fix the attached managed service state and retry after pushing a new commit or rerunning the command.

Deleting a preview sandbox tears down only preview-owned Cloud Run services, managed resources, gateway routes, and env vars. Dev and prod resources are untouched.

## Preview Database Branches

A preview database branch is preview-owned managed Postgres state. It is isolated from dev, prod, and other previews. Migrations, reviewer changes, and agent experiments land in that preview branch only.

V1 preview database branches are branch-like isolation on floo's managed-resource substrate. They are not raw production clones, arbitrary point-in-time clones, or provider-native copy-on-write branches. True provider-backed branching is tracked separately in [getfloo/floo#733](https://github.com/getfloo/floo/issues/733).

Use the CLI to inspect the branch behind a preview:

```bash theme={null}
floo db branches list feat-db-abcde --app my-app
floo db branches show feat-db-abcde --app my-app --name default
```

The preview argument can be the preview slug, a preview URL, the source branch, or `#123` when that PR number resolves to one preview.

Use `--json` when an agent needs stable fields:

```bash theme={null}
floo db branches list feat-db-abcde --app my-app --json
```

JSON includes the app, preview context, `database_branches`, `source_environment`, `hydration_mode`, `resource_status`, `schema_name`, reset eligibility, and expiry. It never includes plaintext database credentials.

## Reset A Preview Branch

Reset drops and recreates only the selected preview database branch. Dev and prod are untouched.

```bash theme={null}
floo db branches reset feat-db-abcde --app my-app --name default
```

In automation, confirm explicitly:

```bash theme={null}
floo db branches reset feat-db-abcde --app my-app --name default --yes --json
```

Preview reset is tier 2. It destroys preview-only data, but it does not touch durable dev or prod data. Dry-run shows the same scope without calling the API:

```bash theme={null}
floo --dry-run db branches reset feat-db-abcde --app my-app --name default
```

Reset works only for ready preview-owned managed Postgres branches. It is blocked when the preview has no managed Postgres attachment, when the branch is not ready, or when the data belongs to dev, prod, Redis, Storage, or an external database.

## Choose Preview Data

Use `[preview.data]` to choose how a new preview branch starts.

### Empty

`empty` is the default. floo creates a fresh preview database branch and copies no data.

```toml theme={null}
[preview.data]
mode = "empty"
```

Use this for apps that can boot from migrations alone.

### Seed

`seed` runs your seed command once after migrations and before the preview is marked live.

```toml theme={null}
[preview.data]
mode = "seed"
seed_command = "bin/rails db:seed"
```

The command runs in a preview-scoped one-off job with preview env vars. Pushing another commit to the same PR reuses the preview data unless you change the preview data policy.

### Clone Dev

`clone-dev` copies managed Postgres dev data into the preview branch before migrations run.

```toml theme={null}
[preview.data]
mode = "clone-dev"
```

Use this when a reviewer needs realistic dev data but must be isolated from the actual dev database. This mode copies attached managed Postgres only.

## Unsupported Modes

These are deliberately not V1 behavior:

* Raw prod clone.
* Sanitized prod clone until the admin-gated runner exists.
* Redis copy or reset.
* Storage copy or reset.
* Merging preview database changes back into dev or prod.
* Instant copy-on-write branches from arbitrary points in time.

If a config asks for unsupported data behavior, floo fails closed instead of silently using dev or prod credentials.

## Multi-Service Apps

Preview branches follow the same managed credential attachment rules as dev and prod. Attach managed Postgres only to the services that need it:

```toml theme={null}
[services.api.env]
managed = ["postgres"]

[services.web.env]
managed = []
```

If no service declares `managed`, legacy apps receive managed credentials in every service. Once any service declares `managed`, omitted services receive none.

## Troubleshooting

| Symptom                                                 | Meaning                                                          | What to do                                                                                                        |
| ------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `floo db branches list` shows no branches               | The preview has no floo-managed Postgres attachment              | Add managed Postgres with `floo services add postgres --app my-app`, then attach it with `managed = ["postgres"]` |
| Reset is blocked                                        | The branch is not ready or is not preview-owned managed Postgres | Re-run `floo db branches show ... --json` and inspect `reset_blocked_reason`                                      |
| Preview creation fails before deploy                    | floo could not provision isolated managed resources              | Fix the managed-service state and push another commit                                                             |
| `clone-dev` works for Postgres but not Redis or Storage | Redis and Storage copy modes are not implemented                 | Use app-level seed logic or keep those resources empty in previews                                                |

## Related

* [Managed Services](/guides/managed-services)
* [Databases](/guides/databases)
* [`floo previews`](/cli/previews)
* [`floo db`](/cli/database)
* [Config Spec](/reference/config-spec#preview)