rune/oai-web
1
0
Fork 0
Code Issues Pull Requests Packages Wiki Activity

Update Home

rune
2026-04-09 13:13:08 +02:00
parent 5c65cc690d
commit af903dec04
1 changed files with 23 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
Home.md

@@ -18,9 +18,6 @@
- [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)
@@ -28,11 +25,6 @@
- [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)
@@ -44,23 +36,6 @@
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.
@@ -69,11 +44,9 @@ oAI-Web is a secure, self-hosted personal AI agent built on the Claude API with
**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.
**Audit Log** - An append-only record of every tool call, its arguments, and outcome.
**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.
**User Folder** - Each user gets a personal folder for file storage. Agents and the Files page scope all file access to this folder automatically.
### Quick Start
@@ -131,7 +104,7 @@ The **Pause** button in the sidebar is a global kill switch. While paused, no ag
## 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).
The [Files](/files) page is a browser for your personal data folder.
### Browsing
@@ -152,7 +125,7 @@ A red **Delete** button appears next to downloadable files. Clicking it shows a
### 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.
If the Files page shows "No files folder configured", contact your administrator.
---
@@ -220,7 +193,7 @@ Enable the **Sub-agents** toggle to give an agent access to the `create_subagent
### 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.
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.
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.
@@ -230,28 +203,6 @@ Generated images are saved to the agent's user folder. The file path is returned
**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**
@@ -277,27 +228,9 @@ Click **Refresh** on any server in **Settings - MCP Servers** to re-discover too
## 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.
The Inbox tab manages **trigger rules** for the global IMAP 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
@@ -308,7 +241,7 @@ Email Accounts is the main email management area. Each account is independently
**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.
**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 your data folder.
For handling accounts, you can also configure:
@@ -316,11 +249,11 @@ For handling accounts, you can also configure:
- **Telegram keyword**: a short slug (e.g. `work`) that creates a `/work` Telegram command. Send `/work <message>` 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_<username>.md`) and reasoning logs (`reasoning_<username>.md`) stored in the user's data folder to maintain continuity across email sessions.
> The handling agent uses memory files (`memory_<username>.md`) and reasoning logs (`reasoning_<username>.md`) stored in your 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.
- **Bot Token**: your Telegram bot's API token (from @BotFather). Set your own per-user token in the 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
@@ -333,7 +266,7 @@ Available to all users. Contains:
- **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.
- **Data Folder**: shows the path of your personal folder used by agents and the Files page.
- **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.
@@ -343,101 +276,12 @@ Edit **SOUL.md** (agent identity, values, communication style) and **USER.md** (
### 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.
When connected, shows connection status, recent captured thoughts, and a manual capture form.
### 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: <key>` or `Authorization: Bearer <key>` 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
@@ -446,37 +290,31 @@ All keys are stored in the encrypted credential store. System keys use the `syst
**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
### Whitelists
- **Email whitelist** - the agent can only send email to addresses explicitly approved here
The system enforces three whitelists:
- **Email whitelist** - the agent can only send email to addresses explicitly approved by your admin
- **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)
- **Filesystem sandbox** - the agent can only read/write within declared directories (or your personal folder)
Tier 2 web access (any URL) is only available in user-initiated chat sessions, never in autonomous agent runs.
### User Filesystem Isolation
### Your Filesystem is Isolated
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.
Your agents use a **scoped filesystem tool** restricted to your personal folder. You cannot access paths outside your folder, regardless of what an 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).
Every tool call - arguments, result summary, confirmation status, session ID - is written to an append-only audit log. 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.
The **Pause** button in the sidebar immediately halts all agent activity: no new runs, no inbox processing, no Telegram responses. Individual email handling accounts can also be paused independently via their Telegram keyword command or the Email Accounts UI.
### No Credentials in Agent Context
@@ -488,15 +326,9 @@ API keys, passwords, and tokens are only accessed by the server-side tool implem
### 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.
2. Go to **Settings - Profile - Telegram Bot Token** and save your token
3. Your Telegram chat ID must be on the whitelist - contact your admin if messages aren't being processed
Each chat maintains its own conversation history, persisted in memory and reset on server restart.
@@ -521,22 +353,14 @@ Trigger accounts use IMAP IDLE for instant push notification. When a new email a
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)
- **Filesystem tool** - scoped to your data folder (if configured)
- **Memory files** - `memory_<username>.md` (persistent notes) and `reasoning_<username>.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 <reply>` footer for easy follow-up
- **Pushover tool** (optional, admin only)
### Trigger Rule Matching