Problem Addressed

devenv

Research Date: 2026-02-26 Source URL: https://devenv.sh GitHub Repository: https://github.com/cachix/devenv Version at Research: v1.11.2 License: Apache-2.0

Overview

devenv is a declarative developer environment tool built on Nix that enables teams to define fast, reproducible, and composable development environments in a single devenv.nix configuration file. It provides 100,000+ prebuilt packages, built-in process management, task automation, and service orchestration that activate in under 100ms through Nix evaluation caching. The tool targets the "works on my machine" problem by encoding the entire toolchain — languages, services, git hooks, and environment variables — as version-pinned, reproducible declarations.

Problem Addressed

Key Statistics

SOURCE: GitHub API repos/cachix/devenv (accessed 2026-02-26)

Key Features

Declarative Environment Configuration

• devenv.nix is the single source of truth for packages, languages, services, processes, tasks, git hooks, and environment variables
• devenv.yaml defines input sources (nixpkgs revision, custom flake inputs) and composes imports from sub-directories
• devenv.lock pins all inputs to exact revisions for reproducible builds
• Profile-based activation allows hostname/username-based environment variants within one configuration

Language Support (50+ languages)

• Per-language modules with version management: Python (via venv/conda/uv), Rust (toolchain pinning), Go, Ruby, PHP, Terraform, JavaScript/Node.js, Java, Haskell, and 40+ others
• LSP servers, formatters, linters, and compilers enabled declaratively per language
• Python example: languages.python.enable = true; languages.python.version = "3.12.0";

Service Orchestration

• 30+ built-in service modules: PostgreSQL, Redis, MySQL, MongoDB, Kafka, RabbitMQ, Elasticsearch, Memcached, MinIO, and more
• Services run natively in the development environment without requiring Docker or container runtimes
• Each service module exposes typed configuration options (port, data directory, authentication settings)

Process Management

• Default built-in process manager supports supervision, socket activation, file watching, and dependency ordering
• Alternative process manager backends: process-compose (TUI), hivemind, honcho, overmind, mprocs — switchable via process.manager.implementation
• Restart policies: on_failure (default), always, never
• Ready probes: exec commands, HTTP endpoint polling, systemd-style READY=1 notify probes
• Process dependencies declared with after/before and temporal suffixes @started, @ready, @completed

Task Automation System

• Tasks defined in devenv.nix with exec, status (skip-if-zero-exit), execIfModified (file hash tracking), and package attributes
• Parallel execution with automatic dependency resolution between named tasks
• Inter-task data flow via $DEVENV_TASK_INPUT, $DEVENV_TASKS_OUTPUTS, $DEVENV_TASK_OUTPUT_FILE environment variables
• Processes become tasks automatically under the devenv:processes: namespace
• Supports any language for task execution via the package attribute

Git Hooks Integration

• git-hooks.hooks module enables pre-commit, commit-msg, and other hook types
• Language-specific linters (black, isort, rustfmt, golangci-lint, eslint) activated per-project
• Uses the upstream pre-commit framework's hook registry under the hood

Composability and Imports

• devenv.yaml imports support local relative paths for monorepo subdirectory composition
• At the root, all imported configurations merge so devenv up starts unified process set
• Per-subdirectory activation: entering frontend/ activates only that component's environment
• Remote imports not yet supported in devenv.yaml (as of v1.10)

Container and Codespace Support

• devcontainer.enable = true generates .devcontainer.json from the same Nix configuration
• Generated devcontainer compatible with GitHub Codespaces and VS Code Dev Containers
• Container/OCI image building from development environment configuration

Secrets Management

• SecretSpec integration (secretspec v0.4.1+ as of v1.11.2) for declarative secrets management
• Secrets injected into environment without hardcoding in version-controlled configuration files

Technical Architecture

devenv is implemented in Rust for the CLI binary, with the module system written in Nix. The evaluation pipeline works as follows:

Key architectural decisions:

• Nix module system: All configuration options are typed Nix modules — invalid configurations fail at evaluation time with descriptive errors rather than runtime
• Binary cache: Cachix (the same organization) provides a public binary cache (cachix.cachix.org) so common packages download as pre-built binaries rather than compiling from source
• direnv integration: .envrc generated by devenv init calls use devenv, enabling automatic shell activation when entering the project directory
• Flakes compatibility: devenv supports both classic Nix (via nixpkgs.tarball) and Nix Flakes for teams already on flakes-based workflows

Installation & Usage

