Configuration keys¶

Every key keryx reads, with its default and what happens when it is wrong. Keys are written here in dotted form; in YAML they nest. Where the files live and which layer wins is on the configuration page.

A key not listed here is not read. In particular, studio.port appears in some older notes and is not a configuration key — the studio's port comes from --port only.

workspace.* — where reel workspaces live¶

keryx reel new <slug> creates <workspace.root>/<slug>, and keryx reel list enumerates that directory.

reel.* — frame shape¶

A reel workspace can override this per reel with aspect in its workspace.yaml, and reel build --aspect overrides both. An aspect more elongated than 3:1 in either direction is rejected: aspect "5:1" is too elongated (beyond 3:1).

render.* — which engine does the work¶

Applies to the afmpeg backend, which can run either the portable WASM module or a native driver that is dramatically faster — seconds against roughly eight and a half minutes on a three-card reel, per render.

It sits here rather than under providers.render.* on purpose. providers.render as a scalar naming the adapter and providers.render.driver as a map key cannot coexist in YAML, so a key under providers.render.* would be unreachable for precisely the people who selected afmpeg in config — everyone who might want to set it. A top-level render.* has no such collision:

providers:
  render: afmpeg
render:
  driver: auto

KERYX_FFMPEG_WASI_DRIVER overrides it for a single run.

When auto falls back, keryx says so — an INFO line on the CLI, and a note on the studio's render panel while the render runs. A render that is merely slow is otherwise indistinguishable from one that has hung.

providers.* — selecting a backend¶

Each generative capability sits behind an interface, and the adapter is chosen by a scalar key. An empty or unset value selects the default; an unregistered name is an error listing what is available.

Chat is selected differently, by a nested key — see providers.chat.* below.

The scalar and map forms of a providers key collide¶

providers.render is a scalar (the adapter name). providers.render.module is a key inside a map. One YAML key cannot be both, and neither can two layers: the higher-precedence layer's shape wins outright and the other form reads as empty.

# Rejected by the YAML parser — "mapping key render already defined".
providers:
  render: afmpeg
  render:
    module: /opt/ffmpeg-wasi.wasm

Splitting them across ~/.keryx/config.yaml and the project .keryx.yaml does not help either; whichever layer is higher supplies the shape and the other contributes nothing.

The same collision applies to providers.image versus providers.image.price_per_image and providers.image.currency, and to providers.voice versus providers.voice.price_per_1k_chars. Choosing a non-default adapter and tuning that adapter's per-unit price cannot both be expressed.

providers.render.* — the afmpeg wasm module¶

Read only when providers.render is not set as a scalar, for the reason above.

KERYX_FFMPEG_WASI is the env fallback for providers.render.module, and — because of the collision — it is the only way to override the module while also selecting providers.render: afmpeg.

With nothing set, the afmpeg backend downloads a pinned ffmpeg-wasi release (the gpl variant), caches it, and reuses it. You do not need to fetch a module by hand.

That default goes through the project's certified release path: the module is fetched with its checksums, detached signature and provenance, and all three are verified against signing keys embedded in the keryx binary before the module is compiled. Verification cannot be skipped on this path.

Setting providers.render.module yourself is the bring-your-own path instead — your build, uncertified, with module_sha256 as the integrity check you supply. It is not routed through the release verification, because a module you built was never issued under that provenance.

providers.chat.* — the LLM for drafting and copy¶

There is no hardwired chat provider. When providers.chat.provider is unset, keryx infers it from exactly one API key being present in the environment:

• one of ANTHROPIC_API_KEY, GEMINI_API_KEY or OPENAI_API_KEY present → that provider is used;
• none present → no chat provider configured — set providers.chat.provider (claude|gemini|openai) + the matching API key;
• more than one present → multiple chat API keys present (…) — set providers.chat.provider to choose.

That last case is the one that catches people mixing vendors. Generating images with Gemini needs GEMINI_API_KEY; if you also want chat from OpenAI you will have two keys in the environment, and inference refuses rather than guessing. Set providers.chat.provider: openai explicitly and both work — image and chat provider selection are independent keys, and using different vendors for them is supported.

providers.gemini.* and providers.elevenlabs.* — adapter settings¶

cover --model and portrait --model override providers.gemini.model for one run.

