NixOS Basics for osModa Users
osModa runs on NixOS — a Linux distribution that takes a fundamentally different approach to system configuration. Instead of running commands to change your system (apt install, yum update), you declare what your system should look like in a configuration file, and NixOS builds it. This guide covers what you need to know as an osModa user: declarative configuration, adding packages, generations and rollback, SafeSwitch deployments, and the key differences from Ubuntu/Debian.
Last updated: March 2026 · No prior NixOS experience required
Key concepts
- Declarative: Your system is defined in /etc/nixos/configuration.nix. Change the file, run nixos-rebuild switch, and the system matches your declaration.
- Generations: Every nixos-rebuild switch creates a numbered snapshot. Roll back to any previous generation instantly.
- SafeSwitch: osModa's name for atomic deployment + auto-rollback. Deploy changes atomically — if the new state is broken, revert in seconds.
- Reproducible: The same configuration.nix produces the same system on any machine. No drift, no mystery packages, no "works on my machine."
Why osModa Uses NixOS
AI agents run 24/7 for weeks or months. Over that time, traditional Linux distributions drift — packages update inconsistently, config files are modified by hand, dependencies conflict silently. This drift is the number one cause of unexplained agent failures: "it worked yesterday" becomes a regular occurrence.
NixOS eliminates drift by design. The entire system state is derived from a single configuration file. If an agent worked with generation 42, you can always return to generation 42 and it will work again — same packages, same versions, same configurations, guaranteed.
Reproducibility
The same configuration.nix produces the same system every time. If you need to rebuild a server from scratch (hardware failure, scaling up, disaster recovery), your configuration file recreates the exact environment. No manual steps to forget.
Atomic changes
System changes are all-or-nothing. When you run nixos-rebuild switch, either the entire new configuration succeeds or the system stays on the previous configuration. There is no half-installed state where some packages updated but others did not.
Instant rollback
Every configuration change creates a new generation while preserving previous generations. Rolling back is not "undo the last change" — it is "switch to generation N, which is known to work." This takes seconds, not minutes.
Declarative Configuration: The Core Concept
On Ubuntu, you install packages imperatively:apt install python3. The system state is the accumulated result of every command you have ever run. Two systems with the same initial image diverge as soon as you run different commands on each.
On NixOS, you declare what you want in /etc/nixos/configuration.nix and apply it. The system state always matches the current configuration file.
Ubuntu (imperative — order matters, state accumulates):
apt update apt install python3.12 python3-pip git curl apt install nodejs npm # What if someone ran apt remove curl last week? # What if pip was installed via pip, not apt? # State is a mystery after enough time passes.
NixOS (declarative — the file IS the system):
# /etc/nixos/configuration.nix
{ config, pkgs, ... }:
{
environment.systemPackages = with pkgs; [
python312
python312Packages.pip
git
curl
nodejs_22
];
services.openssh.enable = true;
networking.firewall.allowedTCPPorts = [ 22 8080 ];
}
# Apply: nixos-rebuild switch
# The system now has EXACTLY these packages.
# Nothing more, nothing less. No mystery state.This is the single most important concept in NixOS. The configuration file is the source of truth. If a package is not in the file, it is not on the system (after the next rebuild). If a service is not declared, it does not run. Your system is exactly what you say it is.
How to Add Packages and Configure Services
Adding a package to your osModa server is a three-step process: edit the configuration file, rebuild, and verify.
Step 1: Edit the configuration
# Open the configuration file
nano /etc/nixos/configuration.nix
# Add packages to environment.systemPackages
# Example: adding Redis and PostgreSQL
environment.systemPackages = with pkgs; [
python312
git
redis # add this
postgresql_16 # add this
];
# Enable services declaratively
services.redis.servers."default" = {
enable = true;
port = 6379;
};
services.postgresql = {
enable = true;
package = pkgs.postgresql_16;
};Step 2: Rebuild and switch
# Apply the new configuration nixos-rebuild switch # This: # 1. Downloads/builds required packages # 2. Creates a new generation # 3. Switches the system to the new generation # 4. Starts any new services # All atomically — no half-installed state
Step 3: Verify
# Check the new generation was created nixos-rebuild list-generations | head -3 # Verify packages are available redis-cli --version psql --version # Check services are running systemctl status redis systemctl status postgresql
Quick testing without permanent install: If you want to test a package before adding it permanently, use nix-shell:
# Temporarily enter a shell with htop available nix-shell -p htop # htop is available in this shell only # Exit the shell and it is gone # No system state was changed
Generations: Every Change Is a Rollback Point
Every time you run nixos-rebuild switch, NixOS creates a new numbered generation. The previous generation is preserved intact. This means you always have a working system to fall back to.
Working with generations:
# List all generations nixos-rebuild list-generations # Example output: # 42 2026-03-08 14:30 NixOS 24.11 (current) # 41 2026-03-07 09:15 NixOS 24.11 # 40 2026-03-05 16:22 NixOS 24.11 # 39 2026-03-01 11:00 NixOS 24.11 # Roll back to the previous generation nixos-rebuild switch --rollback # Now generation 41 is active # Generation 42 still exists — you can switch back # Switch to a specific generation (via boot) # Previous generations are available in the boot menu
How this saves you in practice:
# Scenario: You add a package that breaks your agent nano /etc/nixos/configuration.nix # add some-package nixos-rebuild switch # generation 43 created # Agent crashes because of a library conflict! # Fix: instant rollback nixos-rebuild switch --rollback # back to generation 42 # Agent is running again. 10 seconds total. # Now investigate the issue at your leisure # The broken generation 43 is preserved for debugging # Your agent never stays down longer than a rollback takes
SafeSwitch: Atomic Deployment and Auto-Rollback
SafeSwitch is osModa's name for the deployment model built on NixOS generations and osmoda-watch. It adds intelligence on top of basic nixos-rebuild: after switching to a new generation, osmoda-watch verifies that your agent is healthy. If the agent fails health checks after a deploy, osmoda-watch can trigger an automatic rollback.
1. Deploy atomically
nixos-rebuild switch applies all changes at once. The system transitions from generation N to generation N+1 without any intermediate state. Either the full new configuration is active or the old one is.
2. Verify health post-deploy
osmoda-watch checks that your agent process starts and passes health checks after the configuration switch. This happens automatically — osmoda-watch knows a deploy just occurred and monitors more aggressively for the first few minutes.
3. Auto-rollback on failure
If the agent crashes immediately after a deploy, osmoda-watch can trigger a rollback to the previous generation. The entire system reverts — packages, services, configurations — not just the agent code. Your agent returns to the last known-good state.
SafeSwitch is what makes osModa deployments safe to run unattended. You can push a configuration change and walk away. If it breaks something, the system fixes itself. Every deploy, rollback, and health check is recorded in the audit ledger.
Key Differences from Ubuntu/Debian
If you are coming from Ubuntu or Debian, these are the things that will trip you up. None are hard — they are just different.
Ubuntu/Debian NixOS equivalent
───────────────────────────── ──────────────────────────────────
apt install <pkg> Add to configuration.nix, then:
nixos-rebuild switch
apt update && apt upgrade nix-channel --update
nixos-rebuild switch
dpkg -l nix-env -q (or check config file)
/etc/apt/sources.list nix channels (nix-channel --list)
systemctl enable <service> services.<name>.enable = true;
in configuration.nix
/etc/<service>/config Declared in configuration.nix
under services.<name>.settings
Manual config file editing Declarative in configuration.nix
(configs are generated from Nix)
No built-in rollback nixos-rebuild switch --rollback
(instant, any previous generation)
Filesystem hierarchy standard Nix store (/nix/store/...)
Binaries symlinked to /run/current-systemPackage names are different
Ubuntu: python3. NixOS: python312. Ubuntu: nodejs. NixOS: nodejs_22. Search search.nixos.org/packages to find the right name.
Config files are managed by Nix
On Ubuntu, you edit /etc/nginx/nginx.conf directly. On NixOS, you declare nginx settings in configuration.nix and NixOS generates the config file. Editing generated files directly works temporarily but gets overwritten on the next rebuild. Always configure through Nix.
The Nix store
Packages live in /nix/store/ with hash-based paths (like /nix/store/abc123-python-3.12.1/). This is how NixOS achieves reproducibility — multiple versions coexist without conflicts. You rarely interact with /nix/store directly; system paths are symlinked automatically.
The learning curve is real but short. Most osModa users become comfortable with NixOS within a day or two. The payoff — reproducible systems, instant rollback, no configuration drift — is worth it for any agent that needs to run reliably in production.
Essential NixOS Commands for osModa
# Edit system configuration nano /etc/nixos/configuration.nix # Apply configuration changes (creates new generation) nixos-rebuild switch # Roll back to previous generation nixos-rebuild switch --rollback # List all generations nixos-rebuild list-generations # Test a configuration without switching (dry run) nixos-rebuild test # Build but do not switch (verify it builds) nixos-rebuild build # Update Nix packages channel nix-channel --update # Temporarily use a package (without installing) nix-shell -p htop ripgrep fd # Search for packages nix-env -qaP | grep python # Garbage collect old generations (free disk space) nix-collect-garbage -d # Check system disk usage df -h /nix/store
Frequently Asked Questions
Is NixOS harder to use than Ubuntu?
It is different, not harder. The main adjustment is learning to declare system state in configuration.nix instead of running imperative commands like apt install. Once you internalize the declarative model, NixOS is actually simpler — there is one file that defines your entire system, and it always produces the same result.
Can I use apt or apt-get on NixOS?
No. NixOS does not use apt, yum, or other imperative package managers. Packages are added by editing /etc/nixos/configuration.nix and running nixos-rebuild switch. You can temporarily test packages with nix-shell -p <package> without installing them permanently.
What happens if I break my NixOS configuration?
Every nixos-rebuild switch creates a new generation while preserving the previous one. If the new configuration breaks something, run nixos-rebuild switch --rollback to instantly revert to the previous working state. You can also select a previous generation from the boot menu. This is the SafeSwitch atomic deployment model.
How do I find the right Nix package name?
Search at search.nixos.org/packages or run nix-env -qaP | grep <name> from the command line. Package names in Nix sometimes differ from Debian/Ubuntu names — for example, python3 is python312, and nodejs is nodejs_22.
Can I install Docker on NixOS?
Yes. Add virtualisation.docker.enable = true to your NixOS configuration. Docker runs natively on NixOS. However, for most AI agent workloads on osModa, Docker is unnecessary — NixOS provides stronger reproducibility than Docker at the OS level, and osmoda-watch handles process supervision better than container restarts.
Do I need to learn Nix to use osModa?
No. osModa servers come pre-configured. You can SSH in, install packages with nix-env for quick testing, and run your agent as a systemd service without touching the Nix configuration. But learning the basics of declarative configuration (this guide) gives you reproducible deployments and atomic rollback — worth the 30-minute investment.
NixOS, Pre-Configured and Ready
osModa servers come with NixOS installed, configured, and running. All 9 Rust daemons, SafeSwitch deployment, and the audit ledger are ready on day one. From $14.99/month.
Explore More Guides