oAI-Web / Jarvis¶
oAI-Web is a secure, self-hosted personal AI agent built on the Anthropic Claude API. It runs on your home server or Mac, exposes a clean web interface for local-network use, and integrates with email, calendar, Telegram, and more.
The agent answers to the name Jarvis (configurable via SOUL.md).
What it does¶
- Chat interface — multi-turn conversations with tool use, image uploads, and model switching
- Autonomous agents — goal-oriented agents with cron schedules, run history, and token tracking
- Tool ecosystem — email, CalDAV, filesystem, web search, Pushover, Telegram, browser automation, image generation, webhooks, MCP servers
- 2nd Brain — personal knowledge base backed by PostgreSQL + pgvector (semantic search)
- Email inbox — IMAP trigger rules that dispatch agents on incoming messages
- Monitors — RSS feeds and CSS-selector page watchers that trigger agents on changes
- Multi-user — role-based access (admin / user), Argon2 passwords, TOTP MFA
Quick start¶
# 1. Copy and fill in environment variables
cp .env.example .env
# 2. Start PostgreSQL + the app
docker compose up -d
# 3. Open in browser
open http://localhost:8080
First run shows a setup wizard to create the admin account.
Documentation map¶
| Section | What you'll find |
|---|---|
| Getting Started | Installation, first run, initial configuration |
| Architecture | System design, component map, agent loop |
| Security | Whitelists, prompt injection guards, audit log |
| Tools | All 15 tools — parameters, restrictions, examples |
| Web Interface | UI pages and the WebSocket protocol |
| API Reference | All REST endpoints with request/response shapes |
| Integrations | Telegram, Email Inbox, CalDAV, MCP Servers |
| Deployment | Docker, local dev, reverse proxy setup |
| Configuration | All environment variables |
| Database | PostgreSQL schema and migration system |
| AI Providers | Anthropic, OpenRouter, OpenAI setup |
Core design principles¶
- External input is data, not instructions — email bodies, calendar events, and fetched web pages are passed as tool results, never injected into the system prompt
- Whitelists are database-managed — email recipients, allowed web domains, and filesystem sandbox paths are stored in PostgreSQL and managed through the Settings UI
- Confirmation before side effects — sending email, writing files, and creating calendar events require explicit user approval in interactive sessions
- Scheduled permissions declared at creation — an agent's allowed tools are baked in when it's created; it cannot escalate its own permissions at runtime
- Audit log is append-only — every tool call is logged; records are never auto-deleted (configurable retention with explicit purge)
- No credentials in context — the server holds API keys and returns results; raw secrets never appear in the agent's context window