ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Linux troubleshooting guide
Structured reference for Linux install and runtime issues. When you run ./scripts/linux-install-preflight.sh or ./ods-preflight.sh --install-env, each line uses a check ID. Use this document to jump from an ID to likely causes and fixes.
Related: INSTALL-TROUBLESHOOTING.md, TROUBLESHOOTING.md, LINUX-PORTABILITY.md, FIELD-INSTALL-REPORT-LINUX.md.
Using the install preflight
From the ods directory:
./scripts/linux-install-preflight.sh
./scripts/linux-install-preflight.sh --json
./scripts/linux-install-preflight.sh --json-file /tmp/preflight.json
./ods-preflight.sh --install-env --json # same as linux-install-preflight.sh
--strict— exit with failure if any check is warn or fail (useful in automation).--ods-root PATH— directory used for the disk-space probe (default: ods root).--min-disk-gb N— minimum free space in GB to treat as OK (default: 15).
JSON output includes schema_version, kind: linux-install-preflight, distro, kernel, checks[], and summary.
Check IDs (alphabetical)
CGROUP_V2
Symptoms: Warning that cgroup v2 was not detected.
Typical causes: Older kernels, unusual container hosts, or mis-mounted /sys/fs/cgroup.
Fixes:
- On normal desktop/server distros from the last several years, cgroup v2 is standard; if Docker works, you can ignore this warning.
- If Docker fails with cgroup-related errors, ensure you are not mixing rootless Docker with a broken delegated cgroup setup. See your distro’s Docker documentation.
COMPOSE_CLI
Symptoms: Fail — neither docker compose nor docker-compose works.
Typical causes: Docker Engine installed without the Compose v2 plugin; very old Docker packages; PATH issues.
Fixes:
- Install Docker Compose v2 (plugin): often package
docker-compose-plugin(Debian/Ubuntu) or equivalent. - Legacy: install standalone
docker-composev1 if you must (less ideal).
Verify:
docker compose version
# or
docker-compose version
COMPOSE_FILES
Symptoms: Warning — docker-compose.base.yml / docker-compose.yml missing under the ods tree.
Typical causes: Running the script from the wrong directory; incomplete checkout.
Fixes:
cdinto the extracted ods directory that contains the compose files from the release or git clone.- Re-download or re-clone the repository if files are missing.
CURL_INSTALLED
Symptoms: Warn — curl not in PATH.
Typical causes: Minimal container or netinst image without curl.
Fixes:
# Debian/Ubuntu
sudo apt update && sudo apt install -y curl
# Fedora
sudo dnf install -y curl
# Arch
sudo pacman -S curl
The installer and many health checks expect curl.
DISK_SPACE
Symptoms: Warn — low free space on --ods-root (or default ods root).
Typical causes: Small root partition; large existing Docker data; wrong path passed to --ods-root.
Fixes:
- Free space or move the ODS data directory to a larger volume (see installer docs for
data/layout). - Point
--ods-rootat the filesystem you intend to use for the install.
DISTRO_INFO
Symptoms: Fail — /etc/os-release missing.
Typical causes: Non-Linux environment; severely broken chroot.
Fixes:
- Run on a supported Linux distribution. For Windows, use the Windows installer + WSL2; for macOS, use the macOS path.
DOCKER_DAEMON
Symptoms: Fail — docker info does not succeed.
Typical causes: Docker service stopped; user lacks permission to the Docker socket; rootless Docker socket not in environment.
Fixes:
# systemd
sudo systemctl start docker
sudo systemctl enable docker
# Permission denied on /var/run/docker.sock
sudo usermod -aG docker "$USER"
# then log out and back in (or newgrp docker)
Confirm:
docker info
docker run --rm hello-world
DOCKER_INSTALLED
Symptoms: Fail — docker command not found.
Typical causes: Docker Engine never installed; PATH not including Docker binaries.
Fixes:
- Install Docker Engine for your distro.
- Ensure
/usr/bin(or whereverdockerlives) is on yourPATH.
Token Spy cannot store usage with rootful Docker
Token Spy runs as container UID 1000. On Linux (including WSL2 with a Linux
Docker daemon), an installation owned by another UID needs privileged access
to prepare data/token-spy. Otherwise the service can report a healthy HTTP
endpoint while logging Database unavailable and rejecting routed telemetry
with HTTP 503.
The installer uses its prepared sudo access for this ownership step and stops if an enabled Token Spy cannot be prepared. For an existing rootful installation, stop the affected service, repair its data ownership, and start it again:
cd ~/ods
./ods-cli stop token-spy
sudo chown -R 1000:1000 data/token-spy
./ods-cli start token-spy
This preserves the database; it cannot recover telemetry rejected before the repair. Reinstalling from a source containing the fix also prepares ownership. For rootless Docker, use the namespace-aware repair below instead.
Rootless Docker bind-mount ownership
Symptoms: An ODS container repeatedly exits with Permission denied while
writing under data/, but the same install works with rootful Docker.
ODS prepares active bind mounts inside Docker's rootless user namespace. It
does not apply host-side numeric chown values that would map to the wrong
container identity. Existing rootless installs can be repaired without a
reinstall:
cd ~/ods
./ods-cli stop
./ods-cli repair rootless-ownership
./ods-cli start
The repair is limited to active ODS services with a documented container UID.
It rejects symlink escapes, verifies the resulting ownership, and refuses to
recursively change a mismatched directory while its container is running.
The first repair may pull the pinned busybox:1.36.1 helper image; offline
repairs require that image to be present already.
This command does not configure low-port forwarding or Tailscale networking. Those are separate rootless Docker concerns.
KERNEL_INFO
Symptoms: Always pass — prints uname -r (informational).
Note: Use this value when comparing against SUPPORT-MATRIX.md or when filing bugs.
JQ_INSTALLED
Symptoms: Warn — jq not installed.
Typical causes: Minimal system; skipped optional packages.
Fixes:
- The ODS installer often installs
jqautomatically when possible. You can install manually:
sudo apt install -y jq # Debian/Ubuntu
sudo dnf install -y jq # Fedora
KERNEL_INFO
Symptoms: Always pass with kernel version (informational).
Note: Very old kernels may be incompatible with modern Docker or NVIDIA drivers; if you hit exotic bugs, compare with SUPPORT-MATRIX.md.
NVIDIA_CONTAINER_RUNTIME
Symptoms: Warn — nvidia-smi works but Docker does not show an NVIDIA runtime.
Typical causes: NVIDIA drivers installed but NVIDIA Container Toolkit not configured for Docker.
Fixes:
- Install and configure
nvidia-container-toolkit, then restart Docker:
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
- Verify:
docker info | grep -i nvidia
If you are intentionally CPU-only, you can ignore this after setting GPU_BACKEND=cpu in your capability/install profile.
Common cross-cutting issues
Firewall blocking local ports
If the dashboard or WebUI is unreachable from another machine, check ufw / firewalld / iptables for the ports in config/ports.json (or your .env overrides).
SELinux / AppArmor
Rare compose failures can be policy-related. Check audit logs; temporarily testing with permissive profiles is diagnostic only — prefer documented volume labels and permissions.
Docker BuildKit / proxy
Corporate proxies may require HTTP_PROXY / HTTPS_PROXY in Docker’s systemd drop-in or ~/.docker/config.json for image pulls.
Dashboard password or Portal result storage is unavailable
On a Linux install owned by a user other than UID 1000, the Dashboard API
can report healthy while password setup returns HTTP 503 or Portal cannot
create data/pixel-chat-results. The shipped API runs as UID/GID 1000 and
needs write/search access to the shared data parent.
Rerun the corrected Linux installer against the existing installation. Phase
06 preserves the parent's owner, assigns the
parent to runtime group 1000, and grants that group read/write/search access.
It also excludes private pixel-chat-results from the generic host-owner
repair and restores that tree to API UID/GID 1000 if an older reinstall
changed it. File contents/modes and unrelated service data are preserved.
It does not add world-write permission. Rootless Docker applies ownership inside the Docker namespace;
do not substitute a host-side numeric chown for that mapping. A denied repair
stops installation before a healthy API can be mistaken for writable storage.
Existing passwords and chat receipts remain in place. Rolling back source does not undo the parent metadata repair. Restoring its previous group/mode can make Dashboard persistence unavailable again.
Getting help
When opening an issue, attach a field install report (see FIELD-INSTALL-REPORT-LINUX.md) and the JSON from:
./scripts/linux-install-preflight.sh --json
Redact secrets, internal hostnames, and paths you do not want to share.