ZimaBrain CE — Local ZimaOS Diagnostic Assistant

Insight & Feedback
21

I tested the new Flask installation method today, and I have to say I personally prefer the previous Docker image version.

The new installation feels much more complicated than before. Instead of simply deploying a Docker image, it now requires cloning the Git repository, building the image locally, and managing updates manually with git pull and docker compose build.

For most ZimaOS users, I think the previous approach was much easier:

  • Pull the Docker image.

  • Deploy the container.

  • Done.

After installing the Flask version, I also noticed that ZimaOS now shows a grey placeholder tile named zimabrain-ce-flask-8601 on the dashboard. It doesn’t behave like a normal application and, in my case, clicking it doesn’t do anything useful. It doesn’t integrate well with the rest of the ZimaOS interface.

Personally, I don’t like this new installation experience, so I’m going back to the previous Docker image version.

I think it would be great if the project could continue to provide an official pre-built Docker image alongside the development/Git version. That would make installation and updates much easier for normal users while still allowing developers to use the source-based workflow.

22

Thank you for testing and for the honest feedback.

I agree with you. The Git / Flask install is more of a development and testing workflow. It is useful for fast changes, but it is not the best experience for normal ZimaOS users.

The easier path should still be:

Pull image
Deploy container
Open app
Done

The grey zimabrain-ce-flask-8601 tile is also expected with this current development method, but I agree it does not feel like a proper ZimaOS app tile. It is not as clean as the previous Docker image install experience.

My suggestion is that we keep both options:

1. Pre-built Docker image for normal users
2. Git / local build version for testers and developers

That way users who just want to test ZimaBrain can install it easily, while developers can still pull the latest source and rebuild locally.

Your feedback is helpful, because if ZimaBrain is going to help normal ZimaOS users, installation has to stay simple.

23

Thanks for understanding.

I think keeping both options is the right approach.

For me, the pre-built Docker image is the version I would recommend to most ZimaOS users. It is much closer to the ZimaOS philosophy: install, open, and use.

The Git/Flask workflow makes perfect sense for developers and testers, but it is not something I would expect a normal user to maintain.

The other thing that stood out to me is the user experience. The grey zimabrain-ce-flask-8601 tile looks like an unfinished development artifact. It doesn’t integrate with the rest of the ZimaOS interface and makes the dashboard feel cluttered.

If the Git version is mainly intended for development, perhaps it should be documented as a developer installation rather than the default recommendation. I think the official Docker image should remain the primary installation method for most users.

24

One small suggestion regarding versioning.

I find the naming a little confusing.

The application shows v1.6.0-beta, but the container and project are called zimabrain-ce-flask-8601, where 8601 is actually just the port number.

As a user, I would expect versions to simply be:

  • v1.6.0-beta1

  • v1.6.0-beta2

  • v1.6.0-beta3

That makes it immediately obvious which version I am running. The port number does not need to be part of the application or project name.

25

Yes, I agree with this as well.

The 8601 part is only the port number, so I understand why it looks confusing when it appears in the container/project name. It can make users think it is part of the version, when it is not.

I believe the app version should stay simple and visible inside ZimaBrain, for example:

v1.6.0-beta1
v1.6.0-beta2
v1.6.0-beta3

And the container/app name should probably be cleaner, something like:

zimabrain-ce

Instead of:

zimabrain-ce-flask-8601

The port can stay in the compose file, but it does not really need to be part of the user-facing name.

Good suggestion. This would make it much easier for users to know which build they are running, and it would also make support easier when people post screenshots or reports.

26

Please remember this is still beta, so some of these rough edges are expected while we test the workflow. The good thing is that this feedback helps us improve it properly.

The latest fixes are already pushed, especially around the verifier and dashboard evidence routing.

Could you please update and test these questions again:

what needs attention
what are the real alerts, container alerts, and info alerts?
what is the 1 Real Alert?
what are the 5 Info Only items?

The main things to check are:

Does it now explain the alerts instead of only showing counts?
Does “what needs attention” show VERIFIED FROM SAME-REPORT EVIDENCE when real findings exist?
Does it separate real alerts, container/service alerts, and info-only items more clearly?

