oAI-Web is a secure, self-hosted personal AI agent 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.

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.

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

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

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 page is a browser for your personal data folder.

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", contact your administrator.

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 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.

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}.

Adding an MCP Server

Go to Settings - MCP Servers
Click Add Server
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
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

Inbox

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

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 your 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 <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 your data folder to maintain continuity across email sessions.

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

DAV (CalDAV / CardDAV)

Configure your personal CalDAV and CardDAV connection. Admin users see this as the DAV tab; regular users see it as the CalDAV / CardDAV tab. There is no system-wide fallback — each user configures their own credentials independently.

CalDAV: server URL, username, password, and calendar name for reading and writing calendar events
CardDAV: tick "Same server as CalDAV" to reuse the same credentials, or enter separate CardDAV URL, username, and password
Allow contact writes: when enabled, agents can create, update, and delete contacts (not just read them)
Test buttons: verify your CalDAV and CardDAV connections without leaving the settings page

Pushover

Pushover sends push notifications to your iOS or Android device.

Admin tab: sets the shared App Token (registered once for the oAI-Web installation) and the admin's personal User Key
User tab: set your personal User Key — the App Token is provided by the admin and shared by all users

Each user's User Key maps to their own Pushover account and devices. The App Token is shared across all users of the same oAI-Web instance — this is the standard Pushover model (one app, many users).

To get your User Key: log in to pushover.net — it's shown on the dashboard immediately.

Webhooks

Inbound webhooks let external services (iOS Shortcuts, GitHub, Home Assistant, IFTTT) trigger agents via HTTP.

Create a webhook: give it a name, description, and assign an agent. The token is shown once at creation — copy it immediately.
Trigger via POST: POST /webhook/{token} with body {"message": "your message"}
Trigger via GET: GET /webhook/{token}?q=your+message (useful for iOS Shortcuts URL actions)
Rotate token: generates a new token and invalidates the old one
Enable/disable: toggle without deleting the webhook

Outbound webhook targets (for agents to call external services) are managed in the same tab under "Outbound Targets".

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 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.

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

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 section for full setup details.

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.

Whitelists

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 your personal folder)

Tier 2 web access (any URL) is only available in user-initiated chat sessions, never in autonomous agent runs.

Your Filesystem is Isolated

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.

Audit Log

Every tool call - arguments, result summary, confirmation status, session ID - is written to an append-only audit log. View them at Audit Log.

Kill Switch

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

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

Create a bot via @BotFather and copy the bot token
Go to Settings - Profile - Telegram Bot Token and save your token
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.

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 <any message> - 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:

Subject + body matched against trigger rules; the first match wins
If matched, the corresponding agent is dispatched; an auto-reply is sent if configured
If no trigger matches, the email is silently ignored

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 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

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"

Full help section in the app for both admins and users!

oAI-Web - Help

Table of Contents

Getting Started

What is oAI-Web?