NixOS (13): Lessons from Maintaining the System with AI

Motivation

#

In post one, I explained why I returned to NixOS. Being able to ask AI for help finding documentation, writing configuration and investigating errors was an important part of that decision.

After the migration and subsequent maintenance, several computers now share one flake, and their user environments, services and operational notes have gradually been organized. Configuration can still end up in the wrong place, builds can fail and services can behave unexpectedly. There is now an assistant that can read files and work on changes alongside me.

The earlier posts covered tools and their use. Here I will look back at the work AI helps with and how I check its changes. The examples come from maintenance and writing during this period, without reproducing private configuration or attributing every problem to AI.

Work AI Can Help With

#

Finding Options and Explaining Errors

#

NixOS has many modules and options. When approaching a service, I usually need to find its documentation and check what the current version supports. AI can read existing configuration, locate the relevant module and explain the files and options mentioned in an error, giving me a starting point.

I find this particularly helpful for reducing the time spent searching across files. A conflict might involve both a shared module and a host module. AI can locate both definitions and explain their purpose. We still need to decide whether to change a default, adjust imports or use an override, as discussed in post six.

Option names and examples need to match the locked version. Online configurations can come from different releases or dates and may not work together. Asking AI to inspect the current module source makes a proposal easier to check than relying on a plausible option from memory.

Organizing Repeated Configuration

#

AI can help identify tools and user settings shared by several computers and move them into common modules. Hardware, displays and differences in purpose stay separate.

That is also why I use one flake for several computers. Similar-looking files do not necessarily belong together: a server and desktop need different services, and a driver setting may suit only one host. After changes, check which modules each host actually imports.

Preparing Checks and Maintenance Notes

#

AI can run clearly specified checks, organize build logs and update instructions from command results. It also reduces some manual work in Git synchronization, submodule updates and repeated deployment steps.

Notes need to follow what actually happened. Synchronizing source, completing a build, applying configuration and rebooting are different operations. Documentation-only changes create no new system generation. The previous post explained how I handle these steps separately.

Describing a Task

#

I generally start with the intended result, then explain how far the work may proceed. A software name is only part of that. Remote desktop, for example, might mean sharing an already logged-in desktop or using a computer without a monitor. Those need different configurations.

For a configuration change, a request could look like this. It is an illustrative example, not an original transcript:

Add a demonstration web page accessible only from this computer. Read the existing service configuration first, check for port conflicts and put the change in an appropriate module. Build it without applying or rebooting. Explain which files changed and how to check the page after applying.

This specifies purpose, access scope and whether to apply the configuration. Rather than writing a long prompt each time, I keep recurring conventions in maintenance instructions and describe what differs for this task. See post four for organizing those instructions.

Some decisions should not be guessed, such as whether a running job can be interrupted, which data can be deleted or where a service should move. Supply that information before proceeding.

Checking AI Changes

#

Reviewing File Changes

#

First inspect Git changes:

1
2
3

git status --short
git diff
git diff --cached

Check whether the changes meet the request, which modules they enter and whether unrelated content changed. Preserve existing uncommitted work, then explicitly choose the files belonging to this change.

For unfamiliar Nix syntax, ask AI to explain the option’s type, defaults and module source. The explanation should be traceable to current source or documentation, especially for service permissions, startup order and data directories.

Building and Trying the Result

#

For an existing flake, check and build an example host:

1
2

nix flake check --no-build --show-trace
nixos-rebuild build --flake .#laptop --no-update-lock-file

Replace laptop with your own output. These commands do not apply configuration, and --no-build does not run checks requiring builds. After a successful build, decide when to apply according to the task. See post five for the procedure.

After applying, try the actual function. Check a service’s state and access it from the intended location, inspect desktop settings after a new login or test the device affected by a driver change. AI with only SSH access can perform some of this, but display, touch and pen behavior often needs someone at the computer.

Problems Encountered During Maintenance

#

Selecting a Host Output

#

Early in setting up one computer, a compatibility output name was used that actually selected another computer’s configuration. That brought in hardware settings intended for the other host. The maintenance records later show the correct output selected.

A command running successfully does not establish that it selected the right computer. Before an AI assistant builds or applies, check the flake output and the hardware and host modules it imports. Use an explicit host name rather than an easily confused alias.

Build Time and Disk Space

#

A kernel build also failed for lack of space and completed only after space was addressed and the build retried. A few lines of Nix changes can require substantial compilation.

I now check space and existing build references before large updates and allow enough time. AI can read logs and explain an error, but repeatedly running the same command cannot resolve a full disk. Identify the generations retained for recovery before cleaning up.

Service State and Data

#

Some problems appear only when programs run. Generated container configuration still needs Compose applied. A started service still needs its access route checked. A cross-host synchronization job still needs confirmation that the intended directories reached the copy.

While organizing data, an incorrect service-source entry was found to cause a directory to be skipped. A successful job alone cannot confirm that all intended data was saved. Databases also need their own backup and restore methods; ordinary file synchronization cannot replace those checks.

For migrations, I stop writes at the original location, prepare configuration, secrets and consistent data, and check the destination before switching access. AI can help execute this arrangement, but it needs an explicit current data source so an old copy cannot overwrite the new data. These experiences are covered in post ten and post eleven.

Using AI for Documentation and Blog Posts

#

This series has had similar issues. Asking AI to follow an outline can produce a complete tutorial whose chosen tools and examples do not necessarily match the methods I use on the computers.

Reviewing the drafts meant adding the actual secrets, Compose deployment and data synchronization arrangements, and explaining the separate teaching examples. A restic exercise can explain historical backups, for instance, without establishing that the computers already use that backup system. Actual experience and optional methods need separate explanations.

Writing style needed attention too. A motivation heading did not stop the body from sounding like operational notes, with repeated reminders to check and verify. I returned to earlier Python and Docker articles, adjusted paragraphs and headings, and rewrote passages more like my usual tool explanations.

I therefore find AI useful for organizing material and preparing a draft, while experience, choices and wording still need my review. Real configuration, keys and logs need checking before sharing too. General methods can be published while private content stays in my own environment.

Recommended Usage

#

For NixOS maintenance, I prefer giving AI a small, clear change first: read the related files, explain the proposal, then check and build. Confirming one change before moving on is easier to understand than changing many settings on several computers together.

Keep recurring conventions and solved problems in repository documentation. Both AI and I can reread it next time instead of relying on remembering an earlier conversation. Rebuildable software still needs separate arrangements for data, secrets and recovery.

For me, AI has made continuing with NixOS more convenient. I still need to understand configuration and try the functions I use. These thirteen posts collect the concepts and methods currently useful to me. Further hardware support or service migration experience can become supplementary articles.