# Step 1: Install Nix (Linux/macOS daemon mode)
sh <(curl -L https://nixos.org/nix/install) --daemon

# Step 2: Install devenv via nixpkgs unstable
nix-env --install --attr devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

# Or via nix profile
nix profile install nixpkgs#devenv

# Step 3 (optional): Add GitHub token to avoid API rate limits
echo "access-tokens = github.com=<GITHUB_TOKEN>" >> ~/.config/nix/nix.conf

# Initialize a new project
devenv init
# Creates: .envrc, devenv.nix, devenv.yaml, .gitignore

# Activate environment (manual)
devenv shell

# Start all configured processes
devenv up

# Run tasks
devenv tasks run myapp:build

# Update pinned inputs
devenv update

# Run environment tests (for CI)
devenv test

# Build container image
devenv container build

# devenv.nix — example configuration
{ pkgs, lib, config, ... }:

{
  # Packages available in the shell
  packages = [ pkgs.git pkgs.jq ];

  # Language runtimes
  languages.python = {
    enable = true;
    version = "3.12.0";
    venv.enable = true;
    venv.requirements = ./requirements.txt;
  };

  languages.rust = {
    enable = true;
    channel = "stable";
  };

  # Local services (no Docker needed)
  services.postgres = {
    enable = true;
    port = 5432;
    initialDatabases = [{ name = "myapp"; }];
  };

  services.redis = {
    enable = true;
    port = 6379;
  };

  # Processes
  processes = {
    web.exec = "python manage.py runserver";
    worker.exec = "celery -A myapp worker";
  };

  # Tasks
  tasks = {
    "myapp:migrate" = {
      exec = "python manage.py migrate";
      execIfModified = [ "migrations/**/*.py" ];
    };
  };

  # Git hooks
  git-hooks.hooks = {
    black.enable = true;
    ruff.enable = true;
    rustfmt.enable = true;
  };

  # Environment variables
  env.DATABASE_URL = "postgresql://localhost:5432/myapp";

  # DevContainer support
  devcontainer.enable = true;
}

# devenv.yaml — input composition
inputs:
  nixpkgs:
    url: github:NixOS/nixpkgs/nixpkgs-unstable

imports:
  - ./frontend
  - ./backend

Relevance to Claude Code Development

Applications

• Reproducible skill development environments: Each skill plugin that depends on specific Python versions, linting tools (prek, pre-commit), or CLI tools (gh, uv) could be declared in a devenv.nix at the repository root, eliminating onboarding friction
• Consistent pre-commit hook enforcement: The git-hooks module directly replaces manual .pre-commit-config.yaml management by declaring hooks as typed Nix options with automatic installation
• Local service mocking for tests: Skills that test against databases or message queues could use devenv's service modules to spin up local PostgreSQL/Redis instances without Docker, matching CI environments
• Task automation parity with CI: The task system with execIfModified and status caching mirrors the conditional execution patterns needed for efficient CI/CD in skill validation pipelines

Patterns Worth Adopting

• Typed configuration with fail-fast validation: devenv's Nix module system rejects invalid option combinations at evaluation time rather than at runtime — a pattern applicable to skill frontmatter validation
• execIfModified content-hash tracking: Skipping expensive operations when inputs have not changed (by hash, not just timestamp) is directly applicable to the validate_research.py freshness checks
• Namespace-prefixed task composition: The namespace:taskname convention for task grouping provides a clear model for organizing the research curator's multi-step workflows
• Inter-task data flow via environment variables: $DEVENV_TASK_INPUT / $DEVENV_TASK_OUTPUT_FILE provides a simple, shell-agnostic IPC pattern for agent pipelines

Integration Opportunities

• devenv.nix at repository root: Adding devenv.nix to claude_skills would provide a single-command environment setup (devenv shell) with all required tools (uv, gh, prek, node) pinned to exact versions
• Replace manual pre-commit setup: Current uv run prek install step in CLAUDE.md session start could be absorbed into devenv's git-hooks module, auto-installing hooks on devenv shell entry
• Process management for local agent testing: Multi-agent skill tests that require concurrent processes (orchestrator + worker agents) could be declared as devenv processes with proper dependency ordering

References

• devenv official website (accessed 2026-02-26)
• devenv Getting Started (accessed 2026-02-26)
• devenv Processes documentation (accessed 2026-02-26)
• devenv Tasks documentation (accessed 2026-02-26)
• devenv Composing using imports (accessed 2026-02-26)
• devenv Codespaces/DevContainer integration (accessed 2026-02-26)
• GitHub repository cachix/devenv (accessed 2026-02-26)
• GitHub API release v1.11.2 (accessed 2026-02-26)

Freshness Tracking