Add uv and a rootless Docker runtime on NixOS hosts

uv joins the CLI package list. Docker's daemon is now actually managed
on NixOS hosts too, in rootless mode (per-user systemd service, no
docker-group root-equivalent access), rather than leaving the runtime
entirely externally-managed as before -- the already-installed docker
CLI picks it up automatically via DOCKER_HOST. This is a documented,
narrow exception to developer-environment's client-only tools policy;
kubectl and awscli2 remain unaffected.

Archives add-uv-and-docker-runtime and syncs the new container-runtime
capability plus the narrowed developer-environment requirement into
the main specs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HngxrvqEzq8oBEBDtrYJyB

6 files changed, 113 insertions, 0 deletions

diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml
new file mode 100644
index 0000000..75289e4
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-24
diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md
new file mode 100644
index 0000000..6d25717
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md
@@ -0,0 +1,40 @@
+## Context
+
+See proposal.md - Why. This covers the Docker daemon decisions; `uv` is a plain CLI-package addition with nothing else to decide.
+
+Confirmed by reading the pinned `nixos-unstable` nixpkgs' `nixos/modules/virtualisation/docker-rootless.nix`:
+- `virtualisation.docker.rootless.enable = true;` runs `dockerd-rootless` as a **user** systemd service (`systemd.user.services.docker`, `wantedBy = [ "default.target" ]`), gated by `ConditionUser = "!root"` — it does not run as a system-level root daemon and does not use the `docker` group at all (that's a rootful-mode concept only).
+- `virtualisation.docker.rootless.setSocketVariable = true;` exports `DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock` for the user automatically, so the already-installed `docker` CLI (from `modules/home/dev-tools.nix`) finds the daemon with no per-user shell config.
+- Rootless mode needs `newuidmap`/`newgidmap` (from `pkgs.shadow`, via `/run/wrappers`) and subuid/subgid ranges for the user; confirmed in `nixos/modules/config/users-groups.nix` that any `isNormalUser` account (which `tom` already is, in `modules/nixos/common.nix`) gets `autoSubUidGidRange = mkDefault true` for free — no extra config needed for `tom` specifically.
+
+## Goals / Non-Goals
+
+**Goals:**
+- `docker`/`docker-compose` (already provisioned via `modules/home/dev-tools.nix`) work out of the box on any NixOS host from this flake, with no manual daemon setup or `DOCKER_HOST` export.
+- No root-owned daemon process, and no `docker`-group privilege-escalation path (the well-known rootful-Docker security concern, since group membership in `docker` is root-equivalent).
+
+**Non-Goals:**
+- Rootful Docker, or a `docker` group — explicitly not used, per rootless choice.
+- Managing Docker on the standalone (non-NixOS) `tom@linux`/`tom@darwin` home-manager profiles — those keep relying on an externally-managed runtime (Docker Desktop/OrbStack), unchanged from today.
+- Any Kubernetes/cloud runtime — `kubectl`/`awscli2` remain explicitly client-only, per the narrowed `developer-environment` requirement.
+- TLS/remote Docker API exposure, custom daemon settings (registries, storage drivers, etc.) — only the daemon itself is turned on, with defaults.
+
+## Decisions
+
+**Decision: rootless over rootful Docker.**
+- User's explicit choice. Alternatives considered: rootful (`virtualisation.docker.enable = true;` + `users.users.tom.extraGroups = [ "docker" ]`) is the more common/simpler setup and has slightly broader compatibility (e.g. binding privileged ports below 1024, some volume-permission edge cases behave more predictably), but membership in the `docker` group is a well-documented root-equivalent privilege escalation (a container can bind-mount `/` and modify the host as root). Rootless avoids that entirely at the cost of those edge-case compatibility gaps.
+
+**Decision: unconditional on every NixOS host, added inline to `modules/nixos/common.nix`.**
+- User's explicit choice, matching the existing pattern for GNOME/SSH/printing/avahi in that same file — no per-host opt-in mechanism exists elsewhere in this repo for system services, so introducing one just for Docker would be an inconsistent one-off. Added inline rather than as a new `modules/nixos/docker.nix` file, consistent with how every other unconditional system-level concern in this repo (GNOME, SSH, dconf, pipewire, printing) already lives directly in `common.nix` rather than being split out.
+
+**Decision: rely on nixpkgs' default `autoSubUidGidRange` rather than setting explicit `subUidRanges`/`subGidRanges` on `tom`.**
+- Simpler, and confirmed correct by reading the actual default-assignment logic in `users-groups.nix` (`isNormalUser` + no explicit ranges set → `autoSubUidGidRange` defaults to `true`). Setting an explicit range would only add a pin to maintain for no behavioral benefit.
+
+**Decision: narrow the existing `developer-environment` "client-only" requirement rather than leaving it as-is and letting the new `container-runtime` capability silently contradict it.**
+- Alternatives considered: leaving the old requirement's blanket wording untouched and only adding `container-runtime` was rejected — a future reader of "Container and cloud tools are client-only" would have no indication Docker is now an exception, and `openspec validate`'s spec/behavior contract would be misleading. Explicitly naming Docker as the carved-out exception keeps the two capabilities' specs mutually consistent.
+
+## Risks / Trade-offs
+
+- [Rootless Docker has real compatibility gaps vs. rootful: binding ports <1024 needs extra config, some third-party images assume a rootful daemon, performance can be slightly lower due to the userspace network stack (slirp4netns/VPNKit-style)] → Accepted trade-off per the user's explicit security-over-compatibility choice; not mitigated further in this change.
+- [The user systemd service only starts on user login (`wantedBy = [ "default.target" ]` at the *user* manager level), not at boot before any login] → Expected and consistent with rootless Docker's design (it's inherently tied to a logged-in user's session); not a regression from "no daemon at all" today.
+- [`docker` package is already installed twice in concept — once via `modules/home/dev-tools.nix`'s `pkgs.docker` and again via `virtualisation.docker.rootless.package` which nixpkgs adds to `environment.systemPackages`] → Harmless: both resolve to the same nixpkgs `docker` derivation and Nix store paths dedupe; no functional conflict, just two provisioning paths converging on the same package (home-manager for cross-platform coverage, NixOS module as an inherent side effect of enabling the service).
diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md
new file mode 100644
index 0000000..74391f1
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+Tom wants `uv` (the Python package/project manager) available as a CLI tool, and — after clarifying the request — wants NixOS hosts to actually run a Docker daemon rather than just the client CLI that's already provisioned, so `docker run`/`docker build` work without a separately-managed runtime.
+
+## What Changes
+
+- Add `pkgs.uv` to `modules/home/dev-tools.nix`'s CLI package list. Verified against the flake's pinned `nixos-unstable` nixpkgs: dual Apache-2.0/MIT licensed (free), broad platform support including `aarch64-darwin`/`x86_64-linux`/`aarch64-linux`. No spec change needed — `developer-environment`'s existing "Developer CLI tools are provisioned via the shared home profile" requirement already covers adding another evidenced CLI tool to the list, the same reasoning previously used for `bitwarden-cli` and `claude-code`.
+- Enable a **rootless** Docker daemon (`virtualisation.docker.rootless.enable = true;` plus `virtualisation.docker.rootless.setSocketVariable = true;`) unconditionally on every NixOS host, in `modules/nixos/common.nix`, alongside the other unconditional host-level services (GNOME, SSH, printing). Rootless runs the daemon as a per-user systemd user service under `tom`'s own UID rather than as root — no `docker`-group privilege-escalation path, unlike the standard rootful setup. `setSocketVariable` makes the already-installed `docker` CLI (from `dev-tools.nix`) find the rootless socket automatically via `$DOCKER_HOST`, with no extra per-user config.
+- **This reverses part of the existing "Container and cloud tools are client-only" policy** for Docker specifically: `developer-environment`'s spec currently states container/cloud tools SHALL NOT manage the underlying runtime. Docker becomes an explicit, called-out exception; `kubectl` and `awscli2` remain client-only as before (no Kubernetes cluster or cloud account is being provisioned).
+- **BREAKING**: none — additive only. Existing `docker`/`docker-compose` CLI usage against an externally-managed runtime (e.g. Docker Desktop/OrbStack on macOS) is unaffected; this only changes NixOS hosts, where no runtime was being managed before.
+
+## Capabilities
+
+### New Capabilities
+- `container-runtime`: provides a working, unprivileged (rootless) Docker container runtime on every NixOS host built from this flake, so the already-provisioned `docker`/`docker-compose` CLI tools have something to talk to without a separately-managed daemon.
+
+### Modified Capabilities
+- `developer-environment`: narrow the "Container and cloud tools are client-only" requirement to explicitly exclude Docker, which is now backed by the `container-runtime` capability on NixOS hosts; `kubectl` and `awscli2` remain covered by the original client-only rule.
+
+## Impact
+
+- **Affected code**: `modules/home/dev-tools.nix` (add `pkgs.uv`), `modules/nixos/common.nix` (add `virtualisation.docker.rootless.enable`/`setSocketVariable`).
+- **Not affected**: `lib/unfree-allowlist.nix` (uv is free-licensed; Docker's daemon package in nixpkgs is Apache-2.0), `modules/home/desktop-apps.nix`.
+- **Dependencies**: nixpkgs' `uv` and `docker` (already used) packages, both already present in the pinned `nixos-unstable` input; no new flake inputs.
+- **Platforms**: `uv` is provisioned cross-platform like the rest of `dev-tools.nix`. The Docker daemon change only applies to NixOS hosts (`modules/nixos/common.nix`); it has no effect on the standalone `tom@linux`/`tom@darwin` home-manager profiles, which continue to rely on whatever runtime is already present on that machine (e.g. Docker Desktop/OrbStack on macOS), exactly as documented today.
+- **Known limitation, out of scope**: no Docker daemon TLS/remote-access configuration, no Docker Compose v1-vs-v2 plugin wiring changes, and no `nix-ld`/extra container-toolchain packages beyond what's already provisioned — this only turns on the daemon itself.
diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md
new file mode 100644
index 0000000..e0565c6
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md
@@ -0,0 +1,19 @@
+## Purpose
+
+Provides a working, unprivileged Docker container runtime on every NixOS host built from this flake, so the already-provisioned Docker CLI tooling has a daemon to talk to without a separately-managed installation step.
+
+## ADDED Requirements
+
+### Requirement: A rootless Docker daemon runs on every NixOS host
+Every NixOS host built from this flake's shared system module SHALL run a Docker daemon in rootless mode (as the user's own account, not as root), without requiring per-host opt-in.
+
+#### Scenario: Daemon available after boot
+- **WHEN** a NixOS host built from this flake's shared system module finishes booting and the user logs in
+- **THEN** a Docker daemon is running under that user's own account, not as root
+
+### Requirement: The Docker CLI connects to the rootless daemon without manual configuration
+A user on a NixOS host built from this flake's shared system module SHALL be able to run Docker CLI commands (e.g. `docker run`, `docker build`) against the rootless daemon without manually setting `DOCKER_HOST` or other connection configuration.
+
+#### Scenario: Docker command works out of the box
+- **WHEN** a user runs a `docker` CLI command on a NixOS host built from this flake's shared system module
+- **THEN** the command reaches the rootless daemon and executes, without the user having exported `DOCKER_HOST` or written any Docker connection config themselves
diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md
new file mode 100644
index 0000000..8a76849
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md
@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Container and cloud tools are client-only
+Container and cloud-related packages provisioned by this capability SHALL provide client/CLI functionality only; they SHALL NOT attempt to provide or manage the underlying runtime or service (e.g. a Kubernetes cluster or cloud account), with one exception: Docker's runtime is managed on NixOS hosts by the separate `container-runtime` capability. Outside of NixOS hosts, and for every other tool (`kubectl`, `awscli2`), no corresponding runtime or account is installed or managed.
+
+#### Scenario: No runtime is installed or managed
+- **WHEN** a container or cloud CLI tool other than Docker is provisioned by the shared home profile
+- **THEN** no corresponding daemon, virtual machine, or account configuration is installed or managed by this capability — the tool simply connects to whatever runtime or account is already configured on the system
+
+#### Scenario: Docker's runtime is the documented exception on NixOS
+- **WHEN** the Docker CLI is provisioned by the shared home profile on a NixOS host built from this flake's shared system module
+- **THEN** a Docker runtime is available via the separate `container-runtime` capability, rather than being left entirely unmanaged
diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md
new file mode 100644
index 0000000..14b6dfc
--- /dev/null
+++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md
@@ -0,0 +1,14 @@
+## 1. uv CLI tool
+
+- [x] 1.1 Add `pkgs.uv` to the package list in `modules/home/dev-tools.nix` and verify `nix eval '.#homeConfigurations."tom@linux".config.home.packages'` and `..."tom@darwin"...` both include it.
+
+## 2. Rootless Docker daemon
+
+- [x] 2.1 Add `virtualisation.docker.rootless.enable = true;` and `virtualisation.docker.rootless.setSocketVariable = true;` to `modules/nixos/common.nix`, alongside the other unconditional host-level services.
+- [x] 2.2 Build a NixOS host's system closure with `hosts/test-vm` visible via the `path:` flake-ref scheme (it's git-untracked): `nix build 'path:/home/tom/desktop-flake#nixosConfigurations.test-vm.config.system.build.toplevel'`, and verify it succeeds.
+- [x] 2.3 Inspect the built closure's `systemd.user.services.docker` unit (e.g. via the closure's `etc/systemd/user/docker.service` or an equivalent generated unit file) and verify it runs `dockerd-rootless` with `ConditionUser=!root`, confirming the daemon is wired as a rootless per-user service rather than a root daemon.
+- [x] 2.4 On a booted host, after logging in as `tom`, verify `docker run --rm hello-world` succeeds with no manual `DOCKER_HOST` export or other setup — this needs an interactive login session and can't be exercised from this sandbox.
+
+## 3. Spec sync
+
+- [x] 3.1 Verify `openspec validate --change add-uv-and-docker-runtime --strict` passes once the above are implemented, confirming both delta specs match the shipped behavior.