How to use Buffaly settings and feature flags
Configure providers, models, Codex, OpenAI, session storage, web modules, and runtime behavior without hiding operational choices in prompts.
Use this page when a setting changed in the UI but not in a running session, a feature row fails to load, a module is missing, or you need to verify which runtime value is actually active.
Quick answer
In Buffaly, a Feature is commonly a named settings row loaded into a typed source contract. Required rows and settings payloads can fail fast when missing or malformed.
- Use the Buffaly settings UI for everyday OpenAI, Codex, and session-store settings it exposes.
- Use Sessions.Web Features for database-backed feature rows and lower-level JSON inspection.
- Use provider/model UI or provider catalog flows for provider and model selection.
- Use web-module manifests and diagnostics for installed UI capabilities.
- Verify the running process picked up the setting; many feature classes cache a static snapshot.
What Features means in Buffaly
Source uses Feature in a concrete settings sense: a named row in the sessions database whose Settings payload is read into a typed class.
| Feature area | Contract | Controls |
|---|---|---|
| Runtime | RuntimeFeature | Install/session/project roots, defaults, worker mode, and auto-load threshold. |
| OpenAI | OpenAIFeature | OpenAI API key and diagnostics behavior. |
| Codex auth | CodexAuthFeature | Codex OAuth/profile storage, callback, timeout, and profile root. |
| Codex backend | CodexBackendFeature | Codex backend enablement, URL/path, model, timeout, and request behavior. |
| Worker | WorkerFeature | Host/worker internal route settings. |
| Install root | RuntimeInstallRootFeature | Install root for provider and web-module roots. |
Where settings live
Buffaly settings UI
Use first for exposed OpenAI key status, Codex auth/profile controls, usage refresh, and session-store settings.
Sessions.Web Features
Use to inspect feature rows and JSON payloads consumed by typed runtime features.
Provider catalog
Use provider/model flows for provider, model, transport, and reasoning-level selection.
Web-module manifest
Use WebModules.json and diagnostics to verify installed, enabled, and loaded UI capabilities.
Runtime feature flags and cached settings
Many feature classes expose a static Feature property and cache the deserialized settings object. Editing the stored row may not update an already-running process immediately.
- New sessions may still run under a worker that loaded old settings.
- Some changes require page refresh, session restart, worker recycle, or web-host restart.
- Fail-fast loaders can surface missing rows, malformed URLs, invalid enums, and empty required payloads.
Provider, model, and authentication settings
Provider settings span several layers. OpenAI API keys, ChatGPT/Codex backend OAuth or profile settings, and provider/model selection are related but separate. Use the settings path that matches the transport.
- Decide whether you are configuring OpenAI API usage, Codex backend usage, or provider/model selection.
- Use settings UI for OpenAI/Codex credential operations when available.
- Use provider/model settings UI or catalog flows for provider, model, transport, or reasoning selection.
- Verify the active session's provider/model/transport, not just stored defaults.
- Run a small test request before changing more settings.
Never paste API keys into prompts, docs, screenshots, or task artifacts. Store credentials through the supported settings or secret path.
Web modules and enabled capabilities
A capability can exist in source without being enabled in the running installation. Verify all three levels before editing source.
Source-present
The module project or static folder exists in the repository.
Manifest-enabled
WebModules.json lists the module with Enabled: true.
Runtime-loaded
/api/diagnostics/web-modules shows the module loaded by the current host.
Change settings safely
- Identify the exact owner: settings UI, provider catalog, feature row, web-module manifest, or implementation file.
- Read the source contract that consumes the setting.
- Back up or record the current value.
- Make the smallest focused change.
- Validate stored value and running value separately.
- Restart or recycle only if source indicates cached feature state or startup-only loading.
- Test with a small request.
- Document the change and rollback path.
Verify a setting took effect
- OpenAI key: check key status through settings UI/API and run a tiny provider-backed request without exposing the key.
- Codex auth/backend: check profile/status and run a safe inspection or dry-run task.
- Provider/model: inspect active session selection and run a small response with the intended model.
- Runtime paths: inspect runtime feature output or prompt-visible path values.
- Web modules: inspect manifest and diagnostics, load the module page, and check JsonWs calls.
- Session store: create or open a test session and verify it appears in the expected store.
Common mistakes and failure modes
Editing source when settings own behavior
Change the settings row or UI value instead of hardcoding a fallback.
Source-present is not enabled
Verify runtime installation, manifest, and diagnostics.
Confusing OpenAI and Codex auth
Use the path that matches the transport and backend.
Expecting cached values to update instantly
Check whether restart, recycle, or new session is required.
Breaking typed JSON contracts
Malformed URLs, invalid enums, missing paths, or empty required rows can fail fast.
Storing secrets in docs or prompts
Report credential status, not secret values.