Skip to Content
DocumentationCompanion HubHow Hub runs apps and models

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.

ContainerImageWhat it doesStatus
ci-hubghcr.io/companionintelligence/ci-hubThe API and dashboard on port 5002. It drives Docker for every app and answers AI requests.Works today
ci-hub-dbpostgres:14Hub’s own database: apps, jobs, settings, telemetry samples. Port 6543, bound to loopback on the host.Works today
ci-hub-queuerabbitmq:4-alpineThe work queue that carries installs, updates and timed jobs.Works today
traefiktraefik:v3.6.12Reverse proxy on ports 80 and 443. It routes public and private-network addresses to apps and to the Hub.Works today
cloudflaredcloudflare/cloudflared:2026.10.5Outbound Cloudflare tunnel. Runs only under the cloudflare profile, when Hub is paired with your CI Account.Behind a setting
hub-tailscaletailscale/tailscale:v1.98.3Tailscale 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).

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.

Install, 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.

ActionWhat Hub runsStatus
InstallWrites 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 restartRe-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
UpdateStops 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
Stopcompose down, then rebuilds Traefik routes after 1 s.Works today
UninstallReleases the ports and runs compose down, removing local images. With Delete all data on, it also removes volumes and the data folder.Works today
Resetcompose down with volumes, then wipes the app’s data folder.Works today
Backupcompose 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.

  1. App or editorSends an OpenAI-style requestYour app
  2. Hub inference API/api/inference/v1, or the pool route apps getHub
  3. Pick a modelauto means your Settings model firstHub
  4. Choose a nodeThis Hub, or a less busy paired HubHub
  5. Make roomUnloads idle, unpinned models if memory is shortHub
  6. Engine answersOllama, Lemonade, vLLM or oMLXEngine
  7. Reply streams backA dropped connection cancels the engine callHub
What happens when an app asks the Hub for an answerOn a Hub with no connected peer, the node is always this Hub.

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.

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.

BackendWhere Hub finds itWhat Hub uses it forStatus
OllamaOLLAMA_URL, host.docker.internal:11434 in the Hub stackChat and embeddings. Also embeds for vLLM and oMLX.Works today
LemonadeLEMONADE_URL, host.docker.internal:13305 in the Hub stackChat, embeddings, speech to text and text to speech.Works today
vLLMA URL saved in Settings, VLLM_URL, or port 8000Chat.Works today
oMLXA URL saved in Settings, OMLX_URL, or port 8000 on an Apple Silicon hostChat on Apple Silicon.Works today
LocalAILOCALAI_URL, or port 8080 on the hostSpeech after Lemonade, and image generation, if a LocalAI is already running there.Works today
Cloud providersKeys you add in Settings → AIOpenAI, 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.

Nomic Embed Text: 0.3 GB — embeddings, every tierNomic Embed Text0.3 GB · embeddings, every tierQwen 3.5 4B: 3.4 GB — cpu-onlyQwen 3.5 4B3.4 GB · cpu-onlyQwen 3.5 9B: 6.6 GB — lowQwen 3.5 9B6.6 GB · lowGemma 4 12B: 7.6 GB — lowGemma 4 12B7.6 GB · lowDeepSeek Coder V2 16B: 8.9 GB — mediumDeepSeek Coder V2 16B8.9 GB · mediumGemma 4 E4B: 9.6 GB — cpu-onlyGemma 4 E4B9.6 GB · cpu-onlyGPT-OSS 20B: 14 GB — mediumGPT-OSS 20B14 GB · mediumQwen 3.8 27B: 18 GB — mediumQwen 3.8 27B18 GB · mediumQwen 3.5 122B: 81 GB — highQwen 3.5 122B81 GB · high
Download size of some catalog modelsSizes and lowest tier as listed in Hub's model catalog for Ollama.

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.

TierWith a ready GPU runtimeUnified memory, no GPU runtimeOtherwise
high16 GB of VRAM or more32 GB of RAM or more
medium8 GB of VRAM or more16 GB of RAM or more
low4 GB of VRAM or more8 GB of RAM or more
cpu-only16 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.

ActionWhat Hub doesStatus
PullChecks 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
LoadLoads 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 roomWhen 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
PinNever 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
UnloadTells 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.

