Configuration Reference

Every key fymo.yml supports, its type, its default, and how $ interpolation resolves it.

fymo.yml lives at your project root and loads once, at startup. The class that handles it, ConfigManager, lives in fymo/core/config.py.

The file itself is optional. Every section below has a sensible default, so a project with no fymo.yml at all still boots. It just runs with auth off and jobs on the in-process threaded provider.

Each section loads through its own getter, like get_auth_config() or get_jobs_config(). An explicitly null section, auth: with nothing underneath, behaves the same as a missing one. Both resolve to {}.

Env var interpolation

${VAR} and ${VAR:-default} placeholders get resolved directly in the raw YAML text. This happens before yaml.safe_load ever parses it, and it happens once for the whole file, not per section. So a placeholder works the same whether it sits at the top level or three levels deep inside auth.providers.

name: ${APP_NAME}
description: ${APP_DESC:-a fymo app}

auth:
  providers:
    - type: oidc
      issuer: ${OIDC_ISSUER}

• ${VAR} is required. If VAR isn’t set, config loading raises ConfigurationError naming the variable. It never silently falls back to loading the literal string ${VAR}.
• ${VAR:-default} falls back to the given default when VAR is unset. That fallback only evaluates when needed, so in ${A:-${B}}, B is never touched if A is already set.
• An empty default (${VAR:-}) resolves to an empty string, not an error.

Literal braces and malformed placeholders

A default can contain literal braces. ${VAR:-{"a":1}} resolves to {"a":1}, because brace matching counts nesting depth instead of stopping at the first closing brace.

