gbrain-aio
Docker app from dub19's Repository
GBrain all-in-one for Unraid: a hosted knowledge base and MCP server for AI agents (Hermes Agent, OpenClaw, Codex).
Requirements
Overview
GBrain all-in-one for Unraid: a hosted knowledge base and MCP server for AI agents (Hermes Agent, OpenClaw, Codex). One container runs GBrain, PostgreSQL 17 + pgvector, Caddy TLS, and the job supervisor. Agents connect over HTTPS — Postgres is never exposed.
Basic/default setup: follow the five first-run steps below and leave optional advanced fields at their defaults. The container includes PostgreSQL and Caddy TLS, and starts the job supervisor.
First run (details are in each field's help text):
- Set Postgres Password and Admin Bootstrap Token.
- Set LAN Bind to your host IP. Leave Public URL empty to derive the LAN HTTPS address, unless you use a custom port, DNS name, reverse proxy, or Tailscale origin.
- Set Brain Path to an empty folder.
- Start, then open https://lan:3132/admin/ and paste the token.
- Trust the generated CA once.
Advanced configuration is optional. The advanced fields support provider and embedding settings, schema selection, maintenance schedules, TLS origin, Git push, and extra runtime configuration.
STORAGE MODEL (v0.60 single-root layout). ALL persistent state lives in the one Appdata Root folder you choose. The container creates three sub-folders inside it: data/postgres (database), gbrain-home (config, runtime.env, OAuth clients), and caddy (TLS cert plus generated CA). Point Appdata Root only at a folder that holds this app. Keep the same folder across updates and reinstalls; the brain follows the folder.
UPGRADING FROM v0.50 OR EARLIER TEMPLATES. Older releases kept the database, GBrain home, and TLS certs in container-internal or separate mounts. v0.60 keeps everything under the Appdata Root sub-folders and adopts existing data on first boot when the old locations still hold content. On the refreshed template this is controlled by the Appdata Mode variable at its default /data/aio. Before you update: back up the Appdata folder, save a copy of your template field values, keep the Appdata folder path unchanged, and expect the first boot to run database migrations.
TROUBLESHOOTING AFTER AN UPDATE. Never delete the old container or its images while debugging; that is where recoverable copies of state live.
- Log loops on "/config/caddy/certs/cert.pem" or "/data/postgres/postgresql.conf: No such file", Caddy and Postgres restart every second: the container did not boot the true published image (a stale local image answered the update). List what the host holds with: docker images -a | grep gbrain. Remove stale local builds, keep the Appdata folder as is, then run the update again from the Applications tab.
- Container healthy but the brain looks EMPTY: the Appdata Mode variable was missing on boot, so state landed in throwaway volumes. Find them with docker volume ls --filter dangling=true and docker volume inspect. Copy the old database volume into the Appdata folder: docker run --rm -v old volume:/src -v Appdata Root:/dst alpine sh -c 'cp -a /src/. /dst/data/postgres'. Repeat for a leftover cert volume into /dst/caddy. Then restart the container.
- First boot refuses with "Refusing to silently re-template" or a vector dimension error: the embedding width changed versus the existing brain. Set Embedding Dimensions to the previous brain width (768 for the default embeddinggemma setup) and restart. Do not delete data unless a fresh start is intended.
Readme
View on GitHubgbrain-aio
Run GBrain as one container — a hosted knowledge base and MCP server for AI agents. No Postgres setup, no reverse proxy, no worker to manage. Install the Unraid template, set a few values, and it's ready on first boot.
What this is for
GBrain is a self-hosted second brain. Point an AI agent harness at it and it becomes your persistent memory and knowledge store. gbrain-aio packages GBrain so you can run it as a hosted GBrain MCP server for agent frameworks like Hermes Agent, OpenClaw, Codex, and any harness that speaks MCP. Agents connect to it over HTTPS and get queryable memory — not a raw database.
The problem it solves
GBrain will not just run. A real deployment needs five things bolted together:
- PostgreSQL + pgvector — all data + vector embeddings live here
- A reverse proxy — the admin UI and MCP endpoint need HTTPS
- A job worker — background maintenance, nightly "dream," weekly doctor
- Embedding + chat models — Ollama for embeddings, plus a chat model
- A build — GBrain has no official Docker image
Wiring those by hand on Unraid is the whole problem. gbrain-aio does it for you.
What you get in this container
GBrain, running with its full default setup — the reason you're here:
- The GBrain HTTP + MCP server on
127.0.0.1:3131, fronted by Caddy TLS on3132 - The job supervisor — runs background work
- Autopilot — self-maintenance every 30 min
- Nightly dream (02:00) and weekly doctor (Monday 06:00)
- Schema + sources pre-wired —
gbrain-everything, your source federated, sync queued
Plus the supporting infrastructure, all in the same container:
- PostgreSQL 17 + pgvector — loopback only, never published
- Caddy TLS — the public face
- Embedding support —
ollama:embeddinggemma@ 768d
Pinned to official garrytan/gbrain releases. Agents connect only through HTTPS — Postgres is never handed to them.
Embeddings & models
A local Ollama is required for embedding — the container indexes every document into vector space and needs ollama:embeddinggemma @ 768d to do it. Only embeddinggemma is supported today.
- Ollama (required) — the container uses
ollama:embeddinggemma@ 768d. PointOLLAMA_BASE_URLat your local Ollama (e.g.http://<lan>:11434). A GPU is strongly recommended — large brains index and query much faster with GPU-backed embeddings. - Chat / expansion models — add an Anthropic, OpenAI, Gemini, DeepSeek, Groq, or Voyage API key, or route through the same Ollama instance. Leave chat model fields empty to keep defaults.
First boot does the setup for you
Start empty, and the container:
- Runs
gbrain initwithollama:embeddinggemma@ 768d - Git-inits the brain if it is not a repo
- Registers and federates your source
- Writes sync paths and enables the
gbrain-everythingschema - Sets model routing for Ollama
- Enqueues a sync once
/healthis up
No docker exec required.
Install (Unraid, ~3 min)
- Install the template
- Set
POSTGRES_PASSWORD(alphanumeric) andGBRAIN_ADMIN_BOOTSTRAP_TOKEN(32+ chars) - Leave default appdata paths, set your LAN HTTPS origin, Apply
- Wait for init
- Open
https://<lan>:3132/admin/, paste the token, trust the generated CA once
Requirements
- Unraid (with Community Applications) or any Docker host
- A LAN IP you control
- Ollama at
http://<lan>:11434for embeddings (GPU recommended)
Not included
- No host PostgreSQL — everything runs inside the container
Persistence
Back up the brain repo, Postgres data, and Caddy certs under /mnt/user/appdata/gbrain-aio/ if you care about the instance.
License
MIT. GBrain under its own upstream license.
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
dub19/gbrain-aioRuntime arguments
- Web UI
https://[IP]:[PORT:3132]- Network
bridge- Shell
sh- Privileged
- false
Template configuration
Published HTTPS port (Caddy).
- Target
- 3132
- Default
- 3132
- Value
- 3132
Single persistent folder. Sub-folders are created automatically: data/postgres (database), gbrain-home (config, OAuth, runtime.env), caddy (TLS certs + CA).
- Target
- /data/aio
- Default
- /mnt/user/appdata/gbrain-aio
- Value
- /mnt/user/appdata/gbrain-aio
Internal state root (advanced). Keep /data/aio: the single Appdata Root mount and its auto-created sub-folders (data/postgres, gbrain-home, caddy) depend on it. An empty or changed value makes the container use throwaway internal volumes that are wiped on every update.
- Target
- AIO_APPDATA
- Default
- /data/aio
- Value
- /data/aio
Host path to the brain markdown repo. Mounted at the fixed target /source/brain; the source id is fixed to 'brain'. Should be an empty folder (or a git repo) that GBrain will initialize.
- Target
- /source/brain
- Default
- /mnt/user/my-brain
- Value
- /mnt/user/my-brain
Optional. Host folder holding exported agent session transcripts for nightly dream synthesis (mounted read-only at /session-logs).
- Target
- /session-logs
- Default
- /mnt/user/Unraid-Drive-Flash/session-logs
- Value
- /mnt/user/Unraid-Drive-Flash/session-logs
Postgres superuser. Keep gbrain.
- Target
- POSTGRES_USER
- Default
- gbrain
- Value
- gbrain
REQUIRED. Alphanumeric only (A-Za-z0-9). Secret. Example: mypass123. Generate: head -c 16 /dev/urandom | base64 | tr -d '+/=' | head -c 16
- Target
- POSTGRES_PASSWORD
Postgres database name. Keep gbrain.
- Target
- POSTGRES_DB
- Default
- gbrain
- Value
- gbrain
Your Unraid host LAN IP (e.g. 192.168.1.50). The container binds HTTPS to this IP. This is local-network only, not a public address.
- Target
- GBRAIN_LAN_BIND
Optional. Empty = derived from LAN Bind (https://LAN Bind:3132). Override only for custom port, DNS-name access, reverse proxy, or a Tailscale origin. Must match how clients actually reach the container.
- Target
- GBRAIN_PUBLIC_URL
First /admin login token. Must be 32+ chars, alphanumeric + _-. Secret. Generate: head -c 32 /dev/urandom | base64 | tr -d '+/=' | head -c 48
- Target
- GBRAIN_ADMIN_BOOTSTRAP_TOKEN
UID for the brain bind mount. Unraid default is 99 (nobody). Keep 99 unless you know otherwise.
- Target
- BRAIN_UID
- Default
- 99
- Value
- 99
GID for the brain bind mount. Unraid default is 100 (users). Keep 100 unless you know otherwise.
- Target
- BRAIN_GID
- Default
- 100
- Value
- 100
OpenAI-compatible endpoint for embeddings + chat. Point at your local Ollama. Example: http://192.168.1.50:11434/v1 (replace with your Ollama host IP). Leave empty to skip local Ollama.
- Target
- OLLAMA_BASE_URL
Chat model name used when OLLAMA_BASE_URL is set. Written as together:this name. Leave the default unless you know another model. Empty Ollama URL means no chat model (keyword/embed-or-skip).
- Target
- CHAT_MODEL
- Default
- deepseek-v4-flash:cloud
- Value
- deepseek-v4-flash:cloud
Optional. After a successful autopilot-cycle, push the mounted brain to this remote. Empty = off. Do not point a test copy at a live canonical remote. The token is not stored in the remote URL.
- Target
- BRAIN_GIT_PUSH_URL
Optional. Masked token for Brain Git Push URL. Empty = unauthenticated push. Never pasted into git remote -v.
- Target
- BRAIN_GIT_PUSH_TOKEN
Optional. Weekly doctor exam always runs. Set a number to also run gbrain doctor --remediate --max-usd N for that run's estimate. Empty = exam only. Not a weekly wallet.
- Target
- DOCTOR_REMEDIATE_MAX_USD
Optional. Empty = off. Set 1/true/yes/on to enable cycle.skillopt.enabled.
- Target
- SKILLOPT_ENABLED
Optional. Empty = off. Set 1/true/yes/on to enable autopilot.nightly_quality_probe.enabled.
- Target
- NIGHTLY_QUALITY_PROBE
Optional. Empty = off. Set 1/true/yes/on to enable autopilot.conversation_parser_probe.enabled.
- Target
- PARSER_PROBE_ENABLED
Optional. Enables OpenRouter models (any provider:model id). Secret.
- Target
- OPENROUTER_API_KEY
Optional. Enables Claude models for chat/think. Secret.
- Target
- ANTHROPIC_API_KEY
Empty or ollama = route chat/expansion through the ollama recipe (raw gbrain, zero-cost). together = legacy provider_base_urls redirect kept for compatibility. Only used when Ollama Base URL is set.
- Target
- CHAT_PROVIDER
Universal escape hatch. Comma-separated key=value pairs for ANY gbrain config key (e.g. models.drift=ollama:deepseek-v4-flash:cloud, dream.triage.threshold=0.6). provider_base_urls is refused. Applied after known defaults; explicit entries win.
- Target
- GBRAIN_EXTRA_CONFIG
Optional. Comma-separated KEY=VALUE pairs passed to the runtime environment. Allowlist-only: GBRAIN_EMBEDDING_MULTIMODAL(_MODEL), GBRAIN_EMBEDDING_IMAGE_OCR(_MODEL), GBRAIN_SEARCH_EXCLUDE, GBRAIN_SOURCE_BOOST, GBRAIN_CHAT_FALLBACK_CHAIN, GBRAIN_BACKUP_CHECK(_DAYS), GBRAIN_AUTOPILOT_LABEL, GBRAIN_TRAJECTORY_REGRESSION_THRESHOLD, GBRAIN_EMBED_CONCURRENCY, GBRAIN_RETRIEVAL_REFLEX_*. Anything else is refused at boot.
- Target
- GBRAIN_EXTRA_ENV
Empty = ollama:embeddinggemma. Any provider:model id supported by gbrain init.
- Target
- EMBEDDING_MODEL
Empty = 768. Must match the embedding model native width (e.g. bge-m3=1024, nomic=768).
- Target
- EMBEDDING_DIMENSIONS
Empty = gbrain-everything. Schema pack id passed to gbrain schema use.
- Target
- SCHEMA_PACK
Empty = 1800 seconds. Seconds between autopilot cycles.
- Target
- AUTOPILOT_INTERVAL
Empty = 02:00 local. HH:MM for the nightly dream cycle.
- Target
- DREAM_AT
Empty = monday. Weekday for the weekly doctor exam (mon|tue|...).
- Target
- DOCTOR_DAY
Empty = 06:00. HH:MM for the weekly doctor run.
- Target
- DOCTOR_AT
Empty = auto when Unraid per-container Tailscale is enabled (origin = MagicDNS name). off = keep LAN origin. Any URL = explicit origin. Public URL override wins over this.
- Target
- TS_PUBLIC_URL
Optional. Comma-separated extra DNS names for the TLS cert SAN (e.g. your MagicDNS name). Empty = only base SAN plus auto-discovered tailnet names.
- Target
- CERT_EXTRA_DNS
Optional. Comma-separated extra IPs for the TLS cert SAN (e.g. 100.x.y.z)
- Target
- CERT_EXTRA_IPS
Optional. Enables OpenAI models for chat/embeddings. Secret.
- Target
- OPENAI_API_KEY
Optional. Enables Google Gemini models. Secret.
- Target
- GEMINI_API_KEY
Optional. Enables DeepSeek models. Secret.
- Target
- DEEPSEEK_API_KEY
Optional. Enables Groq models. Secret.
- Target
- GROQ_API_KEY
Optional. Enables Voyage embeddings/rerank. Secret.
- Target
- VOYAGE_API_KEY