Thanks again for testing. This is exactly how beta gets better.

27

Thanks. I appreciate all the work you’re putting into this, and I know it’s still beta.

At the moment, though, I’ve switched back to the previous Docker image version because I prefer the simpler installation and the better integration with ZimaOS.

The Git/Flask workflow is understandable for development, but for my day-to-day use and testing I prefer the Docker version.

Once the same verifier improvements are available in the Docker image, I’ll be happy to test them again. For me, the Docker image is the version that represents the experience most normal ZimaOS users will have.

I’ll continue reporting bugs and suggestions from that version.

1 Like
28

That is completely fair, and I actually agree with your reasoning.

The Docker image version is the better user experience for normal ZimaOS users. The Git / Flask workflow is mainly useful for fast testing and development, but it is not the install method I want regular users to struggle with long term.

So yes, please stay on the Docker image version for now if that works better for you.

The next goal is to bring the same verifier improvements into the Docker image version as well, so users can get:

simple install
normal ZimaOS app experience
same improved alert/verifier logic

Your point is important because the Docker image is probably the closest to how most ZimaOS users will actually install and test ZimaBrain.

Please keep reporting from that version. That feedback is still very useful, and it helps make sure we do not only improve the developer workflow, but also the normal user experience.

Thanks again for testing and for the honest feedback. This is exactly what beta testing is for.

1 Like
29

I also created a cleaner ZimaBrain icon in the ZimaOS style. Feel free to use it if you like it. If not, that’s completely fine—I just wanted to contribute something to the project.

zima_brain2_e3ai6zi8va
zima_brain2_e3ai6zi8va1254×1254 261 KB

2 Likes
30

Thank you again, the icon looks good.

Would you be able to share the actual icon file as well?

Ideally:

SVG preferred
or transparent PNG, minimum 512x512

The screenshot is good for previewing it, but for the app tile / Docker image / GitHub package it is better to use the original file so it stays sharp and does not include the forum preview background.

If you can upload the SVG or PNG, I can look at including it in the next version cleanup.

32

One question:

What is the best way to upload the icon files here on the forum?

I only have the PNG versions left (1024×1024 with a transparent background), but I don’t see an obvious way to attach them. Should I upload them directly in this thread, or would you prefer that I share them another way?

33

I apologize in advance for interrupting your discussion. The day before yesterday, I updated ZimaOS to version 1.6.2, and a couple of containers failed to start, while Immich completely stopped working. I checked all the paths, and everything was fine. I remembered zimaBrain, installed Git/Flask, and was looking at it like a ram at a new gate. Of course, I couldn’t study the program in an hour; as I understand it, it should work and collect error data. I started reading and saw that installing a Docker image was a little easier to use. I tried to find the cause or error starting Immich, but zimaBrain didn’t show anything. Perhaps I asked the wrong questions, or asked them in the wrong way. Result: I formatted everything and installed 1.6.2. But it looks like I’ll have to roll back to version 1.5.4 tomorrow.

34

Thank you for the feedback, and sorry ZimaBrain did not help you quickly enough in that situation.

Your post shows exactly where we still need to improve the normal user experience. The Git / Flask install is useful for testing fast changes, but I agree it is not the easiest path when someone is already dealing with broken containers or Immich not starting.

For cases like Immich after a ZimaOS update, the best questions to ask ZimaBrain should be things like:

What needs attention?
Which containers are exited?
Why is Immich not starting?
Check Immich container paths and mounts
Are there failed services?
What changed after the ZimaOS update?
Are there Files / AppData / media path problems?

We have now added more verifier improvements for service state, disk activity, failed services, Files/AppData/media checks, and safer disk summaries, but the next important step is to bring these improvements back into the normal Docker image/custom app version.

That should make it easier for normal ZimaOS users:

install app
open tile
ask guided questions
export report
share here

Thank you for posting this. It helps us see that ZimaBrain needs not only better diagnostics, but also a simpler install and clearer “what should I ask?” flow.

35

