Devbox

Devbox Dependency Management

Devbox is the preferred dependency manager for new projects. Use it to create reproducible development environments.

When to Use Devbox vs Other Tools

Adding Packages

CRITICAL: Add packages one at a time. Adding multiple packages in a single command exceeds the 120s timeout.

# Correct - one package at a time
devbox add nodejs
devbox add python
devbox add postgresql

# Wrong - will timeout
devbox add nodejs python postgresql

Finding Packages

devbox search <package-name>

Environment Variables

Testing First

Test environment variables in commands before making them permanent:

# Test that it works
DATABASE_URL=postgres://localhost/mydb devbox run npm start

Making Permanent

Once confirmed working, add to devbox.json init_hook or setup scripts:

Option 1: devbox.json init_hook

{
  "packages": ["nodejs", "postgresql"],
  "shell": {
    "init_hook": [
      "export DATABASE_URL=postgres://localhost/mydb",
      "export NODE_ENV=development"
    ]
  }
}

Option 2: Setup scripts (.devbox/setup-*.sh)

# .devbox/setup-env.sh
export DATABASE_URL=postgres://localhost/mydb
export NODE_ENV=development

Anti-pattern

Never leave environment variables in repeated command invocations:

# Wrong - env var in every command
DATABASE_URL=x devbox run npm test
DATABASE_URL=x devbox run npm start
DATABASE_URL=x devbox run npm build

# Right - set once in init_hook, then just run
devbox run npm test
devbox run npm start
devbox run npm build

Common Commands

devbox init              # Initialize devbox in current directory
devbox add <pkg>         # Add a package
devbox rm <pkg>          # Remove a package
devbox shell             # Enter devbox shell
devbox run <cmd>         # Run command in devbox environment
devbox services start    # Start background services
devbox services stop     # Stop background services
devbox update            # Update packages

Project Structure

A devbox project typically has:

project/
├── devbox.json          # Package list and configuration
├── devbox.lock          # Locked versions
└── .devbox/
    ├── setup-env.sh     # Custom environment setup (optional)
    └── ...