How Hub runs apps and models
Companion Hub is a set of Docker containers that starts, stops and wires up other Docker containers. Every app you install becomes its own Docker Compose project, and every AI request from those apps goes through one API on the Hub that decides which engine, model or paired Hub answers it.
This page is for owners who want to know what is happening on the box. Setup steps live elsewhere: engines and models in AI and inference, pairing in Hub Pool, and Docker basics in Docker and Companion Hub.
Each part on this page carries one of the four status labels the Companion Memory pages use, as defined on Personas:
- Works today: the capability is on by default.
- Behind a setting: the capability is in the code, but it is off until an owner or operator turns it on.
- Not yet: the capability is not built, or it is built but not connected to the product.
- Planned: the design is documented, and the code does not exist yet.
This page describes Companion Hub’s dev branch as of 12 November 2026. The
latest Hub release, v0.3.11 from 10 November, has none of the training code
below, and its Resources page is the older single-screen page, not the
tabbed one.
The containers Hub runs
The Hub is a Compose project of its own. Two of its containers only start when you turn the matching feature on.
| Container | Image | What it does | Status |
|---|---|---|---|
ci-hub | ghcr.io/companionintelligence/ci-hub | The API and dashboard on port 5002. It drives Docker for every app and answers AI requests. | Works today |
ci-hub-db | postgres:14 | Hub’s own database: apps, jobs, settings, telemetry samples. Port 6543, bound to loopback on the host. | Works today |
ci-hub-queue | rabbitmq:4-alpine | The work queue that carries installs, updates and timed jobs. | Works today |
traefik | traefik:v3.6.12 | Reverse proxy on ports 80 and 443. It routes public and private-network addresses to apps and to the Hub. | Works today |
cloudflared | cloudflare/cloudflared:2026.10.5 | Outbound Cloudflare tunnel. Runs only under the cloudflare profile, when Hub is paired with your CI Account. | Behind a setting |
hub-tailscale | tailscale/tailscale:v1.98.3 | Tailscale sidecar. Runs only under the private-vpn profile. Tailscale Serve sends tailnet requests straight to the Hub and to each app’s container. | Behind a setting |
ci-hub waits until Postgres and RabbitMQ both report healthy before it starts. It does not run privileged. It reaches Docker through the Docker socket mounted into its container, and runs docker compose and the Docker API from there. AI engines that run on the host, such as Ollama, are reached at host.docker.internal (Ollama on 11434, vLLM on 8000, Lemonade on 13305). Each Hub container keeps at most 50 MB of logs (five 10 MB files).
flowchart TB
accTitle: The containers Hub runs and how traffic and control move between them
lan(("You, on the LAN")) e1@--> hub["ci-hub<br/>API and dashboard :5002"]
lan -->|"app addresses"| traefik["traefik<br/>:80 :443"]
tail(("You, on a tailnet")) --> ts["hub-tailscale<br/>(optional)"]
ts --> hub
ts --> apps
web(("Internet visitor")) --> cfd["cloudflared<br/>(optional)"]
cfd --> traefik
traefik -.->|"asks Hub: signed in?"| hub
traefik e2@--> apps["Your apps<br/>one Compose project each"]
hub --> db[("ci-hub-db<br/>Postgres")]
hub --> mq[["ci-hub-queue<br/>RabbitMQ"]]
hub -->|"docker compose<br/>through the Docker socket"| docker[("Docker Engine")]
docker --> apps
apps -->|"AI requests<br/>/api/inference"| hub
hub --> engines["AI engines on the host<br/>Ollama, vLLM, Lemonade"]
e1@{ animate: true }
e2@{ animate: true }Networks
Hub uses four Docker networks. ci-hub_network is the shared app network: the Hub, Traefik, the Tailscale sidecar and each app’s main service join it, so apps can reach the Hub by the name ci-hub. ci-hub_internal holds Postgres and RabbitMQ, and apps never join it. ci-hub_edge is a small network with fixed addresses for Traefik, cloudflared and the Tailscale sidecar, and Traefik trusts forwarded client addresses only from those two senders. ci-os-hub_network is kept as an alias for older stacks.
Each app also gets its own network with its own /24 subnet, taken from a range Hub keeps for apps. Host ports for apps come from 10000 to 60000. Hub never hands out ports below 1024 or the ports its own containers use.
An app’s life
When you click Install, Update or Stop, the dashboard does not run Docker itself. It puts a signed message on RabbitMQ’s app-events-queue, and one of three workers picks it up and runs the command for that verb. Hub saves the job’s state in Postgres, so a job in progress is still known after a restart. Progress reaches the dashboard as server-sent events.
sequenceDiagram
accTitle: What happens when you install an app
actor You
participant UI as Dashboard
participant Q as RabbitMQ
participant Hub as Install command
participant D as Docker
participant T as Traefik
You->>UI: Install, with form values
UI->>Q: Signed install message
Q->>Hub: One of 3 workers takes it
Hub->>Hub: Copy the app from its store (15%)
Hub->>Hub: Write app.env, with AI variables if the app asks (25%)
Hub->>Hub: Reserve host ports (27%)
Hub->>D: Render docker-compose.yml, compose down, then pull images (55% onward)
Hub->>D: compose up --force-recreate (99%)
D-->>Hub: Containers running
Hub->>Hub: Wait until each container runs 5 s without crashing
Hub->>T: Rebuild routes if the app is exposed
Hub-->>UI: RunningInstall, start, restart and update all write a fresh docker-compose.yml from the app’s manifest before they run it. That step adds Hub’s own labels last, so an app cannot override them. It also gives every service restart: unless-stopped unless the manifest says otherwise, adds Traefik labels to the main service only when the app is exposed beyond this machine, and applies your default CPU limit for apps if you set one. The Dynamic compose reference covers the manifest fields.
| Action | What Hub runs | Status |
|---|---|---|
| Install | Writes app.env, reserves ports, renders compose, pulls images, runs compose up (up to 3 tries), then waits for the containers to stay up. | Works today |
| Start and restart | Re-renders compose and app.env, runs compose up. If the app does not stay up within 120 s, Hub takes it down again. | Works today |
| Update | Stops the app, backs it up, pulls the new images and starts them. If the new version fails its health probe, Hub restores the backup and the previous version. | Works today |
| Stop | compose down, then rebuilds Traefik routes after 1 s. | Works today |
| Uninstall | Releases the ports and runs compose down, removing local images. With Delete all data on, it also removes volumes and the data folder. | Works today |
| Reset | compose down with volumes, then wipes the app’s data folder. | Works today |
| Backup | compose stop, then writes app data, user config and named volumes to one .tar.gz under the backups folder. | Works today |
A container counts as up once it has run 5 s without crashing, or 10 s if Hub saw it crash. A container that crashes gets 30 s to settle. After compose up, Hub joins its own container to the app’s networks so the app can resolve ci-hub, and leaves them again before compose down.
What Hub writes into app.env
Every app gets values that tell it who and where it is: APP_ID, APP_PORT, APP_DATA_DIR, APP_URL, APP_PUBLIC_URL and similar. It also gets HUB_INFERENCE_URL, which points at http://ci-hub:5002/api/inference/v1 on an appliance, whether or not the app uses AI.
Apps that declare hub_integration.inference in their manifest also get the AI variables: base URL, key, chat, embedding, vision and utility models, and a context size, each under the variable name the app chooses. Standardized inference variables for apps lists them, and Resolution order explains how Hub picks each value.
When you save a change in Settings → AI that affects what apps are handed, such as the backend, a model, the context limit or Hub Pool, Hub waits 1.5 s for more changes and then restarts the AI apps so they read the new values. A change in which pool peers are connected must hold for 2 health checks first, and Hub will not restart the same app automatically again for 10 minutes. After a Hub update, AI apps are restarted once, 20 s after boot.
How an AI request is routed
Apps, editors and SDKs all talk to the same OpenAI-compatible API on the Hub. The Hub picks a model, makes room for it if needed, and sends the request to an engine on this machine or on a paired Hub.
- App or editorSends an OpenAI-style requestYour app
- Hub inference API/api/inference/v1, or the pool route apps getHub
- Pick a modelauto means your Settings model firstHub
- Choose a nodeThis Hub, or a less busy paired HubHub
- Make roomUnloads idle, unpinned models if memory is shortHub
- Engine answersOllama, Lemonade, vLLM or oMLXEngine
- Reply streams backA dropped connection cancels the engine callHub
Hub has two routes for this. /api/inference/v1 is the address you give an editor or SDK. Its chat, completion and embedding requests go to the pool as soon as at least one peer is connected; its model list, speech, transcription and image requests always stay on this Hub. /api/inference/pool/v1 is the address apps are handed by default, even on a single Hub. It also answers Ollama’s own API (/api/chat, /api/generate, /api/tags and others) for apps that speak Ollama.
flowchart TD
accTitle: Where a chat request goes
req["Chat request"] --> peer{"A pool peer<br/>connected?"}
peer -->|"no"| local["This Hub's router"]
peer -->|"yes"| pool["Pool proxy:<br/>rank this Hub and peers<br/>by queue length"]
local --> has{"An engine here<br/>has the model?"}
has -->|"yes"| eng["Engine on this Hub"]
has -->|"no"| cloud["Cloud provider<br/>if you set one up"]
pool e1@--> eng
pool e2@--> peerEng["Engine on the peer"]
e1@{ animate: true }
e2@{ animate: true }When a request asks for auto on a Hub with no peer, Hub uses the model you chose in Settings → AI if an engine has it loaded, then a pinned model, then any loaded model, then the first chat model a healthy engine lists. With nothing local, it falls back to the first cloud provider you enabled. A request routed through the pool never goes to a cloud provider: if no node can serve it, it fails. Hub Pool explains how the pool ranks nodes and fails over.
| Backend | Where Hub finds it | What Hub uses it for | Status |
|---|---|---|---|
| Ollama | OLLAMA_URL, host.docker.internal:11434 in the Hub stack | Chat and embeddings. Also embeds for vLLM and oMLX. | Works today |
| Lemonade | LEMONADE_URL, host.docker.internal:13305 in the Hub stack | Chat, embeddings, speech to text and text to speech. | Works today |
| vLLM | A URL saved in Settings, VLLM_URL, or port 8000 | Chat. | Works today |
| oMLX | A URL saved in Settings, OMLX_URL, or port 8000 on an Apple Silicon host | Chat on Apple Silicon. | Works today |
| LocalAI | LOCALAI_URL, or port 8080 on the host | Speech after Lemonade, and image generation, if a LocalAI is already running there. | Works today |
| Cloud providers | Keys you add in Settings → AI | OpenAI, Anthropic, Google and GitHub Copilot, as a fallback on the local route. | Behind a setting |
A streamed answer is sent to the caller as it arrives. If the caller hangs up, Hub cancels the call to the engine or cloud provider. Requests from outside the appliance need an inference key; Use your Hub from an editor or SDK shows which address and key to use.
Models
The catalog
Hub ships a curated catalog of 231 models: 109 for Ollama, 41 for Lemonade, 8 for vLLM, 64 for oMLX, and 9 others (6 embedding models, 2 Whisper speech-to-text models and the Kokoro text-to-speech model). Each chat model row records its size, the smallest hardware tier it suits, its context length, and whether it handles images and tool calls. The catalog lists local models only.
Hub sorts your machine into a tier and marks each catalog model as recommended on its own tier and available on higher ones. Lower tiers mark it not recommended, except that low-tier models stay available on CPU-only machines.
| Tier | With a ready GPU runtime | Unified memory, no GPU runtime | Otherwise |
|---|---|---|---|
high | 16 GB of VRAM or more | 32 GB of RAM or more | |
medium | 8 GB of VRAM or more | 16 GB of RAM or more | |
low | 4 GB of VRAM or more | 8 GB of RAM or more | |
cpu-only | 16 GB of RAM or more |
A machine with less than that is rated insufficient.
Memory budget, loading and unloading
Models may use 90% of VRAM on a discrete GPU, or 70% of RAM on unified memory or on CPU only. On top of that, Hub always keeps 2048 MB of system RAM and 512 MB of display VRAM free, and counts 500 MB for each running container. Every load is checked against that budget first.
| Action | What Hub does | Status |
|---|---|---|
| Pull | Checks free disk and the budget before it downloads, and refuses a model larger than the whole budget. Pulls wait in a queue, and only one Ollama pull runs at a time. | Works today |
| Load | Loads one model at a time and tells Ollama to keep it loaded until told otherwise. The context window starts at 65,536 tokens and steps down to a floor of 4,096 until the model fits. | Works today |
| Make room | When an app’s request needs memory, unloads idle, unpinned models that Hub loaded itself, least recently used first, and waits up to 10 s for the memory to free. A load you start yourself may also unload other idle, unpinned models, largest first. | Works today |
| Pin | Never unloads a pinned model to make room. Pins are saved under Hub’s state folder and come back after a restart. Unpinning sets the model back to a 5-minute keep-alive, or to the Ollama keep-alive you gave Hub for this node. | Works today |
| Unload | Tells Ollama to drop the model at once. | Works today |
In a pool, a pin set in Hub Pool only moves a node to the front of the nodes that can already serve the model. Memory, pins, and unloading shows where these controls are in the dashboard.
If an engine keeps failing for one model, Hub stops sending that model to it for 60 s, and longer after repeated failures, up to 15 minutes. Nothing about model management runs on a timer: pulls, loads, unloads and pins happen when you, an app or an MCP tool asks for them.
Background jobs
Hub runs two kinds of timed work. Jobs that touch apps or the store catalog are published to RabbitMQ on a cron schedule and run by the queue workers; if RabbitMQ is not ready at a tick, that tick is skipped. Everything else is a plain timer inside the ci-hub process. Each queue holds at most 10,000 waiting messages.
| Job | Runs on | Schedule | Runs a day |
|---|---|---|---|
| App status sync | Hub | Every 5 minutes | 288 runs |
| Cloudflare exposure sync | Hub | Every 5 minutes | 288 runs |
| Status report | Hub | Every 15 minutes | 96 runs |
| Portal check-in | Hub | Every 15 minutes | 96 runs |
| Catalog update | Hub | Every 15 minutes (production) | 96 runs, production |
| Disk and memory alerts | Hub | Every 15 minutes | 96 runs |
| Orphan network cleanup | Hub | Every 30 minutes | 48 runs |
| Catalog sync | Hub | Every 60 minutes | 24 runs |
| Cache eviction | Hub | Every 360 minutes | 4 runs |
| Memory key rotation | Hub | Every 720 minutes | 2 runs |
| Job | How often | What it does | Status |
|---|---|---|---|
| Host telemetry | Every 5 s | Records CPU, memory, disk and Docker state. The CPU history chart on the Resources page reads it, over 30 minutes to 48 hours. Keeps 48 hours. | Works today |
| Queue watchdog | Every 30 s | Checks the RabbitMQ connection and reconnects if it is stuck. | Works today |
| Pool peer health | Every 30 s by default (10 to 300 s) | Checks each paired Hub. A peer is marked unreachable after 3 failures in a row. | Works today |
| GPU load sampling | Every 10 s, only with a connected peer | Measures GPU load for the pool. The pool ignores it unless you raise its weight from the default of 0. | Works today |
| Tailscale readiness | Every 45 s | Republishes private-network apps once Tailscale connects or HTTPS becomes available. | Works today |
| App CPU monitor | Every minute | Logs the busiest apps and flags an app at 90% CPU or more for 2 minutes. It never throttles or stops an app. | Works today |
| App status sync | Every 5 minutes (queue) | Compares each app’s recorded status with its containers and reports crashes. | Works today |
| Cloudflare exposure sync | Every 5 minutes | Re-syncs public addresses and custom domains with the Portal. | Works today |
| MCP session cleanup | Every 5 minutes | Closes MCP sessions idle for more than 30 minutes. | Works today |
| Catalog update | Every 15 minutes (queue), production only | Pulls every enabled app store. | Works today |
| Status report | Every 15 minutes (queue) | Writes the Hub status file and checks in with the Portal. | Works today |
| Portal check-in | Every 15 minutes | Confirms the Hub’s registration with the Portal, skipped if a check-in ran in the last 14.5 minutes. | Works today |
| Disk and memory alerts | Every 15 minutes | Tells agent apps when disk or memory use is above 90%, at most once an hour. | Works today |
| Orphan network cleanup | Every 30 minutes (queue) | Removes Docker networks that no app uses any more. | Works today |
| Catalog sync | Every hour | Pulls every enabled app store, in every environment. | Works today |
| Cache eviction | Every 6 hours, and once at start | Deletes expired cache entries. | Works today |
| Memory key rotation | 60 s after start, then every 12 hours | Rotates the keys apps use to connect to Companion Memory once they are older than 60 days. | Works today |
| Hub auto-update | Every 24 hours, production only | Checks for a newer Hub image and installs it when auto-update is on (the default). The first check comes 24 hours after start. | Works today |
| Log rotation | At start, then every 24 hours | Moves the day’s logs into history. | Works today |
| Backup retention | Every 7 days of uptime | Trims each app’s backups; see Retention. | Works today |
| Inference supervision | Only when you turn it on | Reports engine health and restart loops. Off by default, and it never restarts an engine. | Behind a setting |
| Crash-loop auto-detection | Never started | A 60 s scan for crash-looping containers. Only tests start it. | Not yet |
| Training job schedules | Never started | Training manifests can carry a cron trigger, but nothing reads it. | Not yet |
Some work happens once per start instead. When the Hub boots it waits for Postgres and runs migrations, clears Docker networks no app uses, pulls the app catalog in the background, and registers the queue jobs above. A few seconds later it re-syncs Cloudflare exposure (after 5 s), rebuilds Traefik routes (after 10 s) and, after a Hub update, restarts AI apps (after 20 s). After a Hub update it also restarts the running apps whose Compose definition changed. On other boots it starts running apps that have no containers.
Per-app backups have no schedule. They happen when you click Backup, when an app is updated, or when you back up all apps at once. See Backup and restore.
Training jobs
Not yet: training on Hub. The code merged on 2026-11-11 but is not ready to use, and nothing in Hub or Companion Memory starts a training job on Hub today.
The merge added two pieces to Hub. The first is a training runner with a resource check that puts a job off while the machine is on battery and asks Ollama to free memory when GPU memory looks short, then starts the job anyway. It can also send a job to a paired Hub. Since Companion Hub #2452 merged on 2026-11-12, peers accept training requests from paired Hubs, but no Hub can run the trainer yet. The second is a set of building blocks for a later version: a job manifest format with an optional cron trigger and an evaluation gate, a job state machine, and placement rules that pick a node for a job.
Companion Hub #2453 merged the same day. A peer can now read the status of only the jobs it sent, it accepts dataset and checkpoint paths only inside its own training data folder, and when a peer refuses a job you get a 409 or a 502 that names the peer and its reason. It does not make training runnable.
| Part | What it is | Why it does not run today | Status |
|---|---|---|---|
| Training runner | Starts a Python training process and reads its progress. | The Hub image has no Python or training code, and nothing in the product submits a job. Jobs are kept in memory only, so a restart loses them. | Not yet |
| Resource check | Defers on battery; when GPU memory looks short it asks Ollama to free memory and starts the job anyway. | Several of its checks only work on macOS or with NVIDIA tools, which the Hub container lacks, and it calls Ollama at an address the Hub container cannot reach. | Not yet |
| Send to a paired Hub | Hands a job to the connected, enabled paired Hub with the most free GPU memory, when the job allows offload and the local check fails. | The receiving Hub accepts only data already in its own training data folder, nothing copies datasets between Hubs, and the receiving Hub cannot run the trainer either. | Not yet |
| Manifests and placement | Job format, state machine, node ranking, evaluation gate. | No other Hub code imports it, and nothing reads its cron triggers. | Not yet |
The personal models Companion Memory trains today run inside Memory itself, on Memory’s own schedule. How Companion learns explains what they learn and when, and AI training, inference and jobs has the technical detail. Sending bigger training jobs to another device you own is listed as Not yet on Personal AI on your own hardware.