Devenv2 Environment Generator

devenv Environment Generator (2.x)

Generate production-quality devenv 2.x environments from structured project requirements. Detailed configuration lives in references/ — load only the files the request actually needs (see Reference Routing).

Requirement Intake

Extract or confirm the following before generating any files. Ask for missing required fields — do not infer or default silently.

Reference Routing

Load reference files at intake time, keyed on which intake fields were filled. Never load all of them — each is a standalone 130–300 line document and only the routed ones are relevant to a given request.

Output Files

devenv.nix        # MANDATORY — every project gets one, even a near-empty one.
                  # Since 2.2 auto-activation (shell hook + `devenv allow`) keys on
                  # devenv.nix; a devenv.yaml-only project silently stops activating.
devenv.yaml       # When inputs, imports, secretspec config, require_version,
                  # shell, or nixpkgs config are needed
secretspec.toml   # When any secrets are declared
.gitignore        # Must contain .devenv/ and .direnv/

.envrc is opt-in only: devenv init --include-envrc (or DEVENV_INCLUDE_ENVRC=1). Do not hand-write one unless the user asks for direnv.

devenv.nix — Canonical Skeleton

{ pkgs, config, lib, inputs, ... }:

{
  packages = with pkgs; [ ];

  languages.<lang>.enable = true;

  services.<name>.enable = true;

  processes.<name> = {
    exec = "...";
    ports.<port-name>.allocate = 8080;
    after = [ "devenv:processes:<name>" ];
    ready.http.get = { port = config.processes.<name>.ports.<port-name>.value; path = "/healthz"; };
    restart.on = "on_failure";        # "never" | "always" | "on_failure"
    restart.max = 5;                  # null for unlimited
    watch.paths = [ ./src ];
    watch.extensions = [ "rs" ];
  };

  tasks."<namespace>:<name>" = {
    exec = "...";
    before = [ "devenv:enterShell" ];
    after = [ "devenv:processes:<name>" ];
    status = "check-if-needed";       # exit 0 = skip
    execIfModified = [ "src/**" ];
  };

  scripts.<name> = {
    exec = ''...'';
    packages = [ pkgs.curl ];
    description = "Help text";
  };

  env = { KEY = "value"; };           # non-secret values only

  git-hooks.hooks.<name>.enable = true;   # requires git-hooks input in devenv.yaml

  enterShell = ''echo "ready"'';
}

Breaking Changes from devenv 0.x / 1.x / 2.0

Migration guide: https://devenv.sh/guides/migrating-to-2.0/ 2.2 release notes: https://devenv.sh/blog/2026/07/28/devenv-22-attach-to-running-processes-and-persistent-out-of-tree-environments/

Validation Checklist

Run before finalizing output:

• Every example and generated project includes a devenv.nix
• Every process that binds a port uses ports.<port-name>.allocate — no hardcoded strings
• Service and process ports are wired through config.processes.<name>.ports.<port-name>.value, never a literal port in a URL or flag
• Secrets are in secretspec.toml, not in env = {}
• secretspec.enable: true is set in devenv.yaml wherever a secretspec.toml ships
• Every devenv.yaml key is snake_case
• devenv.yaml declares the git-hooks input if git-hooks.hooks is used
• Process dependencies use devenv:processes:<name> with optional @started, @ready, @completed suffix
• One-shot migration/seed processes use @completed dependency ordering
• Language versions are pinned where reproducibility matters
• devenv.yaml present if inputs, imports, secretspec config, shell, nixpkgs config, or require_version are needed
• .gitignore includes .devenv/ and .direnv/
• languages.<lang>.lsp.enable is only touched to opt out — it defaults to true
• restart uses submodule syntax: restart.on, not a plain string
• watch uses submodule syntax: watch.paths, not a plain list
• Tasks that should run before shell entry use before = [ "devenv:enterShell" ]

Agent Workflow

1. Intake — Extract requirement fields. Ask for missing required fields.
2. Load references — Route the filled intake fields through the table above; read only those files.
3. Map — Translate requirements to devenv 2.x constructs.
4. Draft — Generate devenv.nix, plus devenv.yaml, secretspec.toml, .gitignore as applicable.
5. Validate — Run the checklist above. Fix violations before output.
6. Annotate — Add inline comments explaining non-obvious choices.
7. Summarize — Provide activation commands:

devenv shell                  # Enter environment (bash, zsh, fish, nu)
devenv up                     # Start all services and processes in the foreground
devenv up -d                  # Start them in the background; a later `devenv up`
                              # attaches to that manager instead of starting a second one
devenv processes attach       # Stream status and logs, leaving processes running on Ctrl-C
devenv down                   # Stop background processes
devenv test                   # Run the test suite
devenv processes list         # List processes and their running state
devenv processes logs <name>  # View process logs
devenv tasks list             # Show the task dependency tree

For auto-activation without direnv:

# bash and zsh need this in the shell rc file; fish and nushell auto-load it
# when devenv is installed via Nix:
eval "$(devenv hook bash)"    # bash
eval "$(devenv hook zsh)"     # zsh

# Then trust the project (from the directory containing devenv.nix):
devenv allow

AI Agent Integration

devenv detects coding agents and drops the TUI so output stays token-cheap; opt out with DEVENV_NO_AI_AGENT=1, or force interactive output with --tui true. Environment-level Claude Code config (claude.code.hooks, .agents, .commands, .mcpServers) is covered in references/ai-integration.md.

MCP Integration

devenv mcp serves package and option search over stdio, or devenv mcp --http 8080 over HTTP; a public instance runs at mcp.devenv.sh. See references/ai-integration.md for wiring it into an agent.