flect.toml reference

flect.toml lives at the root of your project. It declares where the project lives (its scope), the bindings your code resolves (env.db('DB')), the apps to deploy, and how they’re wired. flect deploy reads it to provision, bind, and deploy. The SDK never reads this file — it’s a CLI/deploy artifact.

Scaffold one with flect init.

Single-app form

The common case: one app, a top-level name, a scope, and its bindings.

name    = "myapp"
runtime = "node"
port    = 3000
# target set with `flect use` (see Scope below); no scope field needed here

[[databases]]
binding        = "DB"
name           = "myapp-db"
migrations_dir = "migrations"

[[kv]]
binding = "CACHE"
name    = "myapp-cache"

[[stores]]
binding = "FILES"
name    = "myapp-uploads"

Field	Description
name	Project / app name (required unless using [app]).
scope	Reserved — deploy target comes from flect use (see Scope below).
region	Deployment region — only eu exists today (the default); reserved for more.
runtime	Informational (e.g. node).
port	Port your container listens on.

Scope — where the project lives

Every resource and app lands in a scope (org → workspace → project → environment). Tenancy is managed by the identity plane (org-service); create the tree with flect org/ws/proj/env and pick the target with flect use:

flect org create --name Acme --slug acme
flect ws  create --org acme --name Web --slug web
flect proj create --org acme --ws web --name Notes --slug notes
flect use acme/web/notes/prod        # this is the deploy target

flect deploy targets your active context (from flect use), sent to the broker as X-Org-Id + X-Flect-Scope. Override it for one deploy with --scope <scopeId>. Precedence: --scope flag > active context.

The top-level scope = "…" field in flect.toml is reserved for a future org-service path resolution; today the deploy target comes from flect use (or --scope), not the toml field.

Bindings

Bindings connect a name your code uses to a Flect resource. The three kinds map to three code accessors:

Section	Kind	Accessor
[[databases]]	database (sqld/libsql)	env.db(binding)
[[kv]]	KV (Valkey/redis)	env.kv(binding)
[[stores]]	object storage (Garage/S3)	env.store(binding)

Each entry takes:

Field	Required	Description
binding	yes	The name your code passes to env.db()/kv()/store(), e.g. "DB".
name	yes	The Flect resource it maps to (the public ref from flect <kind> create).
migrations_dir	no	Databases only — directory holding your SQL migration files.

Binding names must be unique across all kinds in a project.

[[databases]]
binding = "USERS_DB"
name    = "users-db"

[[databases]]
binding = "LOGS_DB"
name    = "logs-db"

[[kv]]
binding = "SESSION"
name    = "session-cache"

Resource names come from flect db create / flect kv create / flect store create, which print the exact ref to paste here. If a named resource doesn’t exist yet, flect deploy provisions it.

App-group form

To deploy several apps that share a domain (e.g. an API plus a sidecar service), use [app] + [[apps]] instead of a top-level name.

[app]
name   = "clave"
domain = "clave-api.up.flect.run"   # optional: shared / custom domain

[[apps]]
name   = "clave-api"
image  = "ghcr.io/you/clave-api:1.0.0"
port   = 3000
public = true                       # owns the domain (at most one app)

[[apps]]
name   = "auth-service"
image  = "ghcr.io/you/auth:1.0.0"
expose = "/v1/auth"                 # mounted at a path under the shared domain

[vars]
OIDC_ISSUER = "https://nesskey.com"

[[databases]]
binding = "DB"
name    = "clave-db"

[[services]]
binding = "AUTH_SERVICE"            # inject the sibling app's URL as this env var
app     = "auth-service"

[[apps]] fields

Field	Description
name	App name (required).
image	Container image (registry/name:tag).
port	Container port.
public	true to own the domain — only one app may be public.
expose	Mount at a path prefix under the shared domain (e.g. /v1/auth).
replicas	Instance count.
cpuMhz	CPU allocation, MHz.
memoryMb	Memory allocation, MB.

[vars]

Plain environment variables to set on the app(s) at deploy time. (Secrets should come from your platform’s secret store, not here.)

[[services]]

Wire one app to another: inject the resolved URL of app app into the environment as the variable named by binding.

Field	Description
binding	Env var name to inject.
app	The sibling app whose URL is injected.

[page] — a static site

A page is a git repository the platform clones, builds and serves (no runtime, no bindings). The build runs in the cluster, so nothing depends on your machine.

[page]
name     = "docs"
repo     = "https://github.com/acme/docs"   # required
ref      = "main"                            # branch, tag or commit (default: main)
template = "docs"                            # Starlight docs template
title    = "Acme Docs"
github   = "https://github.com/acme/docs"
# domain = "docs.acme.com"                   # optional custom domain (else a generated hostname)

Deploy it with flect page deploy. If the repo has its own astro.config.* or a [page.build] command, that build runs instead of the template.

Each build is published to its own immutable directory and swapped in atomically, so a failed build never touches the live site and flect page rollback is a pointer switch rather than a rebuild.