Meet ADI AI, your self-hosted AI command center.

What ADI AI Is

ADI, Advanced Data Intelligence, is a self-hosted AI dashboard. Instead of using one isolated chatbot, ADI gives you one place to talk to models, use voice, show the camera, search the web, remember facts, manage tasks, and call tools connected to your own machines.

The goal is simple: make your AI feel like a capable local assistant, not just a text box. ADI can answer questions, help organize daily work, use connected services, keep useful memory, and show live status so you know what parts of the system are online.

How To Use ADI AI

Open the ADI dashboard, choose or confirm the active model in the top bar, then use the message box at the bottom. You can type a normal request, use the microphone, or ask ADI to use a connected tool.

Feature Guide

ADI is made of several connected features. You can use it as a normal chat app, but the interesting part is that the chat can reach out into voice, vision, memory, tools, and local services.

Understanding The HUD

The HUD is the compact row of icons above the message box. It tells you which services and tools are online, which overlays are active, and whether ADI can reach the systems it depends on.

Settings And Personalization

Settings is where ADI becomes your system instead of a generic interface. The most important tab for connected services is Endpoints, where model hosts and service URLs are managed.

API Keys And Where To Get Them

Provider credentials live under Settings → API Keys. Values are pre-filled from settings and saved in the database; when a field is left empty, the daemon falls back to the matching variable in its .env. Each key is optional — you only need the ones for providers you actually use. Keys are stored per provider in the formats shown below.

After pasting a key, save Settings and reload. If a provider keeps falling back to .env, confirm the matching variable (for example DASHSCOPE_API_KEY) is set for the daemon as well.

How Model Routing Works

The model picker uses the model ID itself to decide which provider handles a request:

• A plain local name routes to your local Ollama at OLLAMA_BASE.
• A :cloud suffix routes the model to Ollama Cloud at ollama.com.
• A provider prefix — openrouter/, mistral/, nvidia/, groq/, deepseek/, and so on — sends the request to that provider's API using its key.

Capability lists in config.php (TOOL_CAPABLE_MODELS, VISION_CAPABLE_MODELS, LIVE_OPTIMIZED_MODELS) tell ADI which models may use tools, accept images, or drive Live mode, so the UI only offers each capability where the chosen model supports it.

Tools, Actions, And Memory

MCP is the layer that lets ADI do useful work beyond answering in text. When tools are available, ADI can call them during a conversation and return the result in the chat.

Tool Categories

• Shopping: list, add, update, mark, delete, and clear shopping items.
• To-Do: tasks, categories, status updates, and task stats.
• Web Search: search the web and fetch URLs.
• MariaDB: inspect tables and run safe read-only queries.
• Files: read, write, search, create folders, and rename within allowed paths.
• Knowledge Graph: create entities, relations, observations, read the graph, search nodes, and open nodes.

Memory Knowledge Graph

The Knowledge Graph stores information as connected facts. For example, ADI can remember that a person owns a project, a service runs on a host, or a preference belongs to a user. This makes memory more structured than a simple note.

How ADI Works Behind The Scenes

This section is for technically curious visitors. ADI is modular: the browser interface talks to PHP endpoints, those endpoints talk to models and databases, and MCP servers expose tools that the assistant can call.

Recommended File Layout

/opt/adi-ai/
  lib/
  schema/
  services/
  mcp/
  private/
    backups/
    feedback/
    logs/
  public/
    api/
    assets/
    uploads/

Feature Art Showcase

These lightweight SVG panels show the major pieces of ADI at a glance. They are local assets, so they can ship with the public site or a GitHub package without remote image dependencies.

Fleet Dashboard

A central control surface for Ollama, voice, vision, local mode, and MCP services.

Streaming Chat

The main conversation surface streams model output while keeping status visible.

Voice and Wake Word

Wake-word, microphone input, transcription, and voice response are part of the live HUD flow.

Vision and Camera

Camera input gives ADI scene context for describe, draw, and multimodal workflows.

MCP Tool Layer

Shopping, tasks, search, files, launchers, and database tools connect through MCP.

Memory Knowledge Graph

Entities, relations, and observations are stored in MariaDB and exposed through the Memory MCP server.

Configurable Endpoints

Ollama, ADI Radio, and web search endpoints can be adjusted from Settings.

Dynamic Backgrounds

Selected video and image backgrounds turn the chat surface into a customizable cockpit.

Feedback Capture

The public feedback form captures issues, ideas, page context, and contact details for follow-up.

Package and Ship

The release package should include source, schema, service templates, installer scripts, and example config.

Technical Install Notes

This part is for people who want to run ADI themselves. A typical installation uses Apache, PHP, MariaDB, Node.js, local model services, and one or more MCP servers.

