# cachix/devenv architecture

> Architecture diagram of the GitHub repository cachix/devenv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cachix/devenv
- Repository: https://github.com/cachix/devenv

## Overview

devenv is a Rust CLI for defining and activating reproducible developer environments with Nix. The principal workflow starts with a project configuration, evaluates it into an environment, then activates that environment in a shell. The README also documents process and task management, live terminal UI, reloads, language-server support, containers, and integrations. Paths identify implementations where supported by the tree; some capability links are dashed because the relevant implementation was not sampled, so those connections are not verified.

Main entry points: [`devenv/src/main.rs`](https://github.com/cachix/devenv/blob/main/devenv/src/main.rs) (CLI), [`devenv-processes/src/manager.rs`](https://github.com/cachix/devenv/blob/main/devenv-processes/src/manager.rs) (Process manager), [`devenv-core/src/config.rs`](https://github.com/cachix/devenv/blob/main/devenv-core/src/config.rs) (Environment config), [`devenv-activity/src/events.rs`](https://github.com/cachix/devenv/blob/main/devenv-activity/src/events.rs) (Activity events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["CLI<br/>[main.rs]"]
  node_commands["Commands<br/>[mod.rs]"]
  node_config["Environment config<br/>[config.rs]"]
end

subgraph group_evaluation["Evaluation and Nix"]
  node_evaluator["Evaluator<br/>[evaluator.rs]"]
  node_nix["Nix backend<br/>[backend.rs]"]
  node_evalcache[("Eval cache")]
end

subgraph group_runtime["Environment runtime"]
  node_shell["Shell session<br/>[session.rs]"]
  node_processes["Process manager<br/>[manager.rs]"]
  node_tasks["Task runner<br/>[tasks.rs]"]
  node_probes["Readiness probes"]
end

subgraph group_experience["Developer experience"]
  node_activities["Activity events<br/>[events.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_reload["Shell reload"]
  node_lsp["Language server<br/>[lsp.rs]"]
end

subgraph group_integrations["Packaging and integrations"]
  node_container["OCI containers<br/>[container.rs]"]
  node_mcp["MCP server<br/>[mcp.rs]"]
  node_proxy["Development proxy<br/>[routes.rs]"]
  node_secrets["Secrets integration<br/>[settings.rs]"]
end

node_user(("Developer"))
node_external["Nix tooling"]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_commands
node_user -->|"defines"| node_config
node_cli -.->|"loads"| node_config
node_evaluator -.->|"evaluates with"| node_nix
node_evaluator -.->|"caches evaluation"| node_evalcache
node_nix -.->|"uses"| node_external
node_cli -->|"activates"| node_shell
node_cli -->|"starts processes"| node_processes
node_cli -->|"runs tasks"| node_tasks
node_processes -.->|"checks readiness"| node_probes
node_processes -.->|"reports events"| node_activities
node_tasks -.->|"reports events"| node_activities
node_activities -.->|"drives display"| node_tui
node_shell -->|"supports reload"| node_reload
node_cli -->|"starts"| node_lsp
node_cli -->|"builds or runs"| node_container
node_cli -->|"launches"| node_mcp
node_config -->|"configures"| node_secrets
node_processes -.->|"routes services"| node_proxy

click node_cli "https://github.com/cachix/devenv/blob/main/devenv/src/main.rs"
click node_commands "https://github.com/cachix/devenv/blob/main/devenv/src/commands/mod.rs"
click node_config "https://github.com/cachix/devenv/blob/main/devenv-core/src/config.rs"
click node_evaluator "https://github.com/cachix/devenv/blob/main/devenv-core/src/evaluator.rs"
click node_nix "https://github.com/cachix/devenv/blob/main/devenv-nix-backend/src/backend.rs"
click node_evalcache "https://github.com/cachix/devenv/tree/main/devenv-eval-cache/src"
click node_shell "https://github.com/cachix/devenv/blob/main/devenv-shell/src/session.rs"
click node_processes "https://github.com/cachix/devenv/blob/main/devenv-processes/src/manager.rs"
click node_tasks "https://github.com/cachix/devenv/blob/main/devenv-tasks/src/tasks.rs"
click node_probes "https://github.com/cachix/devenv/tree/main/devenv-event-sources/src"
click node_activities "https://github.com/cachix/devenv/blob/main/devenv-activity/src/events.rs"
click node_tui "https://github.com/cachix/devenv/blob/main/devenv-tui/src/app.rs"
click node_reload "https://github.com/cachix/devenv/tree/main/devenv-reload/src"
click node_lsp "https://github.com/cachix/devenv/blob/main/devenv/src/lsp.rs"
click node_container "https://github.com/cachix/devenv/blob/main/devenv/src/devenv/container.rs"
click node_mcp "https://github.com/cachix/devenv/blob/main/devenv/src/mcp.rs"
click node_proxy "https://github.com/cachix/devenv/blob/main/devenv-proxy/src/routes.rs"
click node_secrets "https://github.com/cachix/devenv/blob/main/devenv-core/src/settings.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_config toneBlue
class node_evaluator,node_nix,node_evalcache toneAmber
class node_shell,node_processes,node_tasks,node_probes toneMint
class node_activities,node_tui,node_reload,node_lsp toneRose
class node_container,node_mcp,node_proxy,node_secrets,node_user,node_external toneIndigo
```

## Components

### CLI and configuration

- [CLI](https://github.com/cachix/devenv/blob/main/devenv/src/main.rs): `devenv/src/main.rs`
- [Commands](https://github.com/cachix/devenv/blob/main/devenv/src/commands/mod.rs): `devenv/src/commands/mod.rs`
- [Environment config](https://github.com/cachix/devenv/blob/main/devenv-core/src/config.rs): `devenv-core/src/config.rs`

### Evaluation and Nix

- [Evaluator](https://github.com/cachix/devenv/blob/main/devenv-core/src/evaluator.rs): `devenv-core/src/evaluator.rs`
- [Nix backend](https://github.com/cachix/devenv/blob/main/devenv-nix-backend/src/backend.rs): `devenv-nix-backend/src/backend.rs`
- [Eval cache](https://github.com/cachix/devenv/tree/main/devenv-eval-cache/src): `devenv-eval-cache/src`

### Environment runtime

- [Shell session](https://github.com/cachix/devenv/blob/main/devenv-shell/src/session.rs): `devenv-shell/src/session.rs`
- [Process manager](https://github.com/cachix/devenv/blob/main/devenv-processes/src/manager.rs): `devenv-processes/src/manager.rs`
- [Task runner](https://github.com/cachix/devenv/blob/main/devenv-tasks/src/tasks.rs): `devenv-tasks/src/tasks.rs`
- [Readiness probes](https://github.com/cachix/devenv/tree/main/devenv-event-sources/src): `devenv-event-sources/src`

### Developer experience

- [Activity events](https://github.com/cachix/devenv/blob/main/devenv-activity/src/events.rs): `devenv-activity/src/events.rs`
- [Terminal UI](https://github.com/cachix/devenv/blob/main/devenv-tui/src/app.rs): `devenv-tui/src/app.rs`
- [Shell reload](https://github.com/cachix/devenv/tree/main/devenv-reload/src): `devenv-reload/src`
- [Language server](https://github.com/cachix/devenv/blob/main/devenv/src/lsp.rs): `devenv/src/lsp.rs`

### Packaging and integrations

- [OCI containers](https://github.com/cachix/devenv/blob/main/devenv/src/devenv/container.rs): `devenv/src/devenv/container.rs`
- [MCP server](https://github.com/cachix/devenv/blob/main/devenv/src/mcp.rs): `devenv/src/mcp.rs`
- [Development proxy](https://github.com/cachix/devenv/blob/main/devenv-proxy/src/routes.rs): `devenv-proxy/src/routes.rs`
- [Secrets integration](https://github.com/cachix/devenv/blob/main/devenv-core/src/settings.rs): `devenv-core/src/settings.rs`

### Other components

- **Developer**
- **Nix tooling**

## Connections

- Developer → CLI: runs
- CLI → Commands: dispatches (evidence: `devenv/src/main.rs`)
- Developer → Environment config: defines
- CLI → Environment config: loads
- Evaluator → Nix backend: evaluates with
- Evaluator → Eval cache: caches evaluation
- Nix backend → Nix tooling: uses
- CLI → Shell session: activates
- CLI → Process manager: starts processes
- CLI → Task runner: runs tasks
- Process manager → Readiness probes: checks readiness
- Process manager → Activity events: reports events
- Task runner → Activity events: reports events
- Activity events → Terminal UI: drives display
- Shell session → Shell reload: supports reload
- CLI → Language server: starts
- CLI → OCI containers: builds or runs
- CLI → MCP server: launches
- Environment config → Secrets integration: configures
- Process manager → Development proxy: routes services
