# Feature Flags Reference

Feature flags are passed as a JSON object via the `MOLTLAZY_FEATURE_FLAGS` environment variable. They control which optional feature packs are active. All secret values (tokens, API keys) remain as environment variables and are never included in feature flags.

## Format

The feature flags JSON is set directly as a per-customer binding (`MOLTLAZY_FEATURE_FLAGS`) and passed to the container as the `MOLTLAZY_FEATURE_FLAGS` env var. Flags are managed via the FourIA API.

## Example

```json
{
  "knowledgeGraph": true,
  "unifiedBilling": false,
  "softwareProvisioning": false,
  "channelsTelegram": true,
  "channelsDiscord": false,
  "channelsSlack": false,
  "microsoftGraph": false,
  "agents": "*",
  "agentTenant": ""
}
```

## Flags

| Flag                   | Type      | Default | Description                                                                      |
| ---------------------- | --------- | ------- | -------------------------------------------------------------------------------- |
| `agents`               | `string`  | `""`    | Premade agent filter: `"*"` for all, comma-separated IDs, or empty               |
| `agentTenant`          | `string`  | `""`    | Tenant name for tenant-specific agents                                           |
| `knowledgeGraph`       | `boolean` | `false` | Enable knowledge graph (memory, wiki, QMD)                                       |
| `unifiedBilling`       | `boolean` | `false` | Enable CF AI Gateway unified billing plugin                                      |
| `softwareProvisioning` | `boolean` | `false` | Reconcile the declared software manifest at boot (`moltlazy software provision`) |
| `channelsTelegram`     | `boolean` | `false` | Enable Telegram behavioral config                                                |
| `channelsDiscord`      | `boolean` | `false` | Enable Discord behavioral config                                                 |
| `channelsSlack`        | `boolean` | `false` | Enable Slack behavioral config                                                   |
| `microsoftGraph`       | `boolean` | `false` | Enable Microsoft Graph plugin                                                    |

> **`softwareProvisioning`** is consumer-side (the Worker reads it directly, not
> the Config Module). When `true`, the Worker materializes the tenant's software
> manifest (`customers/<slug>/software.json`) and spawns `moltlazy software
> provision` as an **independent process** through the Sandbox SDK — in parallel
> with the gateway boot, non-fatal, and never blocking readiness. It is NOT
> defaulted to dev mode: production tenants opt in. See
> [apps/fouria/docs/WORKER-DEVELOPMENT.md](../../../docs/WORKER-DEVELOPMENT.md).

## Always-on config (no flag needed)

These config sections are always applied by the Config Module at startup, regardless of feature flags:

| Section            | Source           | Purpose                              |
| ------------------ | ---------------- | ------------------------------------ |
| `gateway.*`        | `config/gateway` | Auth mode, trustedProxies, controlUi |
| `session.dmScope`  | `config/session` | Per-channel-peer session isolation   |
| `tools.toolSearch` | `config/tools`   | Tool search enabled in "tools" mode  |
| `logging.*`        | `config/logging` | Production logging with redaction    |
| `agents.defaults`  | `agents/`        | Default model configuration          |

## Secret-free guarantee

Feature flags and `moltlazy.json` never contain secrets. The gateway reads secrets from its own environment:

| Variable                              | Scope              |
| ------------------------------------- | ------------------ |
| `CLOUDFLARE_AI_GATEWAY_API_KEY`       | CF AI Gateway auth |
| `TELEGRAM_BOT_TOKEN`                  | Telegram bot auth  |
| `DISCORD_BOT_TOKEN`                   | Discord bot auth   |
| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` | Slack auth         |

## Storage

Feature flags are set as a per-customer `MOLTLAZY_FEATURE_FLAGS` binding, managed via the FourIA API. There is no R2 storage and no worker-side cache — the binding is read directly at container startup. The legacy `CONFIG_BUCKET` / ETag-cache mechanism was removed.

## Deprecated keys (removed in v0.3)

| v0.2 key                    | v0.3 equivalent                        |
| --------------------------- | -------------------------------------- |
| `MOLTLAZY_FORCE_GATEWAY`    | Removed — always-on                    |
| `MOLTLAZY_FORCE_AI_GATEWAY` | Removed — use `unifiedBilling`         |
| `MOLTLAZY_FORCE_CHANNELS`   | Removed — use `channelsTelegram` etc.  |
| `MOLTLAZY_FORCE_AGENTS`     | Removed — use `agents`                 |
| `MOLTLAZY_AGENTS`           | `agents` (in flags JSON)               |
| `AGENT_TENANT`              | `agentTenant` (in flags JSON)          |
| `MOLTLAZY_TOML_CONTENT`     | Removed — use `MOLTLAZY_FEATURE_FLAGS` |
| `MOLTLAZY_TOML_ETAG`        | Removed — no longer needed             |

## Related

- [Migration Guide](/staging/llms/platform/libraries/moltlazy/migration/index.md) — Migrate from v0.2 TOML-based config
- [Feature Packs](/staging/llms/platform/libraries/moltlazy/feature-packs/index.md) — SDK feature pack details
