Configuration

RondoFlow reads all of its configuration from a single .env file at the project root. Every package — the UI, the server, and shared code — loads from that one file, so there is just one place to look.

npm run setup generates .env from .env.example and fills in a random BETTER_AUTH_SECRET for you. You then edit it to add Claude credentials and any optional providers/nodes.

There are two ways to set values:

• The .env file — best for the required server settings (database, auth, networking) and for first boot.
• Settings → Credentials in the app — an encrypted, in-app credentials manager for provider keys, OAuth secrets, and SMTP. Values saved here are stored encrypted in the database and override the matching .env value at boot. More on this below.

Required variables

These three must be present for the server to start and authenticate users.

DATABASE_URL=postgresql://rondoflow:rondoflow_dev@localhost:5432/rondoflow
BETTER_AUTH_SECRET=<random-hex>
BETTER_AUTH_URL=http://localhost:3001

Networking

These set where the server listens and which origin it trusts. The defaults work for local development; change them when you serve the UI or API from a different host or port.

PORT=3001
UI_ORIGIN=http://localhost:3000

Claude authentication

Assistants (agents) run through the Claude Code CLI, which the server starts (spawns) as a child process. You must provide one of two credentials:

# Provide ONE of the two
ANTHROPIC_API_KEY=
CLAUDE_CODE_OAUTH_TOKEN=

To get a setup token, run:

claude setup-token

Optional providers

RondoFlow can also run assistants on OpenAI and Perplexity, and run Sakana AI transform nodes. Add a key for whichever you want to use — leave the rest unset.

If an assistant is configured for a provider whose key is missing, the run fails with a clear message — for example “OPENAI_API_KEY is not configured. Add it in Settings → Credentials (OpenAI access).” See Providers for per-provider details.

OAuth sign-in (optional)

Leave these empty to disable the corresponding sign-in button. When set, RondoFlow rebuilds its auth layer automatically, so GitHub/Google sign-in starts working without a server restart.

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Email node (SMTP)

The canvas Email card (node) sends a workflow’s combined output as an HTML email. It is opt-in — the card ships disabled, so building a workflow never sends mail until you turn it on. To make it work, configure an SMTP transport with these variables:

SMTP_HOST=
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=
SMTP_FROM=

SMTP can also be managed at runtime in Settings → Credentials (group SMTP); a DB-stored value overrides .env at boot, just like the other credentials. The Email node and its API are covered in the Data nodes guide and the Workflows guide.

First-admin bootstrap

RondoFlow is invite-only — self-registration is disabled, so an administrator creates every account. These variables seed the very first admin so you are not locked out of a fresh install. See Users & Roles for the role model and inviting people.

RONDOFLOW_ADMIN_EMAIL=
RONDOFLOW_ADMIN_PASSWORD=
RONDOFLOW_ADMIN_NAME=Administrator

This runs at seed time — during npm run db:seed (and npm run setup, which seeds). It is idempotent: if the account already exists it just ensures the role is admin.

Tuning variables

These adjust runtime behavior. All are optional and have sensible defaults.

Spawn timeouts & teardown

These protect against a hung Claude CLI process (a stalled network, an unanswerable permission prompt, an infinite loop) and control whether in-flight runs survive a disconnect. All times are in milliseconds.

External folders

There are also optional variables for External Folders — EXTERNAL_FOLDERS_HOST_PATH (default ./external) and EXTERNAL_FOLDERS_CONTAINER_ROOT (default /external) — covered in that guide.

Spend cap (not an env var)

Looking for a budget variable? The global per-run spend cap (forwarded to the CLI as --max-budget-usd) is not an environment variable. It is the “Max Budget” setting in the app, stored on the canonical global Safety Rule (policy) row and managed via the budget endpoint. null means no cap; the maximum is 1000 USD. See Security for how budgets resolve.

In-app credentials manager

Open Settings → Credentials to manage provider keys, OAuth secrets, and SMTP without editing files. It is backed by the /api/settings/credentials route and stores values encrypted in the database.

It manages the same keys as .env, grouped by provider:

How it behaves:

• Masked, never returned in full. The status endpoint reports only whether each credential is set and a masked preview (for example ••••a1b2). Secrets are never sent back to the browser. Non-secret values (the OAuth Client IDs, the SMTP host/port/secure/username/from) are shown in full so you can confirm them.
• Source is labeled. Each field shows whether the value is Saved (the API source db — stored in the database) or From .env (the source env — read from the file), so you always know where a value comes from.
• Database overrides .env. A value saved in the manager takes precedence over the matching .env variable at boot and on save. Most changes apply immediately — saving a provider key takes effect on the next run, and saving OAuth credentials rebuilds the auth layer without a restart.
• Clear to fall back. Clearing a field deletes the stored value and restores the original .env value (if any).

Next steps