Skip to content

Installation

Requirements

Install

1. Get the files

Download or copy these files into a directory on your server:

  • docker-compose.example.yml — rename to docker-compose.yml
  • .env.example — rename to .env
  • SOUL.md.example — rename to SOUL.md
  • USER.md.example — rename to USER.md
cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
cp SOUL.md.example SOUL.md
cp USER.md.example USER.md

All files are available in the public repository.

2. Create the data directory

mkdir -p data

3. Configure the environment

Edit .env — see Environment Variables in the First Run guide.

4. Pull and start

docker compose pull
docker compose up -d

Open http://<your-server-ip>:8080 in your browser. See the First Run guide for what to do next.

Updating

docker compose pull
docker compose up -d

Database migrations run automatically on startup — no manual steps needed.

Reverse proxy

oAI-Web runs on HTTP internally. Terminate TLS at your reverse proxy (nginx, Caddy, Zoraxy, etc.).

In Settings → Security, add your proxy's IP to system:trusted_proxy_ips so oAI-Web knows the real client IP.

nginx example (WebSocket support required):

server {
    listen 443 ssl;
    server_name jarvis.yourdomain.local;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_read_timeout 300s;   # long enough for slow agent runs
    }
}

WebSocket timeout: Agent runs can take minutes. Set proxy_read_timeout to at least 300 seconds.

Database backups

PostgreSQL data lives in ./data/postgres. Back it up with:

docker compose exec postgres pg_dump -U brain brain > brain_backup.sql

Or use your preferred PostgreSQL backup tool (pgBackRest, Barman, etc.).

Source code

The public repository is at gitlab.pm/rune/oai-web.