Skip to content

First Run

Environment Variables

Before starting, open .env and fill in the values. Required fields are marked with *.

AI Provider

# Which provider to use as default: anthropic | openrouter | openai
DEFAULT_PROVIDER=anthropic

# Override the default model (leave empty to use the provider's default)
# DEFAULT_MODEL=claude-sonnet-4-6

# Model pre-selected in the chat UI (leave empty to use provider default)
# DEFAULT_CHAT_MODEL=claude-sonnet-4-6

Your actual API keys are not set here — they are entered via the web UI under Settings → Credentials and stored encrypted in the database.

Security *

# Master password for the encrypted credential store.
# All your API keys, passwords, and secrets are encrypted with this.
# Choose a strong passphrase and keep it safe - if lost, credentials cannot be recovered.
DB_MASTER_PASSWORD=change-me-to-a-strong-passphrase

Server

# Port the web interface listens on (default: 8080)
PORT=8080

# Timezone for display - dates are stored internally as UTC
TIMEZONE=Europe/Oslo

Agent Limits

# Maximum number of tool calls per agent run
MAX_TOOL_CALLS=20

# Maximum number of autonomous (scheduled/agent) runs per hour
MAX_AUTONOMOUS_RUNS_PER_HOUR=10

Both values can also be changed live from Settings → General without restarting.

Database *

# Main application database
AIDE_DB_URL=postgresql://aide:change-me@postgres:5432/aide

# 2nd Brain database password (pgvector)
BRAIN_DB_PASSWORD=change-me-to-a-strong-passphrase

# Brain connection string - defaults to the bundled postgres service
BRAIN_DB_URL=postgresql://brain:${BRAIN_DB_PASSWORD}@postgres:5432/brain

# Access key for the Brain MCP endpoint (generate with: openssl rand -hex 32)
BRAIN_MCP_KEY=

Change the change-me passwords in AIDE_DB_URL and BRAIN_DB_PASSWORD to something strong. They must match — if you change BRAIN_DB_PASSWORD, the same value is substituted into BRAIN_DB_URL automatically.

Setup wizard

When you open oAI-Web for the first time, you'll be redirected to /setup. This wizard creates the admin account.

  1. Enter a username and password
  2. Click Create admin account
  3. You'll be redirected to the login page

Configuring your AI provider

After logging in, go to Settings → General and select your Default Provider (Anthropic, OpenRouter, or OpenAI).

Then go to Settings → Credentials and add your API key:

  • system:anthropic_api_key for Anthropic Claude
  • system:openrouter_api_key for OpenRouter
  • system:openai_api_key for OpenAI

The API key is encrypted at rest using AES-256-GCM.

Personalising the agent

SOUL.md — Agent identity and personality

SOUL.md defines who your agent is. The name is extracted automatically from the first line matching You are **Name**.

Key sections to edit:

Name — change Jarvis to whatever you want your agent to be called: 

You are **Jarvis**, a personal AI assistant...

Character — describe how you want the agent to behave. Be specific. Examples: - "You are concise and avoid unnecessary commentary." - "You are proactive — if you notice something relevant while completing a task, mention it briefly." - "You never use bullet points unless explicitly asked."

Values — define what the agent should prioritise: - Privacy, minimal footprint, and transparency are good defaults. - Add domain-specific values if relevant (e.g. "always prefer open-source tools when suggesting options").

Language — specify language behaviour explicitly: - "Always respond in the same language the user wrote in." - "Default to Norwegian unless the message is in another language."

Communication style — tune the tone: - Formal vs. casual, verbose vs. terse, proactive vs. reactive. - You can ban specific phrases: "Never start a response with 'Certainly!' or 'Of course!'."

The file is mounted read-only into the container. Changes take effect on the next docker compose restart.

USER.md — Context about you

USER.md gives the agent background knowledge about you. It is injected into every system prompt, so keep it factual and relevant — not a biography.

Identity — name, location, timezone. These help the agent interpret time references and address you correctly.

