Variables d'environnement

Liste exhaustive des variables d’environnement reconnues par arka-deck. Source de vérité : .env.example à la racine, addons/cortex-lite/.env.example pour le sidecar embarqué, et la lecture effective au boot.

Serveur web

Variable	Défaut	Description
`ARKA_DECK_WEB_PORT`	`3117`	Port HTTP du serveur
`ARKA_DECK_WEB_HOST`	`127.0.0.1` (ou `0.0.0.0` si `--lan`)	Adresse de bind
`ARKA_DECK_WEB_LAN`	`0`	Active le mode LAN si `1`, `true` ou `yes` (priorité 2, cf. CLI)
`ARKA_DECK_WEB_BASE_URL`	dérivée du host/port	Override l’URL publique exposée par le serveur (callbacks OAuth, liens)
`ARKA_DECK_LOG`	`info`	Niveau de log Fastify (`fatal`/`error`/`warn`/`info`/`debug`/`trace`/`silent`)
`ARKA_DECK_RATE_LIMIT_MAX`	`300`	Plafond rate limit / minute
`ARKA_DECK_RATE_LIMIT_WINDOW`	`1 minute`	Fenêtre du rate limit (syntaxe Fastify rate-limit)

Storage et home

Variable	Défaut	Description
`ARKA_DECK_HOME`	`~/.arka-deck/`	Override du dossier global utilisateur
`ARKA_PLATFORM_DIR`	spécifique à la plateforme	Override du dossier data plateforme (avancé)

Cortex (catalogue + MCP)

Variable	Défaut	Description
`ARKA_DECK_CORTEX_URL`	`https://public.arkalabs.app`	Endpoint Cortex pour le catalogue (lecture seule)
`ARKA_DECK_CORTEX_MCP_URL`	`https://mcp.public.arkalabs.app`	Endpoint MCP Cortex pour les agents
`ARKA_DECK_CORTEX_RUNTIME_URL`	(non défini, fallback loopback)	Endpoint runtime Cortex dédié

Politique anti-SSRF

Par défaut, les overrides ARKA_DECK_CORTEX_URL, ARKA_DECK_CORTEX_MCP_URL et ARKA_DECK_CORTEX_RUNTIME_URL n’acceptent que :

Le loopback (127.0.0.1, localhost) — pour Cortex Lite local
Les hosts HTTPS sur *.arkalabs.app

Tout autre host est refusé. Pour passer outre en développement :

ARKA_DECK_CORTEX_ALLOW_UNSAFE_URL=1

Cette variable ne doit jamais être positionnée en production.

Voir ADR 0006.

Sidecar Cortex Lite

Ces variables sont lues par le sidecar embarqué addons/cortex-lite (SurrealDB + Express REST + MCP stdio optionnel). Quand arka-deck lance le sidecar via Docker compose, il transmet les variables présentes dans l’environnement hôte.

Source du schéma : addons/cortex-lite/.env.example.

Process

Variable	Défaut	Description
`MODE`	`api`	Mode process : `api` (HTTP REST) ou `mcp` (stdio MCP)
`PORT`	`9100`	Port HTTP (bind loopback `127.0.0.1:${PORT}:9100` via docker-compose)
`CORTEX_LITE_MCP_DISABLED`	non défini	Si défini (`1`/`true`), le serveur MCP stdio n’est pas démarré même en `MODE=mcp`
`CORTEX_LITE_COMPOSE_FILE`	`docker-compose.yml` bundlé	Override du fichier compose utilisé par le launcher

SurrealDB

Variable	Défaut	Description
`SURREAL_URL`	`http://127.0.0.1:8000`	Endpoint SurrealDB
`SURREAL_USER`	`root`	Utilisateur DB
`SURREAL_PASS`	(non défini, pas de défaut)	Mot de passe DB — ne jamais réutiliser `root` hors sandbox éphémère
`SURREAL_NS`	`cortex`	Namespace SurrealDB
`SURREAL_DB`	`lite`	Database SurrealDB
`DB_INIT_RETRY_MS`	`1000`	Délai entre tentatives de bootstrap DB (ms)
`DB_INIT_MAX_ATTEMPTS`	`30`	Tentatives max de bootstrap DB avant abandon

Auth et CORS

Variable	Défaut	Description
`API_KEYS`	(non défini)	Tableau JSON `[{ "key": "...", "role": "admin"\|"readonly", "label": "..." }]` — générer via `openssl rand -hex 32`
`CORTEX_LITE_DEV_AUTH`	non défini	Si `1`, accepte la valeur magique `dev-key-lite` comme clé admin. Sandbox uniquement
`CORS_ORIGIN`	loopback uniquement	Allowlist séparée par virgules. `*` n’est accepté que si explicitement défini
`ARKA_TOKEN`	(non défini)	Token LAN partagé entre arka-deck et Cortex Lite (auto-injecté en admin)