An unterminated ${ raises ConfigurationError at load time. So does a malformed variable name like ${123bad}. Either way, the error names the problem.

Every resolved value gets spliced back into the YAML text as an explicit double-quoted scalar, never as a raw substring. So an env var can’t restructure your config, even if its value contains a newline followed by something that looks like a new YAML key, like admin: true. It always comes back out as the literal string it was. This is what makes interpolation safe to use with values you don’t fully control.

Typed values from strings

Every interpolated value is a plain YAML string. ${VAR} never becomes a real bool or int just because the variable holds text like “true” or “60”. That matters most for booleans: a bare bool("false") in Python evaluates to True, since any non-empty string is truthy. A config value like auth.enabled: ${AUTH_ENABLED} resolving to the string “false” would otherwise silently turn auth on.

Fymo prevents this with parse_bool(), used for every boolean key in fymo.yml:

• auth.enabled
• remote.explicit_optin
• security.headers.enabled
• limits.rate_limit.enabled
• limits.rate_limit.trust_proxy

Input	Result
Python True / False	passed through unchanged
"true" / "TRUE" / " True " (case- and whitespace-insensitive)	True
"false" / "FALSE" / " False "	False
anything else ("yes", "1", "", a non-string, non-bool)	raises ConfigurationError naming the field and the value

Numeric keys like limits.max_body_bytes and limits.rate_limit.requests_per_minute don’t need this treatment. Plain int(...) already does the right thing here, since int("60") behaves exactly as expected.

Top-level keys

Key	Type	Default
name	string	"Fymo App"
version	string	none (informational only)
description	string	none (informational only)

Your own code can read version and description back through ConfigManager.get(...) if it needs them. Nothing in the framework itself enforces or uses those two keys.

routes

routes:
  root: index.index
  resources:
    - posts
    - name: admin
      soft_nav: false
  about: pages.about

Key	Meaning
root	controller.action for /.
resources	A list of resource names, each expanded into index/show/new/edit/create/update/delete routes. An entry can be a bare string, or {name, soft_nav} to turn off SPA-style client navigation for that resource (soft_nav defaults to true).
any other key	Treated as an explicit route: a string value is controller.action, an object value is passed through as-is.

limits

limits:
  rate_limit:
    enabled: true
    requests_per_minute: 60
    paths:
      "/_fymo/remote/": 30
    trust_proxy: false
  max_body_bytes: 10485760

Key	Type	Default
rate_limit.enabled	bool	true in production, false in dev
rate_limit.requests_per_minute	int	60
rate_limit.paths	map of path prefix to int	{} (longest matching prefix wins over the default)
rate_limit.trust_proxy	bool	false
max_body_bytes	int	10485760 (10 MB)

The rate limiter runs as a per-process, per-client-IP token bucket, one bucket per matched rule. There’s no sharing across worker processes.

rate_limit.trust_proxy controls whether the first hop of X-Forwarded-For is trusted as the client IP. Only enable it behind a reverse proxy that actually overwrites that header, since otherwise a client could spoof its own rate-limit bucket. The same flag also decides whether X-Forwarded-Proto is honored when resolving the request’s scheme, which feeds both the HSTS header below and the session cookie’s Secure flag.

security

security:
  headers:
    enabled: true
    extra:
      - ["Content-Security-Policy", "default-src 'self'"]

Key	Type	Default
headers.enabled	bool	true
headers.extra	list of [name, value] pairs	[]

With headers.enabled on, every response gets four defaults automatically:

• X-Content-Type-Options
• X-Frame-Options
• Referrer-Policy
• Permissions-Policy

In production (dev=False), two more apply on top. Both are skipped entirely in dev:

• Content-Security-Policy-Report-Only, with a default-src 'self' baseline. Added only if headers.extra doesn’t already set a CSP of either kind.
• Strict-Transport-Security, added when the resolved request scheme is https. That resolution honors X-Forwarded-Proto only if limits.rate_limit.trust_proxy is on.

A header already present in the response from your own handler is never overwritten by these defaults.

auth

auth:
  enabled: true
  user_store: fymo.auth.store.SqliteUserStore
  email_sender: fymo.auth.email.LoggingEmailSender
  providers:
    - password

Key	Type	Default
enabled	bool	false
user_store	dotted class path	fymo.auth.store.SqliteUserStore
email_sender	dotted class path	fymo.auth.email.LoggingEmailSender
providers	list of provider entries	[password]

A provider entry can be a bare built-in name:

• password
• google
• oidc
• clerk

Or it can be an object: a type key for a built-in provider, or a class key for a dotted path to your own. Either way, it can carry whatever extra options that provider’s constructor takes.

Add required: auto to an entry to skip it entirely when the provider isn’t configured, instead of crashing on a missing secret.

Authentication

Full provider config, the session cookie format, and how to write a custom UserStore or AuthProvider.

jobs

jobs:
  provider: threaded

jobs:
  provider:
    type: procrastinate
    env_var: DATABASE_URL

Key	Type	Default
provider	bare string, or {type/class, ...opts}	threaded

threaded runs jobs in-process, with no external dependency. A job is lost if the process restarts mid-run.

procrastinate is a durable, Postgres-backed queue instead, meant to be picked up by a separate fymo jobs-worker process. Using it needs the procrastinate extra installed, plus a database, read from DATABASE_URL by default.

broadcasts

broadcasts:
  provider: postgres

Key	Type	Default
provider	bare string, or {type/class, ...opts}	postgres

Same string-or-object shape as jobs.provider. postgres is currently the only built-in.

remote

remote:
  explicit_optin: true

Key	Type	Default
explicit_optin	bool	false

With explicit_optin off (the default), every public, type-annotated top-level function in app/remote/*.py is exposed to the browser. Turning it on requires @remote on each function you want reachable. Everything else in that file stays server-only.

storage

storage: local

storage:
  provider: local
  root: data/uploads

Key	Type	Default
provider (bare string form), or provider/class (object form)	string / dotted path	none, required if used

Unlike jobs, broadcasts, and auth, there is no fallback provider here. Leaving storage: out of fymo.yml fails at startup if media: is configured. Silently writing to local disk is exactly the kind of default that works fine in dev, but quietly loses data in production.

Storage and Media

The StorageProvider interface, byte-range reads, and writing a custom provider.

media

media:
  - prefix: /media/videos/
    dir: data/videos
    extensions: [webm]

Key	Meaning	Required
prefix	URL path prefix requests are matched under.	yes
dir	Storage-key namespace files are resolved from, through the configured storage: provider.	yes
extensions	Allowed extensions, lowercase, no leading dot. Anything else gets a 400.	no, defaults to none allowed

media: is a list, defaults to []. Each entry becomes a byte-range-aware GET route, useful for video and audio scrubbing, with no hand-written WSGI handler needed.

A prefix under the reserved /dist/ or /assets/ paths doesn’t fail the build, it only prints a warning. Those routes are matched first, so a prefix there would never actually get reached.

logging

logging:
  destination: file
  file: log/fymo.log
  level: info
  format: json

Key	Values	Default
destination	terminal, file	terminal
file	path, required if destination: file	none
level	debug, info, warning, error	info
format	text, json	text in dev, json in prod

An unrecognized value in any of these raises ValueError naming the key, failing fast at startup instead of silently logging somewhere unexpected.

Logging

What flows through fymo’s single root-logger handler, and the shape of request and job log lines.

The identity secret

FYMO_SECRET isn’t a fymo.yml key, it’s read straight from the environment. But it governs enough of the config above, like signed session cookies and OAuth’s PKCE state, that it deserves a mention here.

Resolution order at startup:

1. FYMO_SECRET env var, used as raw UTF-8 bytes. Must be at least 16 characters, or startup raises.
2. .fymo/secret.key on disk, if present and at least 16 bytes.
3. Dev mode only (dev=True or FYMO_DEV=1). 32 random bytes get generated and written to .fymo/secret.key (mode 0600) for reuse across restarts.
4. Production with neither set: startup raises. A forgeable session cookie is a worse failure mode than refusing to boot.

Why the dev flags skip parse_bool

FYMO_DEV and FYMO_SECRET are read with a simple truthy check, not with parse_bool: “1”, “true”, “yes”, or “on”, case-insensitive.

That’s deliberate. Defaulting an unrecognized value to False here is a reasonable fallback for an env var read directly. The stricter parse_bool governs actual fymo.yml booleans instead, where a typo should raise rather than get guessed at.

Sections that aren’t read

Older or scaffolded projects sometimes carry a server: block (host, port, reload) and a build: block (output_dir, minify) in their fymo.yml. The framework doesn’t read either one. Host and port instead come from CLI flags:

fymo dev --host 0.0.0.0 --port 8000
fymo serve --host 0.0.0.0 --port 8000 --prod --workers 4

If you see those sections in an older or generated fymo.yml, they’re inert: safe to leave, safe to delete.

Full example

name: acme-blog
version: 1.0.0
description: "Blog with auth, background email, and video uploads"

routes:
  root: index.index
  resources:
    - posts
    - tags

auth:
  enabled: true
  providers:
    - password
    - type: oidc
      id: okta
      authorize_endpoint: ${OKTA_AUTHORIZE_ENDPOINT}
      token_endpoint: ${OKTA_TOKEN_ENDPOINT}
      userinfo_endpoint: ${OKTA_USERINFO_ENDPOINT}
      client_id_env: OKTA_CLIENT_ID
      client_secret_env: OKTA_CLIENT_SECRET
      required: auto

remote:
  explicit_optin: true

jobs:
  provider: procrastinate

broadcasts:
  provider: postgres

storage:
  provider: local
  root: data/uploads

media:
  - prefix: /media/videos/
    dir: videos
    extensions: [webm, mp4]

limits:
  rate_limit:
    enabled: ${RATE_LIMIT_ENABLED:-true}
    requests_per_minute: 120
  max_body_bytes: 26214400

logging:
  destination: ${LOG_DESTINATION:-terminal}
  level: ${LOG_LEVEL:-info}