It would be great if there was a drop-down list of valid commands (I think this is relevant for the average user). If the question you need isn’t there, type it in manually. I only asked a few questions:
Which containers aren’t working?
Why isn’t Immich starting?
Check the Immich container issue.
And by the way, I think I asked the questions without a question mark! I can’t remember exactly.

36

That is a very good suggestion, and I agree.

For normal users, a drop-down list of suggested questions would make ZimaBrain much easier to use. Not everyone will know what to ask when something is broken, especially after an update or when an app like Immich stops working.

Something like this would help:

What needs attention?
Which containers are not running?
Why is Immich not starting?
Check Immich container paths and mounts
Are there any failed services?
What changed after the ZimaOS update?
Are there any Files / AppData / media path problems?
What service is using disk?
What is using CPU?
Export this session for the forum

Then if the user needs something else, they can still type their own question manually.

Also, the question mark should not matter. ZimaBrain should understand both:

Why is Immich not starting?
Why is Immich not starting

If that was not working properly, then that is something we need to improve in the question routing.

Your feedback is very helpful because it shows ZimaBrain needs two things:

better diagnostics
better guidance on what to ask

I will add the suggested-question/drop-down idea to the improvement list for the next version.

37

Hi everyone,

Small ZimaBrain CE beta update.

Thanks again to everyone testing and giving feedback. The latest fixes are now available in the Docker / Custom App version, so normal users do not need to use the Git / local build method.

This update includes the recent verifier improvements:

- Better “what needs attention?” routing
- Better failed-service detection
- Active service inspection
- zimaos-welcome service status checks
- systemd-networkd-wait-online checks
- CPU activity checks
- pidstat / disk I/O evidence
- iostat fallback evidence
- Better answers for “what service is using disk?”
- Better answers for “what is using CPU?”
- Safer disk CRC summaries
- Removed hard-coded sda / sdd wording from disk summaries
- Cleaner Custom App name: ZimaBrain CE
- Cleaner container name: zimabrain-ce
- App icon now loads automatically during install

The Docker image has been updated here:

gelbuilding/zimabrain-ce:1.6.0-beta

If you already installed the previous test/custom version, remove the old container first:

docker rm -f zimabrain-ce-flask-8601 zimabrain-ce 2>/dev/null || true

Then install ZimaBrain CE again as a Custom App using this compose file:

name: zimabrain-ce

services:
  zimabrain-ce:
    image: gelbuilding/zimabrain-ce:1.6.0-beta
    container_name: zimabrain-ce
    restart: unless-stopped

    ports:
      - "8601:8601"

    environment:
      ZIMABRAIN_PASSWORD: "change-this-password"
      ZIMABRAIN_SECRET_KEY: "change-this-secret-key"

    volumes:
      - /DATA/AppData/zimabrain-ce:/data
      - /DATA/AppData/zimabrain-ce/docs:/app/docs
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/hostname:/host/etc/hostname:ro
      - /var/run/docker.sock:/var/run/docker.sock

x-casaos:
  architectures:
    - amd64
  main: zimabrain-ce
  author: gelbuilding
  category: Utilities
  description:
    en_us: Local ZimaOS diagnostic assistant with verifier-first evidence checks.
  developer: gelbuilding
  hostname: ""
  icon: "https://raw.githubusercontent.com/Jacko88888/zimabrain-ce/main/app/assets/zimabrain-ce-logo.svg"
  index: /
  port_map: "8601"
  scheme: http
  store_app_id: zimabrain-ce
  tagline:
    en_us: Local ZimaOS diagnostic assistant
  title:
    en_us: ZimaBrain CE

After install, open:

http://YOUR-ZIMA-IP:8601/

Example:

http://192.168.1.100:8601/

You can also check health from terminal:

curl -fsS http://127.0.0.1:8601/health && echo
docker ps --filter name=zimabrain-ce

Expected health result should include:

"ok": true

Suggested questions to test:

What needs attention?
Are there any failed services?
Is systemd-networkd-wait-online failed?
Is zimaos-welcome running?
What service is using disk?
What is causing disk activity?
What is using CPU?
Explain disk CRC errors
Which disks need attention?
Which containers are not running?
Why is Immich not starting?
Check Immich container paths and mounts
Are there any Files / AppData / media path problems?