1. Install Apache, PHP, PHP extensions, MariaDB, Node.js, npm, ffmpeg, git, and any model-specific dependencies.
2. Place the application at /opt/adi-ai and point Apache to /opt/adi-ai/public or serve it under /adi/.
3. Create the MariaDB database and user, then import the schema files for conversations, settings, and MCP memory.
4. Install Node dependencies for each MCP server, such as the Memory Knowledge Graph server.
5. Copy systemd service files into /etc/systemd/system/, reload systemd, and enable the services you want.
6. Open Settings, then confirm endpoints for Ollama, ADI Radio, web search, voice, and MCP tools.

sudo systemctl daemon-reload
sudo systemctl enable --now mcp-memory
sudo systemctl status mcp-memory --no-pager

Operations

Useful Checks

php -l /opt/adi-ai/public/index.php
php -l /opt/adi-ai/public/settings.php
curl -k https://thelab-genesis.local/adi/api/health.php
systemctl status mcp-memory --no-pager
journalctl -u mcp-memory -n 50 --no-pager

Backups

• Back up /opt/adi-ai before structural changes.
• Export MariaDB databases before schema changes.
• Keep private config backups outside the public web root.
• Name backups with dates so cleanup is easy.

Deployment And Access

ADI ships with no built-in user login. The application trusts whoever can reach its origin, so it is designed to sit behind an authenticating reverse proxy. In the reference build that proxy is Cloudflare Access (Zero Trust). If you expose the origin without a gate in front, anyone who can reach it can use the dashboard.

Authentication Model

• There is no app-level password — authentication is delegated entirely to the proxy in front of ADI.
• The sign-out tile links to /cdn-cgi/access/logout, which ends the Cloudflare Access session. This link is host-agnostic and works on any domain behind Access.
• Restrict the origin so it is only reachable through the proxy (a Cloudflare Tunnel does this naturally — the app listens on localhost and is never published directly).

Cloudflare Tunnel Pattern

cloudflared runs on the host and routes the public hostname to Apache on localhost; Cloudflare terminates TLS, so the vhost only needs port 80. Add an ingress entry, route DNS to the tunnel, then create a Zero Trust Access application and policy for the hostname.

# /etc/cloudflared/config.yml
ingress:
  - hostname: ai.example.com
    service: http://localhost:80
    originRequest:
      httpHostHeader: ai.example.com
  - service: http_status:404

cloudflared tunnel route dns <TUNNEL_ID> ai.example.com
sudo systemctl restart cloudflared
# then add an Access application + policy for ai.example.com in Zero Trust

Migrating To A New Host

1. Install Apache, PHP and extensions, MariaDB, Node.js, Docker (for SearXNG), ffmpeg, and python venv tooling.
2. Copy /opt/adi-ai to the same path (rsync or tar), preserving permissions and the private secrets.php and .env files. Keeping the path identical means no config rewrite.
3. Dump the database on the source (mysqldump --databases adi_ai_db), import it on the target, then recreate the app DB user and its grants.
4. Recreate the files MCP Python venv on the target (a venv is not portable); the Node MCP node_modules are pure JS and copy cleanly.
5. Install the systemd units — use the host's live unit files, not any stale copies committed in the repo — then daemon-reload and enable them.
6. Start the SearXNG container so web_search works.
7. Add the Apache vhost (DocumentRoot public + Alias /adi) and verify locally with curl and the health endpoint.
8. Last: route the hostname through Cloudflare and add the Access policy. Do not expose the site publicly until the auth gate is in place.

Operator Reference

MCP Servers

Each tool category is a small server speaking Streamable HTTP on localhost, managed by systemd:

• mariadb — port 3333 — shopping list, web_search, SQL helpers, fetch_url — unit mcp-mariadb.service
• memory — port 3334 — knowledge graph — unit mcp-memory.service
• todo — port 3336 — unified to-do list — unit mcp-todo.service
• notes — port 3337 — notes search and CRUD — unit mcp-notes.service
• media — port 3338 — media library and now-playing — unit mcp-media-library.service
• files — port 9122 — sandboxed file read/write (Python) — unit files-mcp.service

systemctl status mcp-mariadb --no-pager
sudo systemctl restart mcp-notes
journalctl -u mcp-memory -n 50 --no-pager

Web Search (SearXNG)

The web_search tool queries a local SearXNG instance. The reference build runs it in Docker bound to 127.0.0.1:8888. SearXNG ships with the JSON output format disabled — you must enable it in settings.yml or the tool returns nothing. SEARXNG_BASE in config points the app and the mariadb MCP at it.

docker run -d --name searxng --restart unless-stopped \
  -p 127.0.0.1:8888:8080 \
  -v /opt/adi-ai/private/searxng:/etc/searxng \
  searxng/searxng:latest

Voice Services

The voice path is made of separate services, each configured under Settings → Endpoints (they can run locally or on another host):

• TTS (OMNIVOICE_BASE) — generates spoken replies.
• Parakeet STT (PARAKEET_TRANSCRIBE_URL) — transcribes speech to text.
• Wake word (WAKEWORD_WS_URL) — detects “Hey ADI” over a websocket.
• Realtime bridge — Qwen-Omni via DashScope, powering /adi/realtime/.

