Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke is a multi-agent orchestration stack designed for email triage, reminders, and persistent agent interactions. The installation process involves setting up a FastAPI backend (Python) and a Next.js frontend (Node.js), configured to communicate via a shared environment file.
Sources: README.md:3-10, server/agents/interaction_agent/runtime.py:38-43
Prerequisites
Before starting the installation, ensure the following software versions are installed on your system:
| Requirement | Version | Description |
|---|---|---|
| Python | 3.10+ | Required for the FastAPI backend and agent runtimes. |
| Node.js | 18+ | Required for the Next.js web interface. |
| npm | 9+ | Package manager for frontend dependencies. |
Sources: README.md:12-15
Backend Setup
The backend is built with FastAPI and handles multi-agent orchestration. It requires a virtual environment and specific API keys for OpenRouter and Composio.
1. Environment Configuration
Configuration is managed via a .env file located in the root directory. Users must copy the template and provide valid API keys.
cp .env.example .env
| Variable | Requirement | Description |
|---|---|---|
OPENROUTER_API_KEY | Required | Key from openrouter.ai to power the LLM agents. |
COMPOSIO_API_KEY | Required | Key from composio.dev for Gmail tool integrations. |
GMAIL_AUTH_CONFIG_ID | Required | Configuration ID for Gmail OAuth flows. |
Sources: README.md:18-32, server/agents/interaction_agent/runtime.py:48-52
2. Dependency Installation
The backend relies on dependencies listed in server/requirements.txt. It is mandatory to use a Python 3.10+ virtual environment.
python3.10 -m venv .venv
source .venv/bin/activate
pip install -r server/requirements.txt
Sources: README.md:34-51
3. Execution
The server is started using the Python module syntax.
python -m server.server --reload
Sources: README.md:53-54
Frontend Setup
The frontend is a Next.js application that proxies requests to the Python backend.
1. Installation and Development
Frontend dependencies are managed by npm. The web app uses Tailwind CSS for styling and React 18 for UI components.
npm install --prefix web
npm run dev --prefix web
Sources: README.md:56-60, web/package.json:10-25
2. Timezone Detection
Upon first load, the frontend automatically detects the browser's timezone using Intl.DateTimeFormat().resolvedOptions().timeZone and persists it via a POST request to /api/timezone.
Sources: web/app/page.tsx:71-93
Integration Setup (Gmail)
To enable email workflows (drafting, replying, and monitoring), users must complete the Gmail OAuth flow via Composio through the web interface.
Connection Workflow
The application uses a sequence of API calls to manage the Gmail connection state.
This diagram shows the flow of connecting a Gmail account through the application's multi-tier architecture.
Sources: web/components/SettingsModal.tsx:162-205, web/app/api/gmail/connect/route.ts:13-22
Component Architecture
The following diagram illustrates how the frontend components interact with the backend runtimes during the setup and operation phase.
This chart visualizes the data flow between the web interface and the backend agent logic.
Sources: web/app/api/chat/route.ts:31-36, server/agents/interaction_agent/runtime.py:44-47, README.md:65-68
Summary
The OpenPoke setup requires a dual-process environment (FastAPI and Next.js). By configuring the shared .env file with OpenRouter and Composio keys and completing the Gmail OAuth flow in the web settings, the system enables a persistent, multi-agent assistant capable of email management and task execution.
Sources: README.md:62-63