---
title: "Chapter 01: Nix on Your Mac"
description: "Separate reproducible dependencies from isolation, then install and verify Nix without replacing macOS."
type: "lesson"
order: 1
chapter: "01-reproducible-foundations"
duration: "45–90 minutes"
---

# Chapter 01: Nix on Your Mac

## Objective

Separate reproducible dependencies from isolation, then install and verify Nix without replacing macOS.

Your tutor should stop at each gate and wait for your evidence before continuing.

## Concept

Your first deliverable is a working package manager and an accurate boundary around what it guarantees. Nix can supply a compiler and its dependencies without replacing macOS. NixOS is a Linux distribution that also declares system configuration. devenv is a development-environment layer on Nix. You need the first and third now; the operating system comes in the final lab.

Geoffrey Huntley’s [Nix essay](https://ghuntley.com/nix/) motivates a shared dependency definition for people, CI, and agents. His [Ralph essay](https://ghuntley.com/ralph/) describes repeatedly invoking a coding agent. This course turns those ideas into small experiments with observable failures and stop conditions. It is an independent course, not an endorsement or a replica of his production setup.

| Layer | Controls | Does not establish |
|---|---|---|
| Nix input pin | Package source revisions and dependency graph | Identical model answers |
| devenv shell | Tools, environment variables, commands | Isolation from your home directory |
| Tests | Specific observable contracts | Complete product correctness |
| Disposable VM | Separate OS and bounded machine lifetime | Safety if powerful credentials are injected |

A Nix build sandbox constrains build processes. A command started in a development shell still runs with your user’s authority. Treat a coding agent as a program capable of executing anything its tools and credentials permit.

## Concept check

**Q1.** Can a process inside `devenv shell` normally read your SSH keys? Why?

**Q2.** Which component would you use to configure Linux systemd services?

<details>
<summary>Concept answer key — attempt first</summary>

## Answer key (concept)

**Q1.** Yes, unless separate OS or agent controls deny access. **Pass criteria:** distinguish a shell environment from an isolation boundary.

**Q2.** NixOS. **Pass criteria:** distinguish the distribution from Nix and devenv.

</details>

## Gate: Inspect before installing

On your Mac, run:

```bash
uname -sm
command -v nix || true
```

Apple Silicon normally reports `Darwin arm64`; an Intel Mac reports `Darwin x86_64`. If Nix is already installed, use that installation and inspect its version. Do not layer another installer over it.

## Gate: Install Nix

For a new macOS installation, the devenv installation guide currently recommends the Nix installer below. Download it first so you can review what will run:

```bash
curl -sSfL https://artifacts.nixos.org/nix-installer -o /tmp/nix-installer.sh
less /tmp/nix-installer.sh
sh /tmp/nix-installer.sh install
```

The installer changes system configuration and may request administrator authorization. Read its prompts. Reopen your terminal afterward. Keep its uninstall instructions; removing `/nix` manually is not an uninstall procedure.

For a clean Linux host with systemd, the upstream multi-user installer is:

```bash
curl -L https://nixos.org/nix/install -o /tmp/install-nix.sh
less /tmp/install-nix.sh
sh /tmp/install-nix.sh --daemon
```

These are alternative host-specific routes. Run only the route for the machine you are configuring. Containers and existing NixOS hosts require different bootstrap steps; NixOS already includes Nix.

## Gate: Verify it runs

```bash
nix --version
nix --extra-experimental-features 'nix-command flakes'   shell nixpkgs#hello --command hello
```

**Pass:** Nix prints its version, resolves a package, and `hello` prints a greeting. This first command uses a moving registry reference deliberately; Chapter 02 replaces moving project dependencies with a lock.

If you need flakes for later commands, merge `experimental-features = nix-command flakes` into `~/.config/nix/nix.conf`. Preserve any existing features and configuration. Do not overwrite an installer-managed system file just to add this line.

## Gate: Record the host

Write down OS, architecture, Nix version, and installer choice. Give your tutor the version output, never credentials. Explain what Nix can and cannot reproduce before proceeding.

## Known failure modes

- `nix: command not found`: reopen the shell and check the installer’s shell integration.
- Experimental feature error: enable `nix-command flakes`, or pass the explicit flags shown above.
- Download failure: distinguish DNS/proxy/certificate errors from Nix evaluation errors. Do not disable TLS checks.
- Existing installation conflict: stop and use that installer’s repair guidance.

## Check your understanding

**Q3.** Why is a successful `hello` not proof of Mac/Linux parity?

**Q4.** What must be recorded separately from your project’s dependency lock?

<details>
<summary>Answer key — attempt every question first</summary>

## Answer key

**Q3.** It verifies this host and one package only. **Pass criteria:** name OS/architecture and later platform tests.

**Q4.** Host, Nix/devenv versions and model/provider configuration. **Pass criteria:** identify an input outside the project package graph.

</details>

## References

- [devenv installation](https://devenv.sh/getting-started/)
- [Nix installation manual](https://nix.dev/manual/nix/stable/installation/installing-binary.html)

---

[← Part index](/nix-agent-lab/01-reproducible-foundations/) · [Next: Chapter 02 →](/nix-agent-lab/01-reproducible-foundations/02-lock-the-environment/)