Devbox - Reproducible Dev Environments Cheatsheet
Devbox (by Jetify) creates isolated, reproducible development environments without Docker or virtual machines. It is powered by Nix but hides the Nix language behind a simple JSON config (devbox.json) and a familiar CLI — you run devbox add nodejs@20 instead of writing a Nix derivation. The result: everyone on the team (and CI) gets the exact same toolchain, pinned to precise versions, isolated from the host system.
Installation
Getting Started
| Command | Description |
|---|
devbox init | Create a devbox.json in the project |
devbox add nodejs@20 python@3.12 | Add packages (pinned versions) |
devbox rm python | Remove a package |
devbox install | Install everything in devbox.json |
devbox shell | Enter the isolated environment |
devbox run <script> | Run a defined script inside the env |
Managing Packages
| Command | Description |
|---|
devbox add go@1.22 | Add a specific version |
devbox search postgresql | Search the Nix package catalog |
devbox list | List installed packages |
devbox update | Update packages to latest allowed |
devbox info nodejs | Show details for a package |
Versions resolve against the Nixpkgs catalog, so nodejs@20 is reproducible everywhere.
The Config (devbox.json)
{
"packages": ["nodejs@20", "python@3.12", "postgresql@16"],
"shell": {
"init_hook": ["echo 'Welcome to the project env'"],
"scripts": {
"dev": "npm run dev",
"test": "npm test",
"db": "pg_ctl start"
}
}
}
| Field | Purpose |
|---|
packages | Pinned tool/language versions |
shell.init_hook | Commands run on entering the shell |
shell.scripts | Named commands (devbox run dev) |
env | Environment variables for the project |
Shell & Scripts
| Command | Description |
|---|
devbox shell | Interactive isolated shell |
devbox run dev | Run the dev script |
devbox run -- npm ci | Run an arbitrary command in the env |
exit | Leave the Devbox shell |
Services (Process Management)
Devbox can manage background services (databases, etc.) for a project.
| Command | Description |
|---|
devbox services ls | List configured services |
devbox services up | Start services |
devbox services stop | Stop services |
devbox add postgresql --start-services | Add a service-backed package |
CI & Containers
| Use | How |
|---|
| CI | Install Devbox, run devbox run test — identical env to local |
| Docker | devbox generate dockerfile produces a reproducible image |
| Devcontainer | devbox generate devcontainer for VS Code |
| Direnv | devbox generate direnv to auto-enter the env on cd |
Common Workflows
# Stand up a reproducible project env from scratch
devbox init
devbox add nodejs@20 postgresql@16
devbox shell # now node + postgres are available, pinned
# Run tasks the same way locally and in CI
devbox run test
# Produce a Docker image from the same definition
devbox generate dockerfile
Devbox vs Alternatives
| Aspect | Devbox | Dev Containers | Nix (raw) | mise |
|---|
| Backend | Nix | Docker | Nix | Own registry |
| Config | JSON | devcontainer.json | Nix language | .mise.toml |
| Isolation | Real (Nix store) | Container | Real | Tool versions |
| Learning curve | Gentle | Moderate | Steep | Gentle |
| Best for | Reproducible envs, easy | Container-based dev | Full Nix power | Version management |
See also Nix for the underlying power, devcontainer for container-based dev, and mise for tool-version management.
Resources