## Identity

- **Name**: Jane
- **Location**: Oslo, Norway
- **Timezone**: Europe/Oslo

Language preferences — override SOUL.md language rules for your specific case:

## Language

- Respond in the exact language the user's message is written in.
- Do not assume Norwegian because of my location.

Professional context — role and responsibilities the agent should be aware of:

## Context and background

- Works as a software architect
- Primarily works with Python and Kubernetes
- Manages a small team of three developers

People — names and relationships. Helps the agent interpret messages like "send this to my manager":

## People

- [Alice Smith] - Manager
- [Bob Jones] - Colleague, backend team
- [Sara Lee] - Partner

Recurring tasks and routines — anything time-sensitive the agent should know about:

## Recurring tasks and routines

- Weekly team standup every Monday at 09:00
- Monthly report due on the last Friday of each month

Hobbies and interests — optional, but helps the agent contextualise requests:

## Hobbies and Interests

- Photography
- Self-hosting and home lab
- Cycling in summer

The file is mounted read-only into the container. Changes take effect on the next docker compose restart.

Per-user personality

Each user can also set their own personality override via Settings → Personality without modifying the global files.

Sending your first message

  1. Click the chat icon in the sidebar (or navigate to /)
  2. Type a message and press Enter or click Send
  3. The agent will respond, using tools as needed

The status bar shows the active model. Click it to open the model picker and switch to any available model.

Your Settings

After logging in, go to Settings to configure your personal services. Each user has their own credentials — nothing is shared with other users.

CalDAV / CardDAV

Set up your personal calendar and contacts server under Settings → CalDAV / CardDAV:

  • Enter your server URL (e.g. mail.example.com), username, and password
  • Optionally specify a calendar name (leave blank for the default calendar)
  • For CardDAV (contacts): tick Same server as CalDAV to reuse your credentials, or enter separate details
  • Use the Test buttons to verify your connection before saving
  • Enable Allow contact writes if you want agents to be able to create and update contacts

There is no system-wide fallback — if you don't configure it, calendar and contacts tools won't be available to your agents.

Pushover

To receive push notifications on your iOS or Android device:

  1. Create a free account at pushover.net
  2. Copy your User Key from the dashboard
  3. Go to Settings → Pushover and save your User Key

The app is already registered by your admin — you only need your own User Key.

Webhooks

Create inbound webhooks under Settings → Webhooks to trigger your agents from external services:

  • Assign a name and target agent, then copy the secret token shown at creation (it's shown only once)
  • POST trigger: send {"message": "your message"} to /webhook/{token}
  • GET trigger: visit /webhook/{token}?q=your+message — ideal for iOS Shortcuts URL actions
  • Enable or disable webhooks without deleting them

Telegram

Set your personal bot token under Settings → Telegram (or Settings → Profile → Telegram Bot Token) if you want your own Telegram bot. Your chat ID must be whitelisted by the admin before messages are processed.

Email Accounts

Set up your own email accounts under Settings → Email Accounts:

  • Trigger account — dispatches agents based on keyword rules in incoming emails
  • Handling account — a dedicated AI agent reads and handles each incoming email

Admin: email whitelist

Before the agent can send emails on your behalf, add recipient addresses to the whitelist:

Settings → Whitelists → Email Whitelist → Add

You can also set a daily send limit per address (0 = unlimited).

Admin: filesystem sandbox

Before the agent can read or write files, add allowed directories:

Settings → Whitelists → Filesystem → Add

The path must exist on the server. The agent cannot access paths outside these directories.

Creating your first scheduled agent

  1. Go to Agents in the sidebar
  2. Click New Agent
  3. Fill in:
  4. Name: e.g. "Daily Weather"
  5. Prompt: what you want the agent to do
  6. Schedule: cron expression (e.g. 0 8 * * * for 8am daily)
  7. Allowed Tools: check only the tools this agent needs
  8. Click Save

The agent will run on schedule. You can also trigger it immediately with Run Now.