devenv image: adopt devenv 2.x and revisit size, startup, and generation

[mogul]

Context

Follow-up from GSA-TTS/agentic-coding-quickstart#474's review of the agent-kits-on-devenv ADR. This issue is scoped to the generic devenv image in integrations/isolation/images/devenv/ (added in GSA-TTS/agentic-coding-patterns#395).

It deliberately does not cover making acq depend more directly on devenv, or collapsing the image variant matrix — those are part of the broader ADR discussion. This issue is about improving how the image is generated and used.

Current state

• Dockerfile pins NIXPKGS_REV=ac62194c3917d5f474c1a844b6fd6da2db95077d (nixos-25.05) and installer 0.27.0; VERSION is 1.0.0.
• That pin resolves to devenv 1.11.2. devenv 2.x is present in neither nixos-25.05 nor nixos-25.11; it first appears in nixos-26.05 (2.1.2) and nixpkgs-unstable (2.2 / 2.3).

Improvements

1. Toolchain currency. Move NIXPKGS_REV to nixos-26.05 or nixpkgs-unstable, record the devenv major as part of the image contract, and bump VERSION with the change. Verify the image's single-user Nix (from installer 0.27.0) against devenv 2.x, which bundles its own Nix fork (the release-26.05 devenv package pins devenvNixVersion = "2.34").

2. Size and startup. Newer nixpkgs brings the ELF-note loader cache, and the devenv closure shrank from 528 MB to 376 MB with a bundled Nix 2.35.2. Measure the image before/after and consider a statically linked devenv (~16 ms startup, ~82 MB) only if startup cost is a measured problem. Adopt devenv 2.3's max_closure_size test limit to keep a budget enforced in CI.

3. Generation model (optional). Evaluate single-sourcing the toolchain through a declarative devenv.nix and deriving the image with devenv container build shell (subcommand form; copyToRoot, startupCommand, config.container.isBuilding). Caveats to validate: it needs nix2container and mk-shell-bin inputs, a Linux builder when run on macOS, and it starts the environment rather than producing a sandbox base (the agent user, no-init, writable prefix) — so treat it as an addition, not a drop-in replacement.

4. Persistence docs. Document that .devenv holds the evaluation cache and detached process-manager state and should be backed by a kit-declared volume for repeat commands and devenv up -d. Note devenv 2.2's SQLite-cache-on-virtiofs fix, which applies to msb/sbx mounts.

5. Devenv 2.x behavior notes for consumers. Activation keys on devenv.nix (not devenv.yaml); devenv init no longer writes .envrc by default; devenv build emits JSON; the git-hooks input is no longer included by default; pre-commit is now prek; devenv container --copy became devenv container copy. No existing kit uses devenv, so this is documentation only.

6. Keep as-is. The no-baked-proxy-CA default, the checksum-pinned Nix installer, the immutable version tags, and the multi-arch (amd64 + arm64) manifest.

Out of scope

• Any change to how acq depends on devenv.
• Removing or collapsing the devenv-opencode variant (that decision belongs to the ADR discussion).

Verification

• Rebuild and smoke-test: devenv --version reports the intended major, direnv is present, a non-interactive bash -c 'devenv version' works, and the agent user contract is unchanged.
• make validate, and a CI devenv-image.yml run that publishes a new immutable VERSION.

Refs

• GSA-TTS/agentic-coding-quickstart#474 — ADR review this follows from
• GSA-TTS/agentic-coding-patterns#395 — the image this covers

[mogul]

@basiliskus are you willing to take this on? I'd push through with it myself, but I am wary of disrupting your team's workflow, since you're the only existing consumer so far.

[mogul]

(Note the announcement blog post's 2.x migration guidance.)

[basiliskus]

@basiliskus are you willing to take this on? I'd push through with it myself, but I am wary of disrupting your team's workflow, since you're the only existing consumer so far.

Right, the problem is that we're stuck ATM with devenv 1.x because of a limitation with our gitlab pipeline. As long as we're versioning the image and acq maintains backwards compatibility, it should be ok. I can take it to make sure it works with our setup