# jetify-com/devbox architecture

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

- Interactive diagram: https://gitdiagram.com/jetify-com/devbox
- Repository: https://github.com/jetify-com/devbox

## Overview

1. **Overall shape**
   This repo is primarily a **Go-based CLI application** (`cmd/devbox`, `internal/*`) that manages reproducible development environments. It is supplemented by a **TypeScript VS Code extension** (`vscode-extension/`), a large set of **example environments** (`examples/`), and **black-box integration tests** (`testscripts/`).

2. **Primary entry point and command surface**
   The executable starts in `cmd/devbox/main.go` and is wired through `internal/boxcli/`. That layer owns the user-facing command tree (`devbox add`, `shell`, `run`, `init`, `install`, `update`, `services`, `plugin`, `pull/push`, etc.), global flags, and command middleware such as debug/telemetry hooks.

3. **Core domain layer**
   `internal/devbox/` contains the main environment-management logic: shell setup, package orchestration, lockfile handling, environment-variable composition, service startup, secrets, refresh/update flows, and profile manipulation. This is the subsystem that turns a declarative project definition into a usable runtime environment.

4. **Configuration and lockfile boundary**
   The project is centered on `devbox.json` and `devbox.lock` in user projects. Parsing and normalization live in `internal/devconfig/` and `internal/devconfig/configfile/`, with multi-format helpers in `internal/cuecfg/`. `internal/lock/` models the lockfile and resolution state, keeping the declarative project config separate from resolved, pinned package state.

5. **Nix as the execution backend**
   Devbox is “internally powered by nix”; that boundary is implemented in `internal/nix/` and `nix/`. These packages handle evaluation, building, installation, store/profile operations, searches, and flake-related behavior. In the architecture diagram, this is the main external runtime dependency that actually materializes packages and shells.

6. **Package abstraction and resolution**
   `internal/devpkg/` and `internal/devbox/packages.go` represent package definitions independent of a specific installation mechanism. This abstraction lets the CLI resolve packages, validate them, compute outputs, and translate them into Nix-backed installable units.

7. **Shell generation and environment bootstrap**
   `internal/shellgen/` and `internal/devbox/generate/` generate the artifacts that make Devbox usable in different contexts: shell rc files, flake files, Dockerfiles, devcontainer configs, and wrapper scripts. This is the conversion layer from “project definition” to “launchable environment.”

8. **Shell runtime and PATH composition**
   `internal/devbox/shell.go`, `internal/devbox/envpath/`, `internal/devbox/shellcmd/`, and `internal/envir/` handle the runtime mechanics of entering and using the environment. They merge Devbox-provided tools with the user’s existing shell context, control PATH ordering, and execute commands inside the generated environment.

9. **Plugin and extensibility model**
   Plugins are a first-class subsystem in `internal/plugin/` and the `plugins/` directory. The repo supports local, git, and GitHub plugin sources, including built-in plugin definitions, file overlays, and service definitions. Architecturally, plugins are a modular input that can inject files, packages, and background services into the environment.

10. **Services and sidecar processes**
    `internal/services/` manages auxiliary processes such as databases, web servers, and other dev-time daemons. The examples under `plugins/*process-compose.yaml` and `examples/stacks/*` show that Devbox treats “services” as part of the environment, not as an external afterthought.

11. **Remote distribution and import/export**
    `internal/pullbox/`, `internal/plugin/git.go`, `internal/plugin/github.go`, and the CLI `pull/push` commands support moving environment definitions and assets between local, git-based, GitHub-based, and object-storage-style backends. This is the repo’s boundary for sharing environment state outside the local machine.

12. **Discovery, search, and identity**
    `internal/searcher/` and `internal/devbox/providers/` cover package discovery and provider-specific identity/cache concerns. These are supporting services used by the CLI to find packages, resolve references, and interact with caches or registry-like providers.

13. **Telemetry, diagnostics, and UX**
    `internal/telemetry/`, `internal/debug/`, `internal/redact/`, `internal/ux/`, and `internal/vercheck/` provide cross-cutting observability and user messaging. This is a distinct operational layer: it does not change environment semantics, but it shapes debugging, release reporting, and error presentation.

14. **Testing, examples, and release pipeline**
    `testscripts/` contains end-to-end behavioral tests that exercise the CLI as a user would. `examples/` demonstrates supported stacks and acts as living documentation for architecture patterns. The `.github/workflows/` and `.goreleaser.yaml` files show the release boundary: CI, packaging, container images, CLI releases, and the VS Code extension publish flow are all separate deployment paths from the core runtime.

15. **VS Code extension as a separate client**
    `vscode-extension/` is a standalone frontend client written in TypeScript that integrates with the Devbox CLI/environment model. It is not the core engine; instead, it consumes Devbox-generated environment behavior from the editor side, making the repo a multi-surface product with one shared backend model.

