HavenOS Project and the 3D Printing of Personal Software

Intro

Over the last couple of years, AI coding tools have changed the threshold for software. An idea can now be worth crafting even when it is too specific to become a product, because getting from that idea to something useful has become dramatically cheaper.

The comparison which comes to mind is 3D printing. Its value is not that it replaces industrial manufacturing, but that it makes otherwise uneconomical objects worth creating! It does not need a market because it solves one particular problem for one particular person ... or a few.

AI-assisted coding is beginning to do something similar for software, and this is roughly where HavenOS came from.

What This Is About

I have gradually started accumulating physical media again: CDs, Blu-rays and books, together with a growing digital library around them.

There is already a lot of open-source software for organising and accessing them, with a rich set of features. However, the barrier to entry is higher than it should be.

You find a good project with thousands of stars on GitHub and, a few minutes later, you are installing Homebrew, checking Python versions, creating virtual environments, configuring a database, generating credentials and working out how the application should restart after the Mac reboots. None of these steps is especially unusual for a software engineer, but they are a strange prerequisite for somebody who simply wants to keep their books or music on a computer at home.

I already liked the Mac mini as a concept for a home server, so I started wondering whether it could begin to behave like one: install one native Mac application, choose what you want the machine to do and let HavenOS take care of the infrastructure underneath.

For example, Books: behind that capability there could be several open-source projects, but the user should not need to understand how they fit together. HavenOS would know which software provides the capability, where to obtain it, how to configure it and how its individual processes should be managed.

Building this turned out to be much more interesting than automating a collection of installation scripts. README files are written for people and are full of instructions such as “install this if needed,” “create a database” or “set these environment variables.” A developer reading them supplies a remarkable amount of missing context without noticing.

My first thought was that an AI agent could interpret those instructions and perform the setup. That worked surprisingly well in experiments, but I gradually became uncomfortable with the idea of an agent improvising through shell commands on a machine I expect to keep running for years. AI is extremely useful while building HavenOS, but I do not want an unpredictable agent administering the finished system.

The project therefore moved in almost the opposite direction. If there is a pinned binary available, HavenOS should just download it directly. If it can avoid introducing Homebrew, Docker or another package manager, it should. The important thing is not merely completing an installation once, but knowing what was installed, where it lives and how to reproduce or undo every change, like a pipeline.

In roughly six weeks, HavenOS moved from a small command-line skeleton to a native application managing books, music, movies and files. The first substantial work was a strict specification loader and a planner that could resolve a requested capability into a concrete installation without modifying the machine. The SwiftUI interface arrived later, initially using mock data.

The process

The original design allowed a bundle to contain several capabilities, but this was simplified almost immediately to one bundle per capability. Service definitions moved from bundled JSON files to a local catalogue organised into per-service folders. Later, the core services moved into the application as native Swift specifications, while a facade layer separated ideas such as Books and Music from Kavita and Navidrome, the particular projects currently providing them. What started as a generic service manager gradually became an application organised around what a user wants to do.

Installation followed the same pattern of trying something, testing it against reality and revising it. The early executor could install native applications but explicitly rejected Python services. Later, Python returned through isolated, versioned environments. The first live Navidrome installation exposed problems with home-directory paths and failed downloads, while Kavita collided with the AirPlay service already using port 5000 and required a different working directory. Even the integration with macOS had reversals: newer launchd commands produced recurring failures, so HavenOS returned to an older but more reliable approach.

Those failures gradually produced a small deterministic installation language with eight operations, path validation and automatic rollback. It could create directories, move files, write configuration, create symlinks and generate cryptographic secrets for later installation steps. Credentials then grew from temporary installation values into a platform responsibility as HavenOS began creating accounts and reconnecting to services automatically (if a user wanted!). An attempt to move them into Keychain was also reversed when it introduced repeated permission prompts and launch risk. The less technically elegant choice produced the more dependable user experience.

This is one of the more useful lessons I have taken from the project. AI did not produce the correct architecture on the first attempt. What it changed was the cost of discovering that an architecture was wrong. Decisions that might previously have been too expensive to revisit could be tested against a real service, discarded and replaced.

Backups made the relationship between experimentation and trust even clearer. Initially, I thought of backup as another feature on the roadmap. Then I imagined relying on HavenOS for a library assembled over many years and eventually losing or replacing the Mac mini underneath it.

The media files are only part of such a system. There is also metadata, configuration, service state and the credentials connecting everything. If the machine fails, I do not want a collection of instructions explaining how to reconstruct several applications. What I actually want is much simpler: I want my Books back.

The backup implementation itself changed direction several times. It began by including media, databases, configuration, service state and credentials together with a restore engine. It was then narrowed to media-only backup and per-capability file restoration. Multi-folder libraries exposed a synchronisation bug that required another rewrite. Configuration, service state and credential snapshots eventually returned to the backup format, while the complete restore experience was removed from the initial scope.

That last decision matters because personal software should not promise more safety than it can provide. HavenOS can currently create scheduled, capability-aware backups and show what is protected, but rebuilding an entire installation on another Mac is still unfinished. The long-term goal remains recovery at the level the person understands, but the system first has to earn the right to make that promise.

Conclusion

There is also a less technical reason I enjoy the project. I still stream music and films, but I started buying CDs and Blu-rays in 2017 and keeping the books I care about. It is not really nostalgia; I simply like the difference between having temporary access to something and owning something I deliberately chose.

I think of this as a form of slow tech: keeping the convenience of modern technology while being more selective about which parts of your digital life you want to rent. A small server at home feels like a natural extension of that collection, but only if maintaining the server does not itself become another hobby.

That is the version of HavenOS I want: a Mac mini quietly looking after the digital things I own while hiding most of the infrastructure required to keep them useful.

This brings the project back to the original comparison. AI makes increasingly personal software economical to explore, and open source provides an enormous collection of components from which to build it. Neither automatically makes the result reliable. That still comes from testing assumptions, simplifying designs and sometimes reversing decisions that looked correct only a few days earlier.

Much like 3D printing, the interesting change is not simply that we can make things faster. It is that we can afford to discover and build the particular shape that fits our own lives.