> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Env variables

<Note>
  Esta página ainda está em inglês. A tradução para português está em andamento.
</Note>

# Environment Variables Reference

All environment variables are defined in `.env` (generated by `make setup`). See `.env.example` for the template.

## AI Provider Configuration

EvoNexus uses the `claude` CLI by default (Anthropic native auth). To switch to any other backend, the active provider is read from `config/providers.json` — **not from `.env`** directly. The dashboard's Providers page and `make setup` both write to that file.

The env vars below are the ones EvoNexus injects into the spawned CLI process based on the active provider. You don't set them in `.env` yourself — they live inside `config/providers.json` under each provider's `env_vars` key, and the terminal-server / ADW runner merge them into the subprocess environment at spawn time. Only the variable names in this allowlist are accepted (both the Python runner and the JS bridge enforce the same list):

| Variable | Used by | Description |
| - | - | - |
| `CLAUDE_CODE_USE_OPENAI` | OpenRouter, OpenAI, Codex Auth | Flag telling OpenClaude to dispatch to the OpenAI-compatible protocol |
| `CLAUDE_CODE_USE_GEMINI` | Gemini | Flag telling OpenClaude to dispatch to Gemini |
| `CLAUDE_CODE_USE_BEDROCK` | AWS Bedrock | Flag telling OpenClaude to dispatch to Bedrock |
| `CLAUDE_CODE_USE_VERTEX` | Google Vertex AI | Flag telling OpenClaude to dispatch to Vertex |
| `OPENAI_BASE_URL` | OpenRouter | Override the API base URL (e.g. `https://openrouter.ai/api/v1`) |
| `OPENAI_API_KEY` | OpenRouter, OpenAI, Codex Auth | API key for the OpenAI-compatible provider |
| `OPENAI_MODEL` | OpenRouter, OpenAI | Model identifier (e.g. `anthropic/claude-sonnet-4`, `gpt-4.1`) |
| `GEMINI_API_KEY` | Gemini | Google AI API key |
| `GEMINI_MODEL` | Gemini | Model identifier (e.g. `gemini-2.5-pro`) |
| `AWS_REGION` | Bedrock | AWS region (e.g. `us-east-1`) |
| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock | Bedrock bearer token (not the standard IAM access key) |
| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI | GCP project ID |
| `CLOUD_ML_REGION` | Vertex AI | GCP region (e.g. `us-east5`) |

**How to configure**: use the **Providers** page in the dashboard — it reads/writes `config/providers.json` for you, masks secrets in API responses, and has a "Test connection" button that runs `<provider-cli> --version` with the merged env. Alternatively, edit `config/providers.json` directly (it starts as a copy of `config/providers.example.json` on first run).

**Anthropic is the default** — when the active provider is `anthropic`, no env vars are injected and the spawned CLI is the native `claude` binary with its own auth. You don't need any of the variables above for the default path.

See [docs/dashboard/providers.md](../dashboard/providers.md) for the full provider setup flow.

## Omie ERP

| Variable | Required | Description |
| - | - | - |
| `OMIE_APP_KEY` | For finance routines | Omie API app key |
| `OMIE_APP_SECRET` | For finance routines | Omie API app secret |

**How to get**: Omie dashboard > Settings > Integrations > API. Create an app to get the key and secret.

## Stripe

| Variable | Required | Description |
| - | - | - |
| `STRIPE_SECRET_KEY` | For finance routines | Stripe secret API key (starts with `sk_live_` or `sk_test_`) |

