ZimaBrain CE — Local ZimaOS Diagnostic Assistant
Hi everyone,
I wanted to share a community diagnostic tool for ZimaOS called ZimaBrain CE.
This project was built with strong guidance from Holger / Lintux, and I want to give him proper credit for that. His direction around verifier-first thinking, evidence layers, security awareness, firewall checks, SMART interpretation, and safe diagnostic flow shaped a lot of how this tool works.
The purpose of ZimaBrain CE is simple: make ZimaOS troubleshooting more structured, evidence-based, and safer.
Many ZimaOS problems are not one single issue. They usually involve a mix of storage, Docker, app paths, ports, firewall rules, SMART health, mount points, containers, and sometimes assumptions made from incomplete evidence.
ZimaBrain CE was built to slow that process down and help users work from evidence first.
The basic principle is:
Analyze first → Verifier second → Explainer third → Repair guide last
That means ZimaBrain should first look at local evidence from the system, explain what it found, and then suggest the safest next step.
What it does
ZimaBrain CE runs locally on your ZimaOS machine and checks things like:
- System and storage evidence
- SMART / NVMe health
- Docker containers
- App ports and exposed services
- LAN reachability hints
- Firewall / DOCKER-USER / ZFW-style checks
- Local dashboard evidence
- Installed app awareness
- Redacted support report export
It also includes a built-in native dashboard, so you can quickly see detected disks, container state, and local evidence without needing a separate visual dashboard container.
Why we built it
A common issue is that users see something like SMART PASSED and assume the disk is healthy.
But SMART PASSED by itself is not enough.
For example, a disk can show overall SMART passed while still having risky attributes such as:
- Reallocated sectors
- Reported uncorrectable errors
- Pending sectors
- Offline uncorrectable sectors
- CRC errors
- Command timeouts
- NVMe unsafe shutdowns
- NVMe error log entries
ZimaBrain CE checks those detailed values instead of trusting the top-level SMART result alone.
Another common issue is apps not opening. Sometimes the app is running, but the port is not exposed. Sometimes it is bound to localhost. Sometimes Docker published the port but firewall or LAN reachability is still the problem. ZimaBrain tries to separate those cases using local evidence.
Security note
ZimaBrain CE runs in Elevated Local Verifier mode.
That means it needs host visibility and read-only Docker socket access so it can verify ZimaOS disks, containers, ports, firewall state, and system evidence.
Because of that:
- Keep it on your trusted LAN
- Set a password on first run
- Do not expose it publicly
- Use the redacted support report when sharing output
Install through ZimaOS Custom App
Install this through ZimaOS → App Store → Custom App.
Paste the compose file below into Custom App and deploy it.
After install:
- Open the tile
- Set the first-run password
- Access ZimaBrain on port
8601 - Ask a test question such as
Are my disks healthy?
If you already installed an older test build, delete the old app first and reinstall so Docker pulls the latest image.
Current status
This is still a community beta, but it has now been tested on multiple ZimaOS systems.
Recent testing confirmed:
- Custom App install works
- Tile opens on port
8601 - First-run password setup works
- Native dashboard loads
- ZimaBrain logo appears on the tile
- ZimaBrain CE tips popup appears on start
- SMART / disk health answer works
- Dashboard now flags risky SMART attributes correctly
- Redacted support report downloads
- App-specific awareness has improved
Docker image
gelbuilding/zimabrain-ce:1.6.0-beta
Compose
name: zimabrain-ce
services:
zimabrain-ce:
image: gelbuilding/zimabrain-ce:1.6.0-beta
container_name: zimabrain-ce
restart: unless-stopped
privileged: true
pid: host
ports:
- "8601:8601"
volumes:
- /DATA/AppData/zimabrain-ce:/data
- /DATA/AppData/zimabrain-ce/docs:/app/docs:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /etc/hostname:/host/etc/hostname:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
extra_hosts:
- "host.docker.internal:host-gateway"
labels:
icon: https://raw.githubusercontent.com/Jacko88888/zimabrain-ce/main/app/assets/zimabrain-ce-logo.svg
title: ZimaBrain CE
description: Local ZimaOS diagnostic assistant
index: /
scheme: http
port_map: "8601"
Good first questions to try
Are my disks healthy?
Is port 8601 reachable on LAN and is firewall blocking it?
Why is Immich not opening?
Which containers are exited?
Final note
This is a verifier-first tool. It will not always say “confirmed” unless the evidence is strong enough. Sometimes it will say Partially Verified, and that is intentional.
For example, LAN reachability can often be checked from the host side, but it cannot be fully proven from another device unless an external LAN client also tests access.
The aim is to reduce unsafe advice, improve troubleshooting flow, and make support reports easier to understand.
Again, special thanks to Holger / Lintux for his explicit guidance and technical direction on how this should be structured.