Hub00:0006:0012:0018:0024:00Runs a dayApp status sync — Every 5 minutes · 288 runs · HubApp status sync288 runsCloudflare exposure sync — Every 5 minutes · 288 runs · HubCloudflare exposure sy…288 runsStatus report — Every 15 minutes · 96 runs · HubStatus report96 runsPortal check-in — Every 15 minutes · 96 runs · HubPortal check-in96 runsCatalog update — Every 15 minutes (production) · 96 runs, production · HubCatalog update96 runs, productionDisk and memory alerts — Every 15 minutes · 96 runs · HubDisk and memory alerts96 runsOrphan network cleanup — Every 30 minutes · 48 runs · HubOrphan network cleanup48 runsCatalog sync — Every 60 minutes · 24 runs · HubCatalog sync24 runsCache eviction — Every 360 minutes · 4 runs · HubCache eviction4 runsMemory key rotation — Every 720 minutes · 2 runs · HubMemory key rotation2 runs
JobRuns onScheduleRuns a day
App status syncHubEvery 5 minutes288 runs
Cloudflare exposure syncHubEvery 5 minutes288 runs
Status reportHubEvery 15 minutes96 runs
Portal check-inHubEvery 15 minutes96 runs
Catalog updateHubEvery 15 minutes (production)96 runs, production
Disk and memory alertsHubEvery 15 minutes96 runs
Orphan network cleanupHubEvery 30 minutes48 runs
Catalog syncHubEvery 60 minutes24 runs
Cache evictionHubEvery 360 minutes4 runs
Memory key rotationHubEvery 720 minutes2 runs
When Hub's recurring jobs run in a dayCron jobs run on the clock. Timers count from when the Hub started, so their marks show spacing, not exact times.
JobHow oftenWhat it doesStatus
Host telemetryEvery 5 sRecords 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 watchdogEvery 30 sChecks the RabbitMQ connection and reconnects if it is stuck.Works today
Pool peer healthEvery 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 samplingEvery 10 s, only with a connected peerMeasures GPU load for the pool. The pool ignores it unless you raise its weight from the default of 0.Works today
Tailscale readinessEvery 45 sRepublishes private-network apps once Tailscale connects or HTTPS becomes available.Works today
App CPU monitorEvery minuteLogs 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 syncEvery 5 minutes (queue)Compares each app’s recorded status with its containers and reports crashes.Works today
Cloudflare exposure syncEvery 5 minutesRe-syncs public addresses and custom domains with the Portal.Works today
MCP session cleanupEvery 5 minutesCloses MCP sessions idle for more than 30 minutes.Works today
Catalog updateEvery 15 minutes (queue), production onlyPulls every enabled app store.Works today
Status reportEvery 15 minutes (queue)Writes the Hub status file and checks in with the Portal.Works today
Portal check-inEvery 15 minutesConfirms the Hub’s registration with the Portal, skipped if a check-in ran in the last 14.5 minutes.Works today
Disk and memory alertsEvery 15 minutesTells agent apps when disk or memory use is above 90%, at most once an hour.Works today
Orphan network cleanupEvery 30 minutes (queue)Removes Docker networks that no app uses any more.Works today
Catalog syncEvery hourPulls every enabled app store, in every environment.Works today
Cache evictionEvery 6 hours, and once at startDeletes expired cache entries.Works today
Memory key rotation60 s after start, then every 12 hoursRotates the keys apps use to connect to Companion Memory once they are older than 60 days.Works today
Hub auto-updateEvery 24 hours, production onlyChecks 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 rotationAt start, then every 24 hoursMoves the day’s logs into history.Works today
Backup retentionEvery 7 days of uptimeTrims each app’s backups; see Retention.Works today
Inference supervisionOnly when you turn it onReports engine health and restart loops. Off by default, and it never restarts an engine.Behind a setting
Crash-loop auto-detectionNever startedA 60 s scan for crash-looping containers. Only tests start it.Not yet
Training job schedulesNever startedTraining 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.

PartWhat it isWhy it does not run todayStatus
Training runnerStarts 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 checkDefers 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 HubHands 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 placementJob 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.

Last updated on