Quickstart

This walks you from a fresh login to a deployed app with a database and a cache.

Prerequisites

• Node.js 20+ and the Flect CLI
• Docker and a container registry (GitHub Container Registry, Docker Hub, …) to build and push your image

1. Install the CLI

npm install -g @getflect/cli

2. Log in and point at the platform

flect login
flect config set gatewayUrl https://flect.cloud   # the hosted control plane
                                                  # (self-hosted: your gateway origin)

flect login opens your browser for SSO and stores an identity token in ~/.flect/config.json. gatewayUrl is the single origin the CLI talks to — the identity plane and the broker both derive from it. Confirm everything is wired:

flect whoami        # your identity + where you're pointed
flect doctor        # green-checks config, plane, broker, token, and scope

3. Scopes — where things live

Flect organizes everything as a tree: Org → Workspace → Project → Environment. Your login gives you an org; you create the rest with the noun commands, then pick an active context with flect use — resource and deploy commands target it.

flect org create --name Acme --slug acme
flect ws  create --org acme --name Web --slug web
flect proj create --org acme --ws web --name Site --slug site
flect ls                         # inspect the tree (active node marked)
flect use acme/web/site          # set the active context

flect ps prints the active context (scope, token, broker) at a glance.

4. Scaffold flect.toml

In your project directory:

flect init

This writes a starter flect.toml and adds flect.local.json / .flect/ to .gitignore:

name    = "myapp"
runtime = "node"
port    = 3000
scope   = "myapp/main/prod"      # reserved/ignored — deploy target comes from `flect use` (step 3)

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

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

• scope is reserved today; the deploy target is your active context (flect use, step 3).
• binding is the name your code uses: env.db('DB').
• name is the Flect resource it maps to.

See the flect.toml reference for every field.

5. Write your app

Your code only needs @getflect/sdk. It never sees a URL or a secret.

npm install @getflect/sdk

import { createEnv } from '@getflect/sdk'

const env = createEnv()

const db    = await env.db('DB')       // an official @libsql/client
const cache = await env.kv('CACHE')    // an official ioredis client

await db.execute('CREATE TABLE IF NOT EXISTS hits (n INTEGER)')
await cache.set('ping', 'pong')

Try it locally first — see Local development.

6. Deploy

Substrate providers must exist for your tenant

flect deploy provisions databases, KV, and stores through providers an operator registers once per tenant (which sqld/valkey/garage substrate backs each kind). If flect doctor warns providers — none registered, ask your platform operator to register them before deploying a resource-backed app; apps with no bindings deploy without providers.

Build and push your image, set it in flect.toml (or pass --image on the app entry), then:

docker build -t ghcr.io/you/myapp:1.0.0 .
docker push ghcr.io/you/myapp:1.0.0

flect deploy

flect deploy reads flect.toml, targets your active context (from flect use in step 3), provisions any missing resources, binds them to your project, and deploys your container to the cluster behind Traefik with an auto-issued TLS certificate.

scope: acme/web/site (active context)
✓ provisioned  database  myapp-db-a1b2c3d4
✓ provisioned  kv        myapp-cache-e5f6g7h8
✓ deployed     myapp     https://myapp-3f9k2a.up.flect.run   running

At deploy time Flect injects exactly two env vars into your container — FLECT_TOKEN and FLECT_BROKER_URL. createEnv() uses them to resolve each binding to a scoped, short-lived connection at runtime.

Next steps

• Local development — flect dev + createEnv() offline.
• Examples — small single-purpose apps (a database, a KV store).
• CLI reference · SDK reference · flect.toml