TRANSITION CONTEXT

Note (2026-07-16): the project has been renamed claude-box → agent-box (issue 70): services.agent-box, modules/agent-box.nix, agent-box-* units. This page documents the July 2026 transition of the original box and deliberately keeps the pre-rename names and pinned revs it used at the time.

claude-box transition — continuity context

Saved before the nixos-rebuild switch that migrates this live box onto the claude-box module. Reason it exists: the switch restarts the systemd unit the running Claude session lives in; its ExecStop kills the tmux session, so this session dies mid-transition. Resume from this file after reconnecting.

Goal

Replace the bespoke hand-written claude.service + user + sudo/polkit rules in /etc/nixos/configuration.nix with the published claude-box NixOS module, pinned to a commit — so our own box runs the reproducible template.

Pin

• Repo: https://github.com/defangdevs/claude-box
• rev: beb8d317a0ad0c61cbb90ec80f680eea51e5657d
• tarball sha256 (base32): 0nsi906jhs8l5ghfmk63s6f0v5wycdc373f7p95l3scdgm4hy93a

Edits to /etc/nixos/configuration.nix (user applies — file is defang:users 644, Claude cannot write it)

1. In imports, add the pinned module. Use fetchTarball, NOT fetchGit — root has no git binary during sudo nixos-rebuild switch, so fetchGit fails with "executing 'git': No such file or directory". fetchTarball needs no git.

   (let
     claude-box = builtins.fetchTarball {
       url = "https://github.com/defangdevs/claude-box/archive/beb8d317a0ad0c61cbb90ec80f680eea51e5657d.tar.gz";
       sha256 = "0nsi906jhs8l5ghfmk63s6f0v5wycdc373f7p95l3scdgm4hy93a";
     };
   in claude-box + "/modules/claude-box.nix")

2. Add the service config:

   services.claude-box = {
     enable = true;
     users.claude = {
       extraGroups = [ "caddy" ];
       environment = {
         TERM = "xterm-256color";
         XDG_RUNTIME_DIR = "/run/user/1004";
       };
       environmentFiles = [ "-/home/claude/.config/gh/token" ];
     };
     sudoAllowlist = [
       "/run/current-system/sw/bin/systemctl reload caddy.service"
       "/run/current-system/sw/bin/systemctl restart caddy.service"
     ];
     extraPackages = with pkgs; [ git ];
   };

3. REMOVE the now-superseded bespoke blocks:

   • users.users.claude = { ... } (was ~lines 127-138)
   • systemd.services.claude = { ... } (was ~lines 213-239)
   • polkit inhibit rule for claude (was ~lines 240-248) — dropped because sleep/suspend is already disabled globally (lines 32-35), so systemd-inhibit is no longer needed in the start command.
   • hand-written claude sudo rules (was ~lines 299-305) — replaced by sudoAllowlist.

4. KEEP: the linger tmpfiles rule "f /var/lib/systemd/linger/claude 0644 root root - -" (~lines 198-200) — keeps /run/user/1004 alive.

Session-drop warning

The old claude.service ExecStop is tmux -L claude kill-session -t claude. The switch kills THIS session. The new session uses a different socket/name.

Reconnect after switch

sudo -u claude tmux -L claude-box attach -t main

(new module uses socket -L claude-box, session main — not -L claude / claude.)

Rollback if broken

sudo nixos-rebuild switch --rollback

Status at save time

• Module + flake published; CI passing (green on master).
• Module parity gap closed: per-user environment option added (in the pinned rev).
• Not yet applied: the configuration.nix edits + switch above (needs user; needs root).

Open confirmations (non-blocking)

• LICENSE holder: currently "Copyright (c) 2026 Defang" — confirm vs "Lio Lunesu".
• Default branch is master; offered rename to main.
• Offered migration off deprecated nixos-generators (→ nixos-rebuild build-image).