From 5c65cc690d0ab4f764db46e7382b89776309f2ac Mon Sep 17 00:00:00 2001 From: rune Date: Wed, 8 Apr 2026 13:13:32 +0200 Subject: [PATCH] Add Home --- Home.md | 547 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..8af4cc3 --- /dev/null +++ b/Home.md @@ -0,0 +1,547 @@ +# oAI-Web - Help + +--- + +## Table of Contents + +- [Getting Started](#getting-started) +- [Chat Interface](#chat-interface) + - [File Attachments](#file-attachments) + - [Model Picker](#model-picker) + - [Capability Badges](#capability-badges) +- [Files](#files) +- [Agents](#agents) + - [Creating Agents](#creating-agents) + - [Scheduling](#scheduling) + - [Prompt Modes](#prompt-modes) + - [Tool Restrictions](#tool-restrictions) + - [Sub-agents](#sub-agents) +- [MCP Servers](#mcp-servers) +- [Settings](#settings) + - [General (Admin)](#general-admin) + - [Whitelists (Admin)](#whitelists-admin) + - [Credentials (Admin)](#credentials-admin) + - [Inbox](#inbox) + - [Email Accounts](#email-accounts) + - [Telegram](#telegram) + - [Profile](#profile) + - [Personality](#personality) + - [2nd Brain](#2nd-brain) + - [MCP Servers (Settings)](#mcp-servers-settings) + - [Security (Admin)](#security-admin) + - [Branding (Admin)](#branding-admin) + - [API Key (Admin)](#api-key-admin) +- [User Management (Admin)](#user-management-admin) +- [Credential Key Reference (Admin)](#credential-key-reference-admin) +- [Security Model](#security-model) +- [Telegram and Email Inbox](#telegram-and-email-inbox) + +--- + +## Getting Started + +### What is oAI-Web? + +oAI-Web is a secure, self-hosted personal AI agent built on the Claude API with full tool-use support. It runs on your home server and exposes a clean web interface for use inside your local network. The agent can read email, browse the web, manage calendar events, read and write files, send push notifications, generate images, and more - all via a structured tool-use loop with optional confirmation prompts before side-effects. + +### System Requirements + +- An API key for at least one AI provider: **Anthropic** or **OpenRouter** +- **PostgreSQL** (with asyncpg) - the main application database +- PostgreSQL + **pgvector** extension only required if you use the *2nd Brain* feature (can be the same server) + +### First-Time Setup Checklist + +1. Copy `.env.example` to `.env` and set `AIDE_DB_URL` (PostgreSQL connection string) and `DB_MASTER_PASSWORD` +2. Start with `docker compose up -d` +3. On first boot with zero users, you are redirected to `/setup` to create the first admin account +4. Open **Settings - Credentials** and add your AI provider API key and any additional credentials (CalDAV, email, Pushover, etc.) +5. Add email recipients via **Settings - Whitelists - Email Whitelist** +6. Add filesystem directories via **Settings - Whitelists - Filesystem Sandbox** - the agent cannot touch any path outside these directories +7. Optionally set `system:users_base_folder` in Credentials to enable per-user file storage (e.g. `/data/users`) +8. Optionally configure email accounts and Telegram via their respective Settings tabs + +### Key Concepts + +**Agent** - A configured AI persona with a model, system prompt, optional schedule, and restricted tool set. Agents run headlessly - no confirmation prompts, results logged in run history. + +**Tool** - A capability the AI can invoke: read a file, send an email, fetch a web page, generate an image, etc. Every tool call is logged in the Audit Log. + +**Confirmation** - Before any side-effect tool (send email, write file, delete calendar event) executes in interactive chat, a modal asks you to approve or deny. Agents skip confirmations. + +**Audit Log** - An append-only record of every tool call, its arguments, and outcome. Never auto-deleted unless you configure a retention period. + +**Credential Store** - An AES-256-GCM encrypted key-value store in PostgreSQL. All secrets (API keys, passwords) live here - never in the agent's context window. + +**User Folder** - When `system:users_base_folder` is set, each user gets a personal folder at `{base}/{username}/`. Agents and the Files page scope all file access to this folder automatically. + +### Quick Start + +Navigate to the [Chat](/) page, type a message and press `Enter`. The agent responds, uses tools as needed (you'll see spinning indicators), and may ask for confirmation before sending email or writing files. + +--- + +## Chat Interface + +### Sending Messages + +Press `Enter` to send. Use `Shift+Enter` for a newline within your message. The **Clear History** button (✕) in the status bar wipes the in-memory conversation for the current session - the agent starts fresh. + +### File Attachments + +The **paperclip button** (📎) in the input bar opens a file picker. Only shown when the active model supports vision or documents. Supported formats: + +- **Images**: JPEG, PNG, GIF, WebP, AVIF - shown as thumbnails in the preview strip +- **PDF**: shown as a file chip with the filename in the preview strip + +You can also **paste images** directly from the clipboard (Ctrl/Cmd+V in the chat input). Multiple files can be attached in one message. Remove any attachment by clicking the ✕ on its preview chip. + +> Attachments are sent inline with the message as base64-encoded data. Large files (especially PDFs) will increase the token count and cost of the request. + +### Model Picker + +The button in the status bar (bottom of the chat area) shows the currently active model. Click it to open a searchable modal listing all available models from all configured providers. Use arrow keys to navigate, `Enter` to select, `Esc` to close. Your selection is persisted in `localStorage` across page loads. + +### Capability Badges + +Small badges in the status bar show what the active model supports: + +- 🎨 **Image Gen** - can generate images (use via the `image_gen` tool in agents) +- 👁 **Vision** - can read images and PDFs; the attachment button is shown +- 🔧 **Tools** - supports tool/function calling +- 🌐 **Online** - has live web access built in + +### Tool Indicators + +While the agent is working, small badges appear below each message: + +- Pulsing blue - tool is currently running +- Solid green - tool completed successfully +- Solid red - tool failed or returned an error + +### Confirmation Modal + +When the agent wants to execute a side-effect tool (send email, write/delete a file, send a push notification), a yellow modal appears showing the tool name and arguments. Click **Approve** to proceed or **Deny** to block the action. The agent receives your decision and continues. + +### Pausing the Agent + +The **Pause** button in the sidebar is a global kill switch. While paused, no agent runs, scheduled tasks, inbox processing, or Telegram responses will execute. The button turns green and shows **Resume** when paused. Click it again to re-enable everything. + +--- + +## Files + +The [Files](/files) page is a browser for your personal data folder (provisioned automatically when `system:users_base_folder` is configured by your admin). + +### Browsing + +- Click a folder to enter it. Use the breadcrumb trail at the top to navigate back. +- Hidden files (names starting with `.`) are not shown. +- Columns show file size and last-modified timestamp. + +### Downloading + +- **Download** - downloads an individual file. +- **↓ ZIP** - downloads an entire folder (and its contents) as a ZIP archive. + +### Deleting Files + +A red **Delete** button appears next to downloadable files. Clicking it shows a confirmation dialog before the file is permanently removed. Deletion is instant and cannot be undone. + +> **Protected files**: files whose names start with `memory_` or `reasoning_` cannot be deleted from the UI. These are agent memory and decision logs maintained by email handling agents. + +### No Folder Configured? + +If the Files page shows "No files folder configured", ask your administrator to set the `system:users_base_folder` credential to a base path (e.g. `/data/users`). Your personal folder at `{base}/{username}/` is created automatically. + +--- + +## Agents + +Agents are headless AI personas with a fixed system prompt, model, and optional cron schedule. Unlike interactive chat, agents run without confirmation modals - their allowed tools are declared at creation time. Results and token usage are logged per-run in the [Agents](/agents) page. + +> Email handling agents (created automatically by Email Accounts setup) are hidden from the Agents list. They are managed exclusively via **Settings - Email Accounts**. + +### Creating Agents + +Click **New Agent** on the Agents page. Required fields: + +- **Name** - displayed in the UI and logs +- **Model** - any model from a configured provider +- **Prompt** - the agent's task description or system prompt (see Prompt Modes below) + +Optional fields: + +- **Description** - shown in the agent list for reference +- **Schedule** - cron expression for automatic runs +- **Allowed Tools** - restrict which tools the agent may use +- **Max Tool Calls** - per-run limit (overrides the system default) +- **Sub-agents** - toggle to allow this agent to create child agents +- **Prompt Mode** - controls how the prompt is composed (see below) + +### Scheduling + +Enter a cron expression in the **Schedule** field. The format is: + +``` +minute hour day-of-month month day-of-week +``` + +Examples: + +- `0 8 * * 1-5` - weekdays at 08:00 +- `*/15 * * * *` - every 15 minutes +- `0 9 * * 1` - every Monday at 09:00 +- `30 18 * * *` - every day at 18:30 + +Use the **Enable / Disable** toggle to pause a schedule without deleting the agent. The **Run Now** button triggers an immediate run regardless of schedule. + +### Prompt Modes + +Three modes control how the agent prompt is combined with the standard system prompt (SOUL.md + security rules): + +**Combined** *(default)* - The agent prompt is prepended as the highest-priority instruction. The standard system prompt (SOUL.md, date/time, USER.md, security rules) is appended after. Best for most agents. + +**System only** - The standard system prompt is used as-is; the agent prompt becomes the task message sent to the agent. Useful when you want the agent's full personality but just need to specify a recurring task. + +**Agent only** - The agent prompt *fully replaces* the system prompt - no SOUL.md, no security rules, no USER.md context. Use with caution. Suitable for specialized agents with a completely different persona. + +### Tool Restrictions + +Leave **Allowed Tools** blank to give the agent access to all tools. Select specific tools to restrict - only those tool schemas are sent to the model, making it structurally impossible to use undeclared tools. + +MCP server tools appear as a single server-level toggle (e.g. `Gitea MCP`), which enables all tools from that server. + +Follow the **least-privilege principle**: give each agent only the tools it actually needs. + +### Sub-agents + +Enable the **Sub-agents** toggle to give an agent access to the `create_subagent` tool. This allows the agent to spin up child agents to handle parallel or specialized tasks. Sub-agents run synchronously (the parent waits for the child to finish) and are logged separately in run history. + +### Image Generation in Agents + +Agents can generate images using the `image_gen` tool. Important: the **agent model must be a text/tool-use model** (e.g. Claude Sonnet), not an image-generation model. The `image_gen` tool calls the image-gen model internally, saves the result to disk, and returns the file path. The default image-gen model is `openrouter:openai/gpt-5-image` - override via the `system:default_image_gen_model` credential. + +Generated images are saved to the agent's user folder. The file path is returned as the tool result so the agent can reference it. + +--- + +## MCP Servers + +**MCP (Model Context Protocol)** is an open protocol for exposing tools to AI models over a network. oAI-Web can connect to external MCP servers and use their tools exactly like built-in tools. Tool names are namespaced as `mcp__{server}__{tool}`. + +### Requirements for a Compatible MCP Server + +- Expose an SSE endpoint at `/sse` +- Use **SSE transport** (not stdio) +- Be compatible with `mcp==1.26.*` +- If built with Python FastMCP: use `uvicorn.run(mcp.sse_app(), host=..., port=...)` - **not** `mcp.run(host=..., port=...)` (the latter ignores `host`/`port` in mcp 1.26) +- If connecting from a non-localhost IP (e.g. `192.168.x.x`): disable DNS rebinding protection: + +```python +from mcp.server.transport_security import TransportSecuritySettings +mcp = FastMCP( + "my-server", + transport_security=TransportSecuritySettings( + enable_dns_rebinding_protection=False + ), +) +``` + +Without this, the server rejects requests with a `421 Misdirected Request` error. + +- oAI-Web connects per-call (open - use - close), *not* persistent - the server must handle this gracefully + +### Adding an MCP Server + +1. Go to **Settings - MCP Servers** +2. Click **Add Server** +3. Enter: + - **Name** - display name; also used for tool namespacing (slugified) + - **URL** - full SSE endpoint, e.g. `http://192.168.1.72:8812/sse` + - **Transport** - select `sse` + - **API Key** - optional bearer token if the server requires authentication +4. Click **Save** + +oAI-Web will immediately attempt to connect and discover tools. The tool count is shown in the server list. + +### Tool Namespacing + +A server named `Gitea MCP` (slugified: `gitea_mcp`) exposes tools as `mcp__gitea_mcp__list_repos`, `mcp__gitea_mcp__create_issue`, etc. In the agent tool picker, the entire server appears as a single toggle. + +### Refreshing Tool Discovery + +Click **Refresh** on any server in **Settings - MCP Servers** to re-discover tools without restarting oAI-Web. + +--- + +## Settings + +### General (Admin) + +- **Agent Control**: Pause / Resume the global kill switch +- **Runtime Limits**: Max Tool Calls (per run) and Max Autonomous Runs per Hour - stored in the credential store for live override without restart +- **Trusted Proxy IPs**: Comma-separated IPs for `X-Forwarded-For` trust (requires restart) +- **Users Base Folder**: Set `system:users_base_folder` to an absolute path (e.g. `/data/users`) to enable per-user file storage. Each user's folder at `{base}/{username}/` is created automatically. +- **Audit Log Retention**: Set a retention period in days (0 = keep forever); manual clear available + +### Whitelists (Admin) + +- **Email Whitelist**: Only addresses on this list can receive emails from the agent. Supports per-address daily send limits. +- **Web Whitelist (Tier 1)**: Domains always accessible to the agent, regardless of session type. Subdomains are automatically included (e.g. `wikipedia.org` covers `en.wikipedia.org`). +- **Filesystem Sandbox**: Absolute paths the agent may read/write. The agent cannot access any path outside these directories (unless it falls within a user's personal folder). + +### Credentials (Admin) + +All secrets (API keys, passwords, app settings) are stored in an AES-256-GCM encrypted PostgreSQL table. Keys use a `namespace:key` convention. See [Credential Key Reference](#credential-key-reference-admin) for a full list. + +### Inbox + +The Inbox tab manages **trigger rules** for the legacy global IMAP/SMTP account. For per-user or multi-account email handling, use the **Email Accounts** tab instead. + +- **Trigger Rules**: keyword phrases that, when matched in an incoming email subject/body, dispatch a specific agent and optionally send an auto-reply +- Matching is case-insensitive and order-independent - all tokens in the phrase must appear somewhere in the message + +### Email Accounts + +Email Accounts is the main email management area. Each account is independently configured with its own IMAP credentials and an account type: + +**Trigger account** - Uses IMAP IDLE (instant push). Dispatches agents based on keyword trigger rules in incoming emails. + +**Handling account** - Polls every 60 seconds. A dedicated AI agent reads and handles each email. The agent gets access to email, Telegram (optional), and filesystem tools scoped to the user's data folder. + +For handling accounts, you can also configure: + +- **Extra tools**: optionally give the handling agent access to Telegram and/or Pushover for notifications +- **Telegram keyword**: a short slug (e.g. `work`) that creates a `/work` Telegram command. Send `/work ` to interact with the email agent via Telegram. Built-in sub-commands: `/work pause`, `/work resume`, `/work status` +- **Pause / Resume**: temporarily suspend a handling account without disabling it entirely. Also available via the Telegram `/keyword pause` command + +> The handling agent uses memory files (`memory_.md`) and reasoning logs (`reasoning_.md`) stored in the user's data folder to maintain continuity across email sessions. + +### Telegram + +- **Bot Token**: your Telegram bot's API token (from @BotFather). Admins set a global token here; non-admin users can set their own per-user token in their Profile tab. +- **Chat ID Whitelist**: only messages from listed chat IDs are processed +- **Default Agent**: agent dispatched for messages that don't match any trigger rule +- **Trigger Rules**: same keyword-matching logic as email inbox + +### Profile + +Available to all users. Contains: + +- **Theme**: choose from 7 built-in themes (Dark, Darker, Light, Nord, Solarized Dark, Gruvbox, Catppuccin Mocha). Applied immediately with no flash of wrong theme. +- **Account Info**: username and email (read-only); editable display name +- **Change Password**: update your login password +- **Two-Factor Authentication (TOTP)**: enable/disable TOTP-based MFA. On setup, a QR code is shown to scan with any authenticator app (e.g. Aegis, Google Authenticator). Once enabled, every login requires a 6-digit code. +- **Data Folder**: shows the path of your auto-provisioned personal folder. +- **Telegram Bot Token**: per-user Telegram bot token (optional). Overrides the global token for your sessions. +- **CalDAV**: per-user CalDAV server, credentials, and calendar name. Overrides the global CalDAV config. + +### Personality + +Edit **SOUL.md** (agent identity, values, communication style) and **USER.md** (owner context: name, location, preferences) directly in the browser. Changes take effect immediately - no restart required. Both files are injected into every system prompt in order: SOUL.md - date/time - USER.md - security rules. + +### 2nd Brain + +Requires PostgreSQL + pgvector (`BRAIN_DB_URL` env var). When connected, shows connection status, recent captured thoughts, and a manual capture form. The brain MCP server is exposed at `/brain-mcp/sse` and requires the `brain:mcp_key` credential for authentication. + +### MCP Servers (Settings) + +Add, edit, remove, enable/disable, and refresh external MCP servers. See the [MCP Servers](#mcp-servers) section for full setup details. + +### Security (Admin) + +Five independently toggleable security options: + +1. **Enhanced Sanitization**: strips extended prompt-injection patterns from all external content +2. **Canary Token**: a daily-rotating secret injected into the system prompt; if it appears in any tool argument, the call is blocked and you receive a Pushover alert +3. **LLM Content Screening**: after fetching web/email/file content, sends it to a cheap screening model for a SAFE/UNSAFE verdict before returning it to the agent +4. **Output Validation**: blocks email auto-replies from inbox sessions back to the trigger sender (prevents exfiltration loops) +5. **Content Truncation**: caps content length from web fetch, email, and file reads to configurable character limits + +### Branding (Admin) + +Customize the sidebar brand name and logo. Upload a PNG/JPG/GIF/WebP/SVG logo (max 2 MB). Changes take effect immediately. Reset to defaults by clearing the name field or deleting the logo. + +### API Key (Admin) + +Protects the REST API for external programmatic access. The **web UI always works without a key** - a signed session cookie is set automatically on login. The API key is only required for external tools and scripts calling `/api/*` directly, and for Swagger UI at `/docs`. + +The raw key is shown **once** at generation time - copy it to your external tool. Only a SHA-256 hash is stored server-side. Regenerating invalidates the previous key immediately. + +Use header `X-API-Key: ` or `Authorization: Bearer ` in external requests. If no key is configured, the API is open (home-network default). + +--- + +## User Management (Admin) + +oAI-Web supports multiple users with role-based access. Manage users at [Admin - Users](/admin/users). + +### Roles + +**Admin** - Full access to all settings, whitelists, credentials, and user management. Can see and manage all agents and audit logs across all users. + +**User** - Access to chat, agents, files, and their own settings (Profile, CalDAV, Telegram, Email Accounts, MCP Servers). Cannot access system-wide whitelists, credentials, branding, or security settings. + +### Creating Users + +1. Go to [Admin - Users](/admin/users) +2. Click **New User** +3. Enter username, email, password, and select a role +4. If `system:users_base_folder` is configured, a personal folder is created automatically at `{base}/{username}/` + +### MFA Management + +Users set up their own TOTP in **Settings - Profile - Two-Factor Authentication**. As admin, you can clear any user's MFA from the Users page using the **Clear MFA** button - they must set it up again on next login. + +### User Filesystem Scoping + +Non-admin users' agents automatically receive a **scoped filesystem tool** limited to their personal folder (`{base}/{username}/`). They cannot access paths outside their folder, even if those paths are in the global filesystem whitelist. + +--- + +## Credential Key Reference (Admin) + +All keys are stored in the encrypted credential store. System keys use the `system:` prefix. + +| Key | Description | +|-----|-------------| +| `system:paused` | Kill switch - set to `"1"` to pause all agent activity | +| `system:max_tool_calls` | Live override of MAX_TOOL_CALLS env var | +| `system:max_autonomous_runs_per_hour` | Live override of MAX_AUTONOMOUS_RUNS_PER_HOUR | +| `system:audit_retention_days` | Days to keep audit entries (0 = keep forever) | +| `system:trusted_proxy_ips` | Comma-separated IPs for X-Forwarded-For trust (requires restart) | +| `system:users_base_folder` | Base path for per-user folders (e.g. `/data/users`) | +| `system:default_image_gen_model` | Model used by the `image_gen` tool (default: `openrouter:openai/gpt-5-image`) | +| `system:brand_name` | Custom sidebar brand name | +| `system:brand_logo_filename` | Custom sidebar logo filename in /static/ | +| `system:security_sanitize_enhanced` | Option 1: enhanced injection pattern sanitization | +| `system:security_canary_enabled` | Option 2: canary token detection enabled | +| `system:canary_token` | Auto-generated daily canary token (read-only) | +| `system:canary_rotated_at` | Timestamp of last canary rotation (read-only) | +| `system:security_llm_screen_enabled` | Option 3: LLM content screening enabled | +| `system:security_llm_screen_model` | Model for LLM screening (default: google/gemini-flash-1.5) | +| `system:security_llm_screen_block` | Option 3 block mode - block vs flag on UNSAFE verdict | +| `system:security_output_validation_enabled` | Option 4: output validation for inbox sessions | +| `system:security_truncation_enabled` | Option 5: content truncation | +| `system:security_max_web_chars` | Max chars from web fetch (default: 20 000) | +| `system:security_max_email_chars` | Max chars from email body (default: 6 000) | +| `system:security_max_file_chars` | Max chars from file read (default: 20 000) | +| `system:security_max_subject_chars` | Max chars of email subject (default: 200) | +| `telegram:bot_token` | Global Telegram bot API token | +| `telegram:default_agent_id` | UUID of agent for unmatched Telegram messages | +| `pushover_user_key` | Pushover user key | +| `pushover_app_token` | Pushover application token | +| `caldav_calendar_name` | Optional CalDAV calendar name override (global) | +| `brain:mcp_key` | 2nd Brain MCP authentication key | +| `system:api_key_hash` | SHA-256 hash of the external API key (raw key never stored) | +| `system:api_key_created_at` | Timestamp of last API key generation | +| `system:session_secret` | HMAC secret for signing web UI session cookies (auto-generated) | + +--- + +## Security Model + +### Core Principle + +**External input is data, never instructions.** Email body text, calendar content, web page content, and file contents are all passed as *tool results* - they are never injected into the system prompt where they could alter the agent's instructions. + +### Three DB-Managed Whitelists + +- **Email whitelist** - the agent can only send email to addresses explicitly approved here +- **Web whitelist (Tier 1)** - domains always accessible; subdomains included automatically +- **Filesystem sandbox** - the agent can only read/write within declared directories (or a user's personal folder) + +Tier 2 web access (any URL) is only available in user-initiated chat sessions, never in autonomous agent runs. + +### User Filesystem Isolation + +Non-admin users' agents use a **scoped filesystem tool** restricted to their personal folder (`{base}/{username}/`). This is enforced at the tool level regardless of what the agent prompt says. + +### Confirmation Flow + +In interactive chat, any tool with side effects (send email, write/delete files, send notifications, create/delete calendar events) triggers a confirmation modal. The agent pauses until you approve or deny. Agents running headlessly skip confirmations - their scope is declared at creation time. + +### Five Security Options + +1. **Enhanced Sanitization** - removes known prompt-injection patterns from all external content before it reaches the agent +2. **Canary Token** - a daily-rotating secret in the system prompt; any tool call argument containing the canary is blocked and triggers a Pushover alert +3. **LLM Content Screening** - a cheap secondary model screens fetched content for malicious instructions; operates in flag or block mode +4. **Output Validation** - prevents inbox auto-reply loops by blocking outbound emails back to the triggering sender +5. **Content Truncation** - enforces maximum character limits on web fetch, email, and file content + +### Audit Log + +Every tool call - arguments, result summary, confirmation status, session ID, task ID - is written to an append-only audit log. Logs are never auto-deleted unless you configure a retention period. View them at [Audit Log](/audit). + +### Kill Switch + +The **Pause** button in the sidebar immediately halts all agent activity: no new runs, no inbox processing, no Telegram responses. The `system:paused` credential stores the state and is checked before every operation. Individual email handling accounts can also be paused independently via their Telegram keyword command or the Email Accounts UI. + +### No Credentials in Agent Context + +API keys, passwords, and tokens are only accessed by the server-side tool implementations. The agent itself never sees a raw credential - it only receives structured results (e.g. a list of calendar events, a fetched page). + +--- + +## Telegram and Email Inbox + +### Telegram Setup + +oAI-Web connects to Telegram via long-polling (no webhook required). Admin setup: + +1. Create a bot via @BotFather and copy the bot token +2. Go to **Settings - Telegram** and save the bot token +3. Add your Telegram chat ID to the whitelist (messages from unlisted IDs are silently dropped) +4. Optionally set a default agent for messages that don't match any trigger rule +5. Add trigger rules to route specific messages to specific agents + +Non-admin users can also set their own Telegram bot token under **Settings - Profile - Telegram Bot Token**. This creates a personal bot that routes to agents and email accounts scoped to that user. + +Each chat maintains its own conversation history, persisted in memory and reset on server restart. + +### Telegram Keyword Commands (Email Handling) + +When an email handling account has a **Telegram keyword** set (e.g. `work`), Telegram messages starting with `/work` are routed directly to that email account's agent. + +Built-in sub-commands (example for keyword `work`): + +- `/work pause` - temporarily pause the email account's listener +- `/work resume` - resume the listener +- `/work status` - show the account's current status +- `/work ` - pass the message to the handling agent + +> Only the Telegram chat ID associated with the email account can use its keyword commands. Other chat IDs are rejected. + +### Email Inbox - Trigger Accounts + +Trigger accounts use IMAP IDLE for instant push notification. When a new email arrives: + +1. Subject + body matched against trigger rules; the first match wins +2. If matched, the corresponding agent is dispatched; an auto-reply is sent if configured +3. If no trigger matches, the email is silently ignored + +Sender whitelist check behaviour: + +- Whitelisted sender + matching trigger - agent runs, reply sent +- Whitelisted sender + no trigger - "no trigger word" reply +- Non-whitelisted sender + matching trigger - agent runs, but Output Validation blocks the reply +- Non-whitelisted sender + no trigger - **silently dropped** (reveals nothing to the sender) + +### Email Inbox - Handling Accounts + +Handling accounts poll every 60 seconds. A dedicated AI agent reads each new email and decides how to handle it. The agent has access to: + +- **Email tool** - list, read, mark as read, move, create folders +- **Filesystem tool** - scoped to the user's data folder (if configured) +- **Memory files** - `memory_.md` (persistent notes) and `reasoning_.md` (append-only decision log) are injected into each run +- **Telegram tool** (optional) - bound to the account's associated chat ID; reply messages automatically include a `/keyword ` footer for easy follow-up +- **Pushover tool** (optional, admin only) + +### Trigger Rule Matching + +Both Telegram and email inbox use the same trigger-matching algorithm: + +- **Case-insensitive** - `URGENT` matches `urgent` +- **Order-independent** - all tokens in the trigger phrase must appear somewhere in the message, but not necessarily in sequence +- Example: trigger phrase `daily report` matches *"Send me the report for the daily standup"* but also *"Daily summary report please"*