> ## 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.

# Config as Code

> Keep app shape in git so humans and agents share one source of truth.

floo is config-as-code by design. `floo.app.toml` is the source of truth for app shape, not for every piece of durable state.

This is not just a preference. It is what makes agent-native deployment workable. Agents need a deterministic, reviewable file that describes desired state.

## What lives in config

Use repo-backed config for app shape:

* app and service definitions
* routing
* ports and ingress
* build settings
* service paths
* migrate and dev commands
* managed credential attachments

Example:

```toml theme={null}
[app]
name = "my-app"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
```

Provision durable resources separately:

```bash theme={null}
floo services add postgres --app my-app
```

## What stays outside config

Some state is intentionally managed outside the repo:

* env vars and secrets
* managed Postgres, Redis, and Storage provisioning
* custom domains
* access grants and team membership
* billing
* API keys
* destructive actions like app deletion

These either should not be committed to git, carry data, or depend on live, interactive workflows. Managed-service changes still leave a reviewable record in `.floo/services.lock`, but the platform DB is authoritative.

## Why this matters for agents

When config lives in the repo:

* agents can read and edit it directly
* changes are reviewable in pull requests
* the deploy surface is deterministic
* there is no second config system to reverse-engineer

If the dashboard could mutate repo-backed config independently, the agent would no longer know which state was real.

## The dashboard is a window

The dashboard is for visibility into the live system. It shows releases, logs, settings, team state, and usage.

It does not become a competing source of truth for app shape that already lives in `floo.app.toml`.

## Recommended workflow

1. Write or update config in the repo.
2. Review it in git.
3. Connect GitHub if needed.
4. Push changes and watch the deploy.

```bash theme={null}
floo init my-app
floo preflight --json
floo apps github connect owner/repo
git push origin main
```

<CardGroup cols={2}>
  <Card title="Configuration" href="/docs/guides/configuration">
    Learn the file shapes and common config patterns.
  </Card>

  <Card title="Dashboard vs CLI" href="/docs/guides/dashboard-vs-cli">
    See how the read/write split works in practice.
  </Card>
</CardGroup>