Current Answer: Use ZimaOS OpenAPI for Real Integration; Treat Internal Dashboard Routes as Unstable
The original request was to add Homer/Homarr buttons for Settings, Backup and App Store. There are two different goals hiding inside it: open a ZimaOS screen and integrate ZimaOS data/actions into another dashboard. For the second goal, ZimaOS now has an official OpenAPI. That is much more reliable than scraping private frontend URLs or reverse-engineering popup routes.
The ZimaOS OpenAPI documents programmatic file, user and system operations. The developer index also provides an API explorer.
For Simple Dashboard Tiles, Link to Stable Service Entry Points
Use the ZimaOS dashboard root for administration and direct app URLs for containerized applications. If Homarr/Homer only needs a tile that launches Plex, Paperless or another app, use the app's host/IP and published port rather than a ZimaOS internal popup route.
That gives you a URL controlled by the service itself and avoids coupling your homelab homepage to ZimaOS frontend implementation details.
Why Settings, Backup and App Store Are Harder to Deep-Link
ZimaOS is a single-page web application. Some panels are opened through internal state, modal logic or routes that were not published as a stable external interface. Even if you discover a URL in browser developer tools today, an update can change it without violating any public API contract.
So the rule is simple: use a deep link only when ZimaOS explicitly publishes it as stable. Otherwise link to the dashboard root and use OpenAPI for actual automation.
Use OpenAPI When You Need Live Status in Homarr
A custom widget can query supported endpoints and render storage, user or system state in the third-party dashboard. Follow the authentication method defined by the API rather than copying browser session cookies into a public dashboard configuration.
The ZimaOS developer tools is the current integration surface. For container dashboards, the Portainer requirements gives the Docker-side context.
ZimaOS's published API follows an OpenAPI-described interface, which is the right boundary for generated clients and external integrations. The OpenAPI specification explains why an explicit API contract is more stable than scraping browser routes from a single frontend build.
Do Not Embed the Full ZimaOS Admin UI in an Untrusted iframe
Embedding an admin interface introduces authentication, frame-policy, origin and clickjacking concerns. If a dashboard only needs a launch button, open ZimaOS in a normal browser tab instead. If it needs data, query the API and display only that data.
OWASP's clickjacking risks explains why framing privileged UIs should be deliberate.
Use Your Own Icons Instead of Scraping ZimaOS Frontend Assets
For Homer/Homarr tiles, choose stable icons you control or use the third-party app's own icon. Pulling hashed frontend assets from a ZimaOS build can break when the UI is rebuilt. If you need brand assets, use publicly distributed assets with appropriate branding rather than depending on private bundle paths.
Separate Read-Only Dashboard Data From Administrative Actions
A home dashboard showing disk use or service status can often use read-only access. Restarting services, changing users or modifying storage needs a much stricter authentication boundary. Do not give a wall-mounted dashboard the same credentials as the owner account merely to display a few status cards.
The ZimaOS app requirements and ZimaOS HTTPS proxying cover the surrounding app and HTTPS layers.
A Practical Homer or Homarr Integration Plan
- Add a tile for the ZimaOS dashboard root.
- Add direct tiles for individual self-hosted apps.
- Use OpenAPI for status widgets that need live ZimaOS data.
- Keep write/admin API credentials out of client-side dashboard JavaScript.
- Re-test integrations after major ZimaOS frontend/API upgrades.
FAQ
Can I deep-link directly to ZimaOS Settings?
Only treat a route as reliable if ZimaOS publishes it as a stable interface. Internal SPA/modal routes can change between releases.
Does ZimaOS have an API now?
Yes. Current ZimaOS developer material exposes OpenAPI resources for programmatic integration.
Can Homarr show ZimaOS storage status?
A custom integration can query supported API endpoints and render the returned data, subject to authentication and endpoint availability.
Should I iframe the whole ZimaOS dashboard?
Usually no. A normal launch link or API-powered widget has a cleaner security and compatibility boundary.
Where should dashboard icons come from?
Prefer assets you control or stable public brand/app icons instead of scraping hashed files from the ZimaOS web bundle.
