Configuration & Environment
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke utilizes a dual-layer configuration system composed of server-side environment variables and client-side local storage. The server relies on a Pydantic-based settings management system that loads configurations from a .env file to manage LLM model selections, API credentials, and integration IDs. The frontend complements this by managing user-specific preferences such as timezones and integration states (e.g., Gmail via Composio) within the browser environment.
Sources: server/config.py:1-25, README.md:20-35, web/components/SettingsModal.tsx:10-30
Server Configuration Management
The backend configuration is centralized in server/config.py. It uses a Settings class inheriting from Pydantic's BaseModel to provide structured access to environment variables with type safety and default fallbacks.
Environment Loading Logic
Before the Settings class is instantiated, a helper function _load_env_file() manually parses the .env file located in the project root. This ensures that variables are injected into os.environ if they are not already present, allowing the Pydantic Field defaults to pick them up via os.getenv().
The diagram above illustrates the sequence of loading environment variables during the server initialization phase.
Sources: server/config.py:12-32, server/config.py:100-104
Core Application Settings
The Settings model defines several categories of configuration, ranging from server runtime details to specific LLM models used for different agentic tasks.
| Category | Option | Default / Fallback | Description |
|---|---|---|---|
| Metadata | app_name | "OpenPoke Server" | Name of the FastAPI application. |
| Network | server_host | "0.0.0.0" | Host address for the server. |
| Network | server_port | 8001 | Port for the server. |
| LLM | interaction_agent_model | "anthropic/claude-sonnet-4" | Model for user-facing interaction. |
| LLM | summarizer_model | "anthropic/claude-sonnet-4" | Model used for conversation summarization. |
| Integrations | openrouter_api_key | None | API Key for OpenRouter completion calls. |
| Integrations | composio_api_key | None | API Key for Gmail and tool orchestration. |
Sources: server/config.py:44-70, server/config.py:72-80
Client-Side Environment & Proxying
The frontend (Next.js) manages its environment through two primary mechanisms: local storage for persistent user settings and server-side environment variables for API routing.
Proxy Configuration
The web application communicates with the Python backend using environment variables defined in the Next.js runtime environment. These variables dictate where the frontend should direct its API requests.
- PY_SERVER_URL: The base URL of the FastAPI backend (defaults to
http://localhost:8001). - PY_CHAT_PATH: The specific endpoint for sending chat messages (defaults to
/api/v1/chat/send).
Sources: web/app/api/chat/route.ts:32-35
User-Specific Persistence
User preferences that do not require server-side secret management are stored in the browser's localStorage. This includes:
- Timezone: Auto-detected from the browser via
Intl.DateTimeFormat().resolvedOptions().timeZoneand stored to ensure consistent timestamp rendering and trigger scheduling. - Gmail Integration State: Tracks
gmail_connected,gmail_email, andgmail_connection_request_idto manage the UI state of the Composio integration.
Sources: web/components/SettingsModal.tsx:12-25, web/app/page.tsx:65-75
This sequence diagram shows how the frontend uses both local storage for context and environment variables for routing requests to the backend.
Sources: web/app/api/chat/route.ts:37-55, web/components/SettingsModal.tsx:15-28
Feature-Specific Configuration
Certain modules within the system have specialized configuration requirements that influence their logic:
Summarization Controls
The conversation summarization logic is governed by thresholds defined in the settings.
- conversation_summary_threshold: Defines the number of entries before a summarization event is triggered (default: 100).
- conversation_summary_tail_size: Determines how many recent messages are kept unsummarized to maintain immediate context (default: 10).
- summarization_enabled: A property that returns
Trueif the threshold is greater than 0.
Sources: server/config.py:82-84, server/config.py:95-98
Integration Credentials
OpenPoke requires external service keys to function fully. These are mandatory for specific agent workflows:
- OpenRouter: Necessary for all LLM completions. If
openrouter_api_keyis missing, theInteractionAgentRuntimewill raise aValueError. - Composio: Required for Gmail tooling. The
composio_gmail_auth_config_idis used to link specific Gmail sessions to users.
Sources: server/agents/interaction_agent/runtime.py:46-50, README.md:27-35, server/config.py:73-75
Summary
OpenPoke's configuration architecture ensures that sensitive credentials remain on the server while user preferences are handled gracefully by the client. By utilizing Pydantic and manual .env parsing, the system provides a robust, type-safe environment for multi-agent orchestration while remaining simple enough for local deployment as described in the project's quickstart documentation.