Link: https://github.com/HarshShah0203/homedex

There is a thread in every selfhosted community every few weeks about keeping documentation together, and the top answer is usually a joke about not having any. That is what this is for.

Homedex connects to your Docker hosts, plain SSH hosts, and Traefik, Caddy or Nginx Proxy Manager, then keeps a record of what is running where, on which port, behind which route, and when the certificates expire. It also keeps a change feed of what actually moved since the last scan, and flags routes pointing at containers that no longer exist.

The part I could not find anywhere else: it parses reverse proxy config and joins it against discovered containers, so you get the domain to container mapping. That is the one nobody remembers and nobody writes down.

Why not the usual suggestions. NetBox is good but it is a source of truth you type into, and for a homelab it becomes a chore. This has zero data entry. Scanopy draws topology maps, which is a different question to keeping records. Portracker does ports only, no routes or certificates.

One Go binary with the UI embedded, or a distroless container around 12MB for amd64, arm64 and armv7. SQLite on disk, no telemetry, works fully air-gapped. Read-only by design: there are no write paths to the Docker API at all, the bundled compose file reaches the socket only through a filtering proxy with POST disabled, and container environment variables are never ingested so credentials cannot end up in an export. There is a CI check enforcing that last one.

MIT, self-hostable in full with no paid tier. A month and a half old, one contributor, green CI and tagged releases. I run it against my own stack but I am not claiming maturity.

AI declaration

• Design (architecture, system design): Pair
• Implementation (production code): Generated
• Testing (tests, test plans, QA): Generated
• Documentation (docs, comments, README): Generated
• Review (code review, PR feedback): Assisted
• Deployment (CI/CD configuration): Generated

I set the data model, the connector interface and the security posture, and reviewed and reworked throughout, but most of the code itself was generated under that direction.

One concrete example of what that costs, since it is more useful than a label: containers were originally keyed by their Docker container ID, so a redeploy issued a new ID and the tool silently orphaned any notes attached to a service and reset its first-seen date. Fixed in v0.1.4 by keying on the container name. The compose service name does not work either, because scaling gives three live containers the same one.

You are aware that this is exactly why the rules require [AIP] in the title and AI declaration in the body?

Always good to be thorough

This post is tagged properly and has a full disclosure.

Off topic comments will be removed.

Or unbearable, whatever

Cool project idea! Some questions:

It seems the project currently exclusively watches docker related stuff. Is there any plan to watch services more broadly? Most of my stuff is running directly on the machine as a systemd service without any container (probably bad practice sue me). I’m not sure how feasible it would be to chase down everything that’s supplying a local host endpoint tho.

What’s your AI workflow like? What model, what harness etc

Ah, you luddites amuse me.

The horses left the building a long time ago, and here you just now noticed and decide to play Don Quixote.

The irony

So, how do you reach the app when trying over local network?

http://192.168.1.X:7377 is unreachable, and I can't find the env vars at a glance in the docs.

Edit: found it, HOMEDEX_URL, buried in docs > CONNECTORS.md. But I was so busy looking for an env var I missed the docker port mapping unnecessarily binding to 127.0.0.1:port. I think you can drop the 127.0.0.1 in the default docker-compose.yml.

Please stop hosting your FOSS and selfhosted stuff in Github folks. It's so contradictory, and some of us are just locked out of github.

Some of us still run Apache. :)

IIRC putting an IP in the port binding binds only that interface while omitting it will bind on all interfaces, so it's not quite the same thing

True, but in practice the IP is not used in deployment defaults.

I eman I have deployed probably hundreds od containers by now, and that's what I have seen.

Ugh slop community, byeeeee

Yes, the SSH source covers that. It reads listening ports with ss over SSH, so systemd services on bare metal show up as processes with their ports, no containers needed.

One catch: to get names for services running as other users, the SSH account has to be able to see them (root can). Otherwise they show up as unnamed listeners. Reading systemd unit names directly isn't there yet, good idea though.

Fair catch, thanks. Loopback is the default on purpose, since whoever opens a fresh instance first sets the admin password. But it shouldn't take digging.

Just pushed a fix: HOMEDEX_BIND=0.0.0.0 docker compose up -d --build opens it to your LAN, and the quickstart says so up front. HOMEDEX_URL is only for the add-connector script, the docs are clearer on that now too.

Ha, fair. Apache would sit next to nginx config parsing, which is already on the list. Noted.