**How to get**: [dashboard.stripe.com](https://dashboard.stripe.com) > Developers > API Keys. Use the secret key (not the publishable key).

## Todoist

| Variable | Required | Description |
| - | - | - |
| `TODOIST_API_TOKEN` | For task management | Todoist personal API token |

**How to get**: [app.todoist.com](https://app.todoist.com) > Settings > Integrations > Developer > API Token.

## Fathom (Meetings)

| Variable | Required | Description |
| - | - | - |
| `FATHOM_API_KEY` | For meeting sync | Fathom API key |

**How to get**: [fathom.video](https://fathom.video) > Settings > API. Generate an API key.

## Discord

| Variable | Required | Description |
| - | - | - |
| `DISCORD_BOT_TOKEN` | For community routines | Discord bot token |
| `DISCORD_GUILD_ID` | For community routines | Server (guild) ID |

**How to get**:

* Bot token: [discord.com/developers](https://discord.com/developers) > New Application > Bot > Token
* Guild ID: Enable Developer Mode in Discord settings, then right-click your server > Copy Server ID

## Telegram

| Variable | Required | Description |
| - | - | - |
| `TELEGRAM_BOT_TOKEN` | For notifications | Bot token from @BotFather |
| `TELEGRAM_CHAT_ID` | For notifications | Chat ID to send messages to |

**How to get**:

* Bot token: Message [@BotFather](https://t.me/BotFather) on Telegram, use `/newbot`
* Chat ID: Send `/start` to your bot, then call `https://api.telegram.org/bot<TOKEN>/getUpdates` to find the chat ID

## YouTube OAuth

| Variable | Required | Description |
| - | - | - |
| `YOUTUBE_OAUTH_CLIENT_ID` | For YouTube analytics | Google OAuth client ID |
| `YOUTUBE_OAUTH_CLIENT_SECRET` | For YouTube analytics | Google OAuth client secret |

**How to get**: [Google Cloud Console](https://console.cloud.google.com) > APIs & Services > Credentials > Create OAuth Client ID. Enable the YouTube Data API v3.

## Meta / Instagram OAuth

| Variable | Required | Description |
| - | - | - |
| `META_APP_ID` | For Instagram analytics | Facebook/Meta app ID |
| `META_APP_SECRET` | For Instagram analytics | Facebook/Meta app secret |

**How to get**: [developers.facebook.com](https://developers.facebook.com) > My Apps > Create App > Settings > Basic. Enable the Instagram Graph API.

## LinkedIn OAuth

| Variable | Required | Description |
| - | - | - |
| `LINKEDIN_CLIENT_ID` | For LinkedIn analytics | LinkedIn app client ID |
| `LINKEDIN_CLIENT_SECRET` | For LinkedIn analytics | LinkedIn app client secret |

**How to get**: [linkedin.com/developers](https://linkedin.com/developers) > My Apps > Create App > Auth tab. Request the `r_organization_social` and `r_liteprofile` scopes.

## Backup (S3-compatible)

| Variable | Required | Description |
| - | - | - |
| `BACKUP_S3_BUCKET` | For S3 backups | S3 bucket name (any S3-compatible: AWS, MinIO, R2) |
| `BACKUP_S3_PREFIX` | No | Folder inside the bucket (default: `evonexus-backups/`) |
| `AWS_ACCESS_KEY_ID` | For S3 backups | AWS credentials (or S3-compatible) |
| `AWS_SECRET_ACCESS_KEY` | For S3 backups | AWS credentials (or S3-compatible) |
| `AWS_ENDPOINT_URL` | For non-AWS | Custom endpoint for MinIO, Cloudflare R2, etc. |

**How to get**: Create an S3 bucket (or use any S3-compatible service). Set the bucket name and credentials. Install `boto3` with `uv add boto3`.

**Note**: Local backups (`make backup`) work without any env vars. S3 is optional for cloud replication.

## Social Accounts

Social media accounts are managed via the dashboard Integrations page after OAuth setup. The tokens are stored with this pattern:

```env theme={null}
SOCIAL_{PLATFORM}_{N}_{FIELD}
```

Examples:

```env theme={null}
SOCIAL_YOUTUBE_1_LABEL=My Channel
SOCIAL_YOUTUBE_1_ACCESS_TOKEN=ya29...
SOCIAL_YOUTUBE_1_CHANNEL_ID=UC...

SOCIAL_INSTAGRAM_1_LABEL=Main Profile
SOCIAL_INSTAGRAM_1_ACCESS_TOKEN=EAA...
SOCIAL_INSTAGRAM_1_USER_ID=17841...

SOCIAL_LINKEDIN_1_LABEL=Company Page
SOCIAL_LINKEDIN_1_ACCESS_TOKEN=AQ...
SOCIAL_LINKEDIN_1_ORG_ID=12345
```

These are populated automatically when you connect accounts through the dashboard.

## Required vs Optional

**No variable is strictly required** -- EvoNexus works with whatever integrations you enable. But specific routines need their corresponding keys:

| Routine | Required Variables |
| - | - |
| Morning briefing | None (uses Google MCP for calendar/email) |
| Financial pulse | `STRIPE_SECRET_KEY`, `OMIE_APP_KEY`, `OMIE_APP_SECRET` |
| Community pulse | `DISCORD_BOT_TOKEN`, `DISCORD_GUILD_ID` |
| Social analytics | Social account tokens (via dashboard) |
| Meeting sync | `FATHOM_API_KEY` |
| Telegram notifications | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
| Task management | `TODOIST_API_TOKEN` |
| Licensing | No env vars (uses the licensing API directly) |
| Daily backup (local) | None |
| Daily backup (S3) | `BACKUP_S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` |

Google Calendar and Gmail are connected via MCP servers configured in Claude Code settings, not through `.env` variables.

## Knowledge Base (pgvector)

| Variable | Required For | Description |
| - | - | - |
| `KNOWLEDGE_MASTER_KEY` | Knowledge Base | Fernet key used to encrypt connection credentials. **Auto-generated on first setup / Docker first boot** (v0.26.0+) — you don't set it manually. Back up your `.env`, losing this key loses access to all connections. |
| `KNOWLEDGE_EMBEDDER_PROVIDER` | Optional | `local` (default), `openai`, or `gemini` |
| `KNOWLEDGE_DEFAULT_PARSER` | Optional | `marker` (default) or `llamaparse` |
| `OPENAI_API_KEY` | `openai` embedder | OpenAI key (starts with `sk-...`) |
| `KNOWLEDGE_OPENAI_MODEL` | Optional | `text-embedding-3-small` (default) / `-3-large` / `ada-002` |
| `GEMINI_API_KEY` | `gemini` embedder | Google AI Studio key (starts with `AIzaSy...`) |
| `KNOWLEDGE_GEMINI_MODEL` | Optional | `gemini-embedding-001` (default) or `gemini-embedding-2-preview` |
| `KNOWLEDGE_GEMINI_DIM` | Optional | MRL output dim: `768` (default, aligns with local), `1536`, or `3072` |
| `LLAMAPARSE_API_KEY` | `llamaparse` parser | LlamaParse cloud API key |

**How to get**:

* **OpenAI**: [platform.openai.com](https://platform.openai.com) > API Keys.
* **Gemini**: [aistudio.google.com/apikey](https://aistudio.google.com/apikey) (generous free tier).

Configure via the dashboard at `/knowledge/settings` — the provider is locked once the first connection is created (changing it after ingestion requires removing and recreating all connections).

## AI Image Creator

| Variable | Required For | Description |
| - | - | - |
| `AI_IMG_CREATOR_CF_ACCOUNT_ID` | Gateway mode | Cloudflare account ID (from dashboard URL or Overview page) |
| `AI_IMG_CREATOR_CF_GATEWAY_ID` | Gateway mode | AI Gateway name (set when creating the gateway) |
| `AI_IMG_CREATOR_CF_TOKEN` | Gateway mode | Gateway auth token (from gateway Settings > Authentication) |
| `AI_IMG_CREATOR_OPENROUTER_KEY` | Direct OpenRouter | OpenRouter API key (starts with `sk-or-...`) |
| `AI_IMG_CREATOR_GEMINI_KEY` | Direct Google | Google AI Studio API key (starts with `AI...`) |

Gateway mode activates when all three `AI_IMG_CREATOR_CF_*` vars are set. Falls back to direct mode if gateway fails. You only need one provider configured (either Cloudflare or at least one direct key).

**How to get**:

* **Cloudflare Gateway**: [dash.cloudflare.com](https://dash.cloudflare.com) > AI > AI Gateway > Create Gateway. See [docs/skills/ai-image-creator.md](../skills/ai-image-creator.md) for full setup.
* **OpenRouter key**: [openrouter.ai/keys](https://openrouter.ai/keys) > Create Key.
* **Google AI Studio key**: [aistudio.google.com/apikey](https://aistudio.google.com/apikey) > Create API Key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.