Their reachability is reflected in the HUD service icons and the health endpoint.

Database Schema

MariaDB database (default adi_ai_db). Schema files in /opt/adi-ai/schema/ are applied in order:

• 01_core.sql — conversations, messages, settings
• 02_shopping.sql — shopping items
• 03_todo.sql — todos and categories
• 04_users.sql — users
• 05_notes.sql — notes and notebooks
• 06_scribe.sql — scribe sessions

Configuration

lib/config.php holds non-secret constants; secrets live in a git-ignored private/secrets.php that config requires, so credentials never sit in the main config or version control. Notable constants:

• Service bases: OLLAMA_BASE, OMNIVOICE_BASE, PARAKEET_TRANSCRIBE_URL, WAKEWORD_WS_URL, SEARXNG_BASE, MCP_SERVERS
• App: APP_BASE (default /adi), UPLOAD_DIR, FILES_SANDBOX_DIR
• Models: LOCAL_MODEL, CLOUD_MODEL, TOOL_CAPABLE_MODELS, VISION_CAPABLE_MODELS, LIVE_OPTIMIZED_MODELS
• Optional image generation: COMFY_BASE and the FLUX_* settings

Health Endpoint

/adi/api/health.php returns JSON with the status and latency of Ollama, the wake word service, Parakeet, and the MCP layer (including live tool count and categories), plus which Ollama models are currently loaded. It is the fastest way to confirm the whole stack and is exactly what the HUD service icons reflect.

curl -s http://127.0.0.1/adi/api/health.php | jq

Security Notes

• Keep API keys and passwords in environment files or private config files outside public/.
• Use least-privilege MariaDB users for app features and feedback forms.
• Do not expose local-only MCP ports directly to the public internet.
• Use HTTPS for public pages and authenticated dashboards.
• Prefer read-only or narrowly scoped MCP tools when shipping a public distro.
• For GitHub, include setup scripts and examples, not live secrets.
• ADI has no built-in login — put it behind an authenticating proxy such as Cloudflare Access / Zero Trust before exposing it. See Deployment And Access.
• Bind MCP servers, SearXNG, and model services to 127.0.0.1 so they are reachable only from the host, never the public internet.

Data Handling And Privacy

• Conversations, settings, notes, to-dos, and graph memory are stored in your own MariaDB. Nothing leaves the host except the requests you make to providers you configure.
• Cloud provider models receive the prompt and content you send them; local Ollama models keep that data on your own hardware. Choose the model accordingly for sensitive material.
• Uploads and generated files live under public/uploads and public/files — keep them access-controlled and out of any public listing.

Troubleshooting

Chats Do Not Save

Check database credentials, conversation tables, PHP error logs, and whether prepared queries are being used correctly for user-scoped conversation reads.

Backgrounds Do Not Display

Confirm the setting value, asset path, file permissions, video MIME type, and browser cache. Test the direct background URL in the browser.

MCP Icon Is Dark

Check the relevant MCP service status, the app health endpoint, and whether the MCP server is returning tools. For Memory, check mcp-memory and http://127.0.0.1:3334/healthz.

Feedback Is Missing Message Text

Inspect the feedback table columns and submit processor. The form should persist the main message field plus metadata such as type, priority, contact, page, URL, source IP, and user agent.

Provider Key Ignored Or Falling Back To .env

If a provider keeps using the daemon's value instead of the one you saved, confirm the key saved to the database (Settings → API Keys), that it is in the right format for that provider, and that the matching .env variable (for example DASHSCOPE_API_KEY) is not overriding it elsewhere. Reload after saving.

Tools Or MCP Categories Missing

Check the health endpoint's tool_count and the per-server status. A missing category usually means that one MCP service is down — restart its unit (for example mcp-notes.service) and read its journal. The mariadb MCP also needs MariaDB up, and web_search needs the SearXNG container running.

Voice Or Wake Word Not Working

Verify the TTS, Parakeet, and wake-word endpoints in Settings and confirm the host can actually reach them (the health endpoint reports each one). For realtime voice, check that the DashScope key is set and bridge.py is running.

502 / 530 Behind Cloudflare

The tunnel cannot reach the origin. Confirm Apache is serving the vhost on localhost, that the cloudflared ingress hostname and httpHostHeader match, and that cloudflared is active with registered connections. Test the origin directly with a local curl and the right Host: header to isolate Apache from the tunnel.

Ollama Model Will Not Load

Check that OLLAMA_BASE is reachable and the model is pulled on that host. The health endpoint lists loaded models; large models may need more VRAM or a longer first-load timeout. For :cloud models, confirm the Ollama Cloud key.

Web Search Returns Nothing

The SearXNG JSON format is disabled by default. Enable JSON in settings.yml, restart the container, and verify SEARXNG_BASE points at it. Test directly: curl "http://127.0.0.1:8888/search?q=test&format=json" should return JSON, not an error page.