providers.*.price_* — cost estimates¶

Prices are cues shown before you spend, not invoices. They are not vendor rates and are deliberately round.

spend.* — the runaway-batch guard¶

Voice is measured on the character axis and everything else on the currency axis. Zero on an axis disables that axis.

themes.* — the style catalog¶

default and defaults are reserved: themes.default holds the default keyword, so no theme may claim either name.

The pre-0047 themes.<type>.<keyword> nesting and themes.defaults.<type> are no longer read. A catalog still in that shape is refused with the command to run — see upgrading from a typed catalog.

Themes are not seeded. On a fresh install there is no catalog, and the first generation asks for one: no theme configured — add one with keryx theme add <keyword> (the first theme added becomes the default).

The field-by-field shape of a theme — palette, card treatment, scrim, music gain, voice clone settings — is on the themes page.

voices.* — the speaker registry¶

voices.<name> defines a named narration voice, referenced from a storyboard card's voice.speaker for multi-author reels. The fields are the same as a reel theme's voice block: id, stability, similarity, style, speed, speaker_boost, model, pronunciation.

Naming a speaker that is not registered fails with voice "<name>" not found (configure it under voices.<name>).

keryx init seeds a voice called matt carrying a real ElevenLabs voice id belonging to the project's author. It is an example, not a default you want; delete it or replace it with your own.

avatars.* — the actor registry¶

avatars.<name> defines a recurring character that can be composited into card illustrations, selected per reel through workspace.yaml's avatars list and per card through the storyboard's avatars field.

Naming an unregistered avatar fails with avatar not found: "<name>" (configure it under avatars.<name>).

As with voices, keryx init seeds an example avatar called matt describing the project's author, whose ref path will not exist in your project.

log.level — logging verbosity¶

studio.* — the local web studio¶

studio.takes_ttl only bites on an in-memory project (a RAM worktree of a remote git project). A local-disk project never prunes takes; its takes are ordinary files the workspace lifecycle owns, cleared by reel prune. The sweeper runs every 30 seconds and skips anything that is the picked slot, so "generate a second round, then go back and pick from the first" works within the window.

The studio's bind port and host come from --port and --host; there is no config key for either.

git.* — the studio's git behaviour¶

storage.* — the media object store¶

Unset storage.provider means local-only, which is not an error: media stays in the workspace and the sync commands report the store as unconfigured.

Credentials are never read from keryx config. Each backend resolves them through its own chain — the AWS default chain, Google ADC, the Azure default credential.

mem keeps objects in process memory and is there for tests; nothing survives the process.

platforms.* — per-platform posting¶

platforms.<name>.enabled (bool, default false) gates a platform for post and auth refresh. <name> is instagram, youtube, tiktok or linkedin.

Credentials resolve environment variable → OS keychain → config key, in that order. The config fallback is plaintext; prefer the environment or the keychain. The full credential set-up per platform is in the how-to guides (Instagram, YouTube, TikTok, LinkedIn).

Non-secret platform settings:

platforms.<name>.constraints.* — overriding the composition limits¶

Each platform ships built-in norms used to steer composition and to gate approval. Every field can be overridden per platform, so a limit can be corrected without waiting for a release.

Exceeding text_cap or title_cap is a hard violation: keryx approve refuses the platform. A title on a platform with title_cap: 0, or a link on a platform with links_clickable: false, is advisory — you get instagram links are not clickable — use "link in bio" and posting still proceeds.

auth.writeback.* — where refreshed tokens are written¶

The gitlab backend needs GITLAB_TOKEN (api-scoped) in the environment and refuses without it.

auth.alerts.* — expiry alerting¶

webhook without a URL fails with auth.alerts.backend=webhook but no URL — set ALERT_WEBHOOK_URL or auth.alerts.webhook.url; email missing any of host, from or to fails with auth.alerts.backend=email needs auth.alerts.email.{host,from,to}.

tls.source — the studio's certificate¶

An unknown value is not an error — it degrades to self-signed, and HTTPS is still served so the Secure cookie holds. localca also falls back to self-signed when the CA cannot be provisioned (no elevation, no certutil).

site.base_url — the canonical post URL¶

When set, storyboard draft rewrites the closing URL card to <site.base_url>/<workspace slug> rather than trusting the host the model invented. Unset, the model's text stands.