The question mark is not required. These should work both ways:

Why is Immich not starting?
Why is Immich not starting

Please remember this is still beta. The goal is to keep improving the verifier from real ZimaOS exports and real user problems. If ZimaBrain misses something, that is useful feedback too, because it shows us exactly where to improve the next layer.

Small note about the ZimaBrain CE password.

In the Custom App compose, there are two environment values:

ZIMABRAIN_PASSWORD
This is the login password you type on the ZimaBrain login page.

ZIMABRAIN_SECRET_KEY
This is not a login password. It is only used internally by the app for browser/session security.

Before installing, please change the example values:

ZIMABRAIN_PASSWORD: “change-this-password”
ZIMABRAIN_SECRET_KEY: “change-this-secret-key”

Use your own password for ZIMABRAIN_PASSWORD, and use any long random value for ZIMABRAIN_SECRET_KEY.

If you already installed ZimaBrain before and the login password does not work, it may be because an old saved password hash already exists in the data folder.

To reset it:

sudo rm -f /DATA/AppData/zimabrain-ce/.zimabrain_password_hash
sudo docker restart zimabrain-ce

Then log in again using the value you set for ZIMABRAIN_PASSWORD.

Do not post your real password or secret key in screenshots.

1 Like
38

This version is much better. The separation between Real Alerts, Container/Service Alerts and Info Only makes the dashboard much easier to understand.

I especially like the improved watchdog explanation showing that the related service is currently running.

One suggestion: I think exited containers are still a bit too prominent. Many users intentionally keep some containers stopped, so showing all of them as yellow warnings may cause unnecessary concern. Perhaps they could be classified as “Needs Review” or “Info” unless there is evidence that the container is expected to be running or is repeatedly crashing.

Overall, this is a significant improvement compared to the previous beta.

1 Like
39

This is another improvement compared to previous versions, but I think the answer is still broader than necessary.

When I ask:

“Check Immich container paths and mounts”

I expect the primary focus to be on the Immich containers only.

The answer correctly lists the Immich bind mounts, but it also includes many unrelated containers (Plex, VLC, Firefox, Komga, etc.), making it harder to quickly identify whether Immich itself has a problem.

I think it would be more useful if the response were structured like this:

Immich verification

  • Immich Server: ✓ Mount verified

  • Upload path: ✓ /DATA/.media/sda4/Media/Gallery/immich/upload

  • Redis: ✓ Mount verified

  • Result: No obvious bind-mount issues detected.

Then, optionally:

Related information

  • Other containers using similar storage paths…

That would make the answer much easier to read while still allowing access to the additional evidence if needed.

1 Like
40

I found another case where the intent detection could be improved.

When I ask:

“Are there any Files / AppData / media path problems?”

this is intended as a system-wide ZimaOS question, not an application-specific one.

The current response says:

“No app name was detected from the question.”

I don’t think an app name should be required here. The question is asking for a global verification of the Files, AppData and media paths.

Instead, I would expect ZimaBrain to inspect things such as:

  • /DATA/.media path mappings

  • /media mount consistency

  • AppData locations

  • broken symlinks

  • duplicate mount names

  • missing storage paths

  • read-only media

  • known ZimaOS Files/AppData issues

Only if the question explicitly mentions an app (for example, “Check Immich paths”) should the response switch to application-specific diagnostics.

I think this question should be handled by the global Files/AppData verifier rather than the app runtime diagnostic layer.

1 Like
41

I found another issue while testing.

One of the suggested test questions is:

“Are there any failed services?”

However, this does not seem to route to the failed-service verifier.

Instead, ZimaBrain returns:

  • GUIDANCE ONLY / NOT VERIFIED FROM CURRENT REPORT

  • Active layer: Fallback Guidance Route

This surprised me because “Are there any failed services?” is one of the example questions in your announcement.

I would expect this question to use the failed systemd verifier and inspect the current systemctl evidence, just like the dashboard alert panels do.

It looks like this intent is either not being matched correctly or is not yet connected to the failed-service diagnostic layer.

1 Like