La vérification API key utilise crypto.timingSafeEqual sur des hash SHA-256 (constant-time sur tout le cache + la branche ARKA_TOKEN).

URL endpoint (`CORTEX_PUBLIC_URL`)

Variable	Défaut	Description
`CORTEX_PUBLIC_URL`	`https://public.arkalabs.app`	URL upstream Cortex catalogue (lecture seule)

Le sidecar applique la même policy anti-SSRF que le core arka-deck (HTTPS + arkalabs.app uniquement). L’override dev est le même ARKA_DECK_CORTEX_ALLOW_UNSAFE_URL=1 — à garder cohérent entre les deux surfaces.

Rate limit — report explicite

L’app Express Cortex Lite n’embarque pas de middleware de rate limit. Justification :

le sidecar est publié en loopback uniquement (bind Docker 127.0.0.1:9100) ;
tout chemin de flood LAN passe par le reverse proxy Fastify arka-deck, qui applique déjà ARKA_DECK_RATE_LIMIT_MAX / ARKA_DECK_RATE_LIMIT_WINDOW ;
le payload est capé à 2 MB (express.json({ limit: '2mb' })).

Si Cortex Lite est un jour exposé au-delà du loopback, ajouter express-rate-limit (cible 600 req/min, allowlist 127.0.0.1) et mettre à jour cette section.

Ingestion / sync scheduler

Variable	Défaut	Description
`INGEST_BATCH_SIZE`	`20`	Atoms par batch lors du sync du catalogue public
`INGEST_DELAY_MS`	`100`	Délai entre batches (ms), pour ne pas saturer Cortex Public
`INGEST_FETCH_CONTENT`	non défini	Fetch du contenu complet pendant l’ingestion (`1`/`true`) ou résumé seul
`SYNC_INTERVAL_HOURS`	`24`	Fréquence du resync automatique
`SYNC_ON_START`	`true`	Déclenche un sync immédiat au démarrage

Connecteurs externes

Variable	Description
`ARKA_DECK_NOTION_OAUTH_CLIENT_ID`	OAuth client ID Notion (intégration first-party)
`ARKA_DECK_NOTION_OAUTH_CLIENT_SECRET`	OAuth client secret Notion
`ARKA_DECK_NOTION_OAUTH_REDIRECT_URI`	URL de callback OAuth Notion, généralement `/api/connectors/installations/oauth/callback`
`NOTION_OAUTH_CLIENT_ID`	Alias legacy (déprécié ; préférer la forme `ARKA_DECK_*`)
`NOTION_OAUTH_CLIENT_SECRET`	Alias legacy (déprécié ; préférer la forme `ARKA_DECK_*`)
`NOTION_OAUTH_REDIRECT_URI`	Alias legacy (déprécié ; préférer la forme `ARKA_DECK_*`)

Les variables OAuth sont nécessaires uniquement si vous utilisez le flow OAuth navigateur Notion. Notion peut encore utiliser un token d’intégration interne.

Gmail et Google Drive n’utilisent pas de variables OAuth globales arka-deck. Leur token API/gateway et leur endpoint MCP optionnel se configurent par installation connecteur depuis l’UI.

Autres flags runtime

Variable	Défaut	Description
`ARKA_DECK_MCP_PROBE`	`1`	Si `0`, la probe d’endpoint MCP n’est pas exécutée pendant les installs
`ARKA_DECK_ENABLE_CUSTOM_STDIO_MCP`	`0`	Active l’enregistrement de serveurs MCP STDIO personnalisés
`ARKA_DECK_GOOGLE_GENAI_ALLOW_UNSAFE_BASE_URL`	non défini	DEV ONLY — désactive la validation anti-SSRF Google GenAI
`ARKA_REFUSE_DRAFT`	non défini	Flag défensif pour tests : refuse l’envoi de drafts vers les connecteurs externes

Tests E2E

Variable	Description
`PLAYWRIGHT_BASE_URL`	URL de base pour les tests Playwright (défaut `http://127.0.0.1:3117`)
`ARKA_E2E_PORT`	Port alternatif utilisé par le web server Playwright
`ARKA_SMOKE_SKIP_BUILD`	Helper smoke : saute l’étape de build dans `scripts/smoke-binary.sh`

Bonnes pratiques

Mettre les overrides dans .env.local (jamais dans .env versionné).
Ne jamais commiter de clé API. La valeur historique dev-key-lite de Cortex Lite est refusée tant que CORTEX_LITE_DEV_AUTH=1 n’est pas explicitement positionné.
Pour des secrets persistents, utiliser l’UI Paramètres → Providers plutôt qu’une variable d’environnement (chiffrement AES-256-GCM).
Vérifier .env.example à la racine et addons/cortex-lite/.env.example pour la liste maintenue à jour.

Voir aussi

CLI : ./cli
Posture sécurité (Produit) : ../../produit/07-securite-et-donnees
Politique URL runtime : ADR 0006