Main entry points: [`internal/devbox`](https://github.com/jetify-com/devbox/tree/main/internal/devbox) (Env engine), [`internal/boxcli`](https://github.com/jetify-com/devbox/tree/main/internal/boxcli) (Commands), [`internal/nix`](https://github.com/jetify-com/devbox/tree/main/internal/nix) (Nix backend), [`internal/plugin`](https://github.com/jetify-com/devbox/tree/main/internal/plugin) (Plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI"]
  node_n_entry["Main<br/>go entrypoint<br/>[main.go]"]
  node_n_boxcli["Commands<br/>go cli"]
  node_n_ux["UX layer<br/>diagnostics"]
end

subgraph group_grp_core["Core engine"]
  node_n_devconfig["Config"]
  node_n_lock["Lockfile<br/>resolved state"]
  node_n_devbox["Env engine<br/>env orchestrator"]
  node_n_packages["Packages<br/>package model"]
  node_n_shellgen["Generation<br/>artifact generator"]
  node_n_shellrt["Shell runtime<br/>shell env<br/>[shell.go]"]
  node_n_envir["Env merge<br/>env composition"]
  node_n_nix["Nix backend<br/>execution backend"]
end

subgraph group_grp_ext["Extensions"]
  node_n_plugin["Plugins<br/>extensibility"]
  node_n_services["Services<br/>sidecar manager"]
  node_n_pullbox["Distribution<br/>remote sync"]
  node_n_search["Discovery<br/>resolver"]
end

subgraph group_grp_surfaces["Surfaces"]
  node_n_examples["Examples<br/>sample envs"]
  node_n_tests["Tests<br/>e2e scripts"]
  node_n_vscode["VS Code<br/>ts client"]
end

node_n_entry -->|"boots"| node_n_boxcli
node_n_boxcli -->|"reads"| node_n_devconfig
node_n_boxcli -->|"drives"| node_n_devbox
node_n_boxcli -->|"delegates"| node_n_nix
node_n_boxcli -->|"exposes"| node_n_pullbox
node_n_boxcli -->|"queries"| node_n_search
node_n_boxcli -->|"reports"| node_n_ux
node_n_devbox -->|"uses"| node_n_lock
node_n_devbox -->|"resolves"| node_n_packages
node_n_devbox -->|"generates"| node_n_shellgen
node_n_devbox -->|"enters"| node_n_shellrt
node_n_devbox -->|"starts"| node_n_services
node_n_devbox -->|"extends"| node_n_plugin
node_n_devbox -->|"composes"| node_n_envir
node_n_packages -->|"materializes"| node_n_nix
node_n_lock -->|"pins"| node_n_nix
node_n_shellgen -->|"targets"| node_n_nix
node_n_plugin -->|"contributes"| node_n_services
node_n_plugin -->|"sources"| node_n_pullbox
node_n_pullbox -->|"fetches"| node_n_nix
node_n_search -->|"looks up"| node_n_nix
node_n_examples -->|"demonstrates"| node_n_devbox
node_n_tests -->|"exercises"| node_n_boxcli
node_n_vscode -->|"invokes"| node_n_boxcli

click node_n_entry "https://github.com/jetify-com/devbox/blob/main/cmd/devbox/main.go"
click node_n_boxcli "https://github.com/jetify-com/devbox/tree/main/internal/boxcli"
click node_n_ux "https://github.com/jetify-com/devbox/tree/main/internal/telemetry"
click node_n_devconfig "https://github.com/jetify-com/devbox/tree/main/internal/devconfig"
click node_n_lock "https://github.com/jetify-com/devbox/tree/main/internal/lock"
click node_n_devbox "https://github.com/jetify-com/devbox/tree/main/internal/devbox"
click node_n_packages "https://github.com/jetify-com/devbox/tree/main/internal/devpkg"
click node_n_shellgen "https://github.com/jetify-com/devbox/tree/main/internal/shellgen"
click node_n_shellrt "https://github.com/jetify-com/devbox/blob/main/internal/devbox/shell.go"
click node_n_envir "https://github.com/jetify-com/devbox/tree/main/internal/envir"
click node_n_nix "https://github.com/jetify-com/devbox/tree/main/internal/nix"
click node_n_plugin "https://github.com/jetify-com/devbox/tree/main/internal/plugin"
click node_n_services "https://github.com/jetify-com/devbox/tree/main/internal/services"
click node_n_pullbox "https://github.com/jetify-com/devbox/tree/main/internal/pullbox"
click node_n_search "https://github.com/jetify-com/devbox/tree/main/internal/searcher"
click node_n_examples "https://github.com/jetify-com/devbox/tree/main/examples"
click node_n_tests "https://github.com/jetify-com/devbox/tree/main/testscripts"
click node_n_vscode "https://github.com/jetify-com/devbox/tree/main/vscode-extension"

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_n_entry,node_n_boxcli,node_n_ux toneBlue
class node_n_devconfig,node_n_lock,node_n_devbox,node_n_packages,node_n_shellgen,node_n_shellrt,node_n_envir,node_n_nix toneAmber
class node_n_plugin,node_n_services,node_n_pullbox,node_n_search toneMint
class node_n_examples,node_n_tests,node_n_vscode toneRose
```

## Components

### CLI

Go command surface and shared UX plumbing

- [Main](https://github.com/jetify-com/devbox/blob/main/cmd/devbox/main.go): go entrypoint · Executable entry point for the Devbox CLI · `cmd/devbox/main.go`
- [Commands](https://github.com/jetify-com/devbox/tree/main/internal/boxcli): go cli · Command tree, flags, and middleware for user-facing subcommands · `internal/boxcli`
- [UX layer](https://github.com/jetify-com/devbox/tree/main/internal/telemetry): diagnostics · Telemetry, debug hooks, redaction, version checks, and user messaging · `internal/telemetry`

### Core engine

Environment, config, packages, shell runtime, lockfiles, and Nix backend

- [Config](https://github.com/jetify-com/devbox/tree/main/internal/devconfig): config parser · Project config parsing, normalization, and multi-format helpers · `internal/devconfig`
- [Lockfile](https://github.com/jetify-com/devbox/tree/main/internal/lock): resolved state · Pinned package and resolution state for devbox.lock · `internal/lock`
- [Env engine](https://github.com/jetify-com/devbox/tree/main/internal/devbox): env orchestrator · Core environment management: shell setup, package orchestration, services, secrets, refresh, and profiles · `internal/devbox`
- [Packages](https://github.com/jetify-com/devbox/tree/main/internal/devpkg): package model · Package abstraction and validation independent of installation backend · `internal/devpkg`
- [Generation](https://github.com/jetify-com/devbox/tree/main/internal/shellgen): artifact generator · Builds shell files, flake files, Dockerfiles, devcontainers, and wrappers · `internal/shellgen`
- [Shell runtime](https://github.com/jetify-com/devbox/blob/main/internal/devbox/shell.go): shell env · PATH composition, shell entry logic, and command execution inside the environment · `internal/devbox/shell.go`
- [Env merge](https://github.com/jetify-com/devbox/tree/main/internal/envir): env composition · Helpers for composing environment variables and inherited shell context · `internal/envir`
- [Nix backend](https://github.com/jetify-com/devbox/tree/main/internal/nix): execution backend · Evaluation, build, install, store, search, and flake operations powered by Nix · `internal/nix`

### Extensions

Plugins, services, pull/push, and remote distribution

- [Plugins](https://github.com/jetify-com/devbox/tree/main/internal/plugin): extensibility · Plugin loading, file overlays, includes, updates, and plugin sources · `internal/plugin`
- [Services](https://github.com/jetify-com/devbox/tree/main/internal/services): sidecar manager · Background dev-time processes and port/status management · `internal/services`
- [Distribution](https://github.com/jetify-com/devbox/tree/main/internal/pullbox): remote sync · Pull/push and remote asset transfer across git, GitHub, and S3-style backends · `internal/pullbox`
- [Discovery](https://github.com/jetify-com/devbox/tree/main/internal/searcher): resolver · Package search and provider identity/cache support · `internal/searcher`

### Surfaces

Examples, tests, and the VS Code client

- [Examples](https://github.com/jetify-com/devbox/tree/main/examples): sample envs · Living documentation for language, server, database, plugin, and stack patterns · `examples`
- [Tests](https://github.com/jetify-com/devbox/tree/main/testscripts): e2e scripts · Black-box CLI integration coverage and scenario runners · `testscripts`
- [VS Code](https://github.com/jetify-com/devbox/tree/main/vscode-extension): ts client · Standalone editor extension client for Devbox integration · `vscode-extension`

## Connections

- Main → Commands: boots · main starts the command framework
- Commands → Config: reads · commands load and normalize project config
- Commands → Env engine: drives · subcommands invoke core environment operations
- Commands → Nix backend: delegates · CLI operations call into the Nix backend when materializing environments
- Commands → Distribution: exposes · pull/push commands route through remote distribution
- Commands → Discovery: queries · search and discovery commands consult package lookup services
- Commands → UX layer: reports · middleware and command handlers emit diagnostics and user-facing messages
- Env engine → Lockfile: uses · core engine reads and updates resolved lock state
- Env engine → Packages: resolves · environment assembly starts from abstract package definitions
- Env engine → Generation: generates · core engine produces launch artifacts and wrappers
- Env engine → Shell runtime: enters · shell commands and environment startup use runtime composition
- Env engine → Services: starts · environment setup includes background services
- Env engine → Plugins: extends · plugins inject packages, files, and service definitions
- Env engine → Env merge: composes · runtime environment variables are merged before execution
- Packages → Nix backend: materializes · package abstractions are translated into Nix-backed units
- Lockfile → Nix backend: pins · resolved state records Nix-derived package outputs and identities
- Generation → Nix backend: targets · generated flake and wrapper artifacts are built around the Nix runtime
- Plugins → Services: contributes · plugins can ship process-compose and service definitions
- Plugins → Distribution: sources · git/github/local plugin inputs overlap with remote distribution mechanisms
- Distribution → Nix backend: fetches · remote assets and plugin material eventually resolve into local Nix-backed content
- Discovery → Nix backend: looks up · search uses backend/provider metadata and cache identity
- Examples → Env engine: demonstrates · examples show supported environment patterns and stacks
- Tests → Commands: exercises · integration scripts run the CLI as users would
- VS Code → Commands: invokes · editor client shells out to or integrates with the CLI model
