How Collimo is built

Collimo is closed source, so you can't read the code to decide whether to trust it. This page says how it's made instead: who decides what it does, how it's tested, what it's allowed to touch, and what we don't claim yet.

Who builds it, and with what

Collimo is designed by an infrastructure engineer: someone who builds and runs fleets of machines for a living, keeps configuration in git, and gets the alert when something breaks. Not a career software developer.

Much of the code is written with Claude Code, Anthropic's AI coding tool. We say so up front because you'd want to know, and because how it's used matters more than whether it is:

• A person decides what Collimo does and the rules it follows. The AI writes code to those rules; it doesn't choose them.
• Every rule is written down first. Collimo has more than 50 design decisions on record, each with the reasoning behind it, and the AI works from them. When a change would break one, the change is wrong, not the rule.
• Nothing reaches you untested. Every change runs the full test suite below, and a release goes through a second person on real equipment first.

The assistant inside Collimo is a separate thing: an optional feature you point at a model of your choice. It's not how Collimo is built.

The rules come from running infrastructure

Most of Collimo's behaviour follows from rules learned the hard way, by being paged for nothing and missing what mattered:

• Absent is not zero. A switch with no fan reports no fan, not a fan at 0%. Otherwise a dead fan and a fanless switch look the same.
• A counter is not a health signal. A port that logged a million errors two years ago isn't broken today. Collimo alerts on errors climbing now.
• Slow is relative to that port. A printer at 100 Mb/s is fine. A port that ran at 10G last week and is at 5G today is not.
• A figure ships with how much of it is known. Thirty-day availability from two days of history says so beside it, rather than pretending.
• Alerts are decided in one place, so the dashboard, the metrics and your phone can never disagree.
• Watching is the default; changing is opt-in. Every account you give Collimo can only look. See what it never does.

How it's tested

Every change runs all of this before it's committed, and again on our build server on every push:

• Over 400 unit tests, across every part of Collimo.
• An end-to-end smoke test, about 200 checks, that runs the real program against simulated equipment: two UniFi consoles, Proxmox VE, PBS, vCenter, the NAS systems, BMCs, UPSes, PDUs, SNMP switches, NetBox and phpIPAM. The simulations are deliberately messy, the way real equipment is: numbers sent as text, missing readings, an offline switch, a failed disk, a gateway mid-failover, a modem blaming the cable network, and an account that's refused.
• A payload corpus. What real consoles and appliances have sent is replayed with each field mangled in every way vendors are known to send it: quoted, empty, null, a word instead of true or false, or missing. Every one must still be read. One bad field once cost a whole recorder's readings, and this is what stops that happening again.
• A scale test of a site far bigger than any we run: 120 48-port switches and 250 access points, each poll well inside the shortest poll interval.
• Upgrade tests. Every released version's archive and settings must open in the new build with nothing lost, because an upgrade that quietly forgot your outage history would defeat the point.
• A secrets check that fails the build if anything shaped like a password, token or key is ever committed.
• The release build itself is smoke-tested, built exactly as it ships, before anything is published, and each image is checked to hold the right program for amd64 and arm64.

How a change reaches you

1. Development. Day-to-day work, tested as above.
2. QA. A second person runs it on their own site, with different hardware, before anything goes further.
3. Release. Only tested work is merged into the release branch, and it's protected so nothing reaches it any other way. Images are built from a tagged release, for amd64 and arm64.

The compatibility list says which equipment has been run for real and which is built from the maker's published API and tested against recorded answers. We don't blur the two.

What it's allowed to touch

• Read-only accounts on everything it watches. Each setup guide asks for the least that system allows (Synology is the one exception, explained in its guide).
• No third-party code. Collimo is written on Go's standard library alone. The protocols it speaks (SNMP, the Prometheus format, the PostgreSQL wire protocol, S3, LDAP and OIDC) are written for Collimo, so there's no dependency to fall behind on security fixes or be taken over.
• A minimal image. The container holds the Collimo program, a CA certificate bundle and its bill of materials, and nothing else: no shell, no package manager.
• Locked down by default. It runs as an unprivileged user, on a read-only filesystem, with every Linux capability dropped and privilege escalation turned off. The ping it uses to test your WAN works without any extra capability.
• Nothing to open to the internet. Collimo only ever reaches out; no site it watches needs a port opened from outside.
• Nothing about your network leaves it, apart from what you turn on yourself. License check and privacy lists every connection Collimo makes and what it carries.

How you can check without the source

• Watch its traffic. Point a packet capture at it. License check and privacy says what you should see.
• Read the bill of materials in every image, at /sbom.cdx.json.
• Give it accounts that can only read. Then the worst it could do is be wrong.
• Report anything you find to [email protected] (Reporting a security problem).

What we don't claim yet

• No independent security review has been done yet. We'd like one before 1.0, and this page will say when it has.
• Images aren't signed yet. Signing starts with 1.0.
• Not every integration has met real hardware. The compatibility list is the honest picture, and beta reports are how it fills in.
• It's a beta. Expect rough edges, and please tell us when you find one.

Talk to us

Questions about how Collimo is made, or what it does with your data, are welcome:

• The Collimo Discord is where the people building Collimo and the people testing it talk, and where beta keys are given out.
• GitHub issues for a bug, a piece of gear you'd like read, or a report of how it went on yours.
• [email protected] for anything security-related, privately.