Docker Issues

Common Docker problems when running Companion Hub, and how to fix them.

Docker not running

# Linux
sudo systemctl start docker
sudo systemctl enable docker
 
# macOS/Windows — start Docker Desktop from the menu bar / system tray

Verify:

docker info
cihub status

Permission denied

If you get permission errors accessing the Docker socket:

sudo usermod -aG docker $USER
# Log out and back in for group membership to apply

On Linux, the Hub container also needs the host docker group GID (DOCKER_GID in your env file).

Disk space full

Docker images, layers, and volumes accumulate over time:

docker system df              # see what's using space
docker system prune           # remove stopped containers, unused networks
docker image prune            # remove dangling images
docker system prune -a        # remove ALL unused images (aggressive)

Hub-specific cleanup:

cihub uninstall --yes    # removes Hub containers/volumes + runtime/config/state dirs

See Docker fundamentals for what uninstall affects.

Container won’t stop

docker kill <container-id>
docker rm -f <container-id>
 
# Or via Hub CLI:
cihub app stop <name>
cihub app delete <name>

Hub stack won’t start

Check for port conflicts:

cihub status
sudo lsof -i :5002    # default Hub API port
sudo lsof -i :80      # Traefik HTTP

The CLI attempts automatic port healing on startup. If conflicts persist, change ports in your .env file.

Bind mount permission errors

Hub runs containers as a mapped host UID/GID. If app data directories are owned by root:

# Check ownership under your data root
ls -la <ROOT_FOLDER_HOST>/apps/
 
# Fix ownership (adjust UID/GID to match your env)
sudo chown -R 1000:1000 <ROOT_FOLDER_HOST>

Ollama not reachable from containers

Symptoms: models fail to load, cihub status shows no models, AI apps can’t connect.

1. Verify Ollama is running: ollama list
2. Bind to all interfaces: OLLAMA_HOST=0.0.0.0:11434 (see AI & Inference)
3. Test from a container: docker run --rm curlimages/curl http://host.docker.internal:11434/api/tags

Remove tunnel token manually

If Cloudflare tunnel state is corrupted after unpairing:

cihub down
rm -f <ROOT_FOLDER_HOST>/tunnel/token
cihub up prod --detached

Then re-pair with Portal. See Device Pairing.

Reset everything (last resort)

cihub down
cihub uninstall --yes
cihub wizard

This is equivalent to a factory reset. All Hub state and app containers are removed. App data volumes may survive depending on Docker prune settings — verify with docker volume ls before purging if you need to preserve data.