devbox

README

Devbox

Instant, easy, and predictable development environments

What is it?

Devbox is a command-line tool that lets you easily create isolated shells for development. You start by defining the list of packages required by your development environment, and devbox uses that definition to create an isolated environment just for your application.

In practice, Devbox works similar to a package manager like yarn – except the packages it manages are at the operating-system level (the sort of thing you would normally install with brew or apt-get). With Devbox, you can install over 400,000 package versions from the Nix Package Registry

Devbox was originally developed by jetpack.io and is internally powered by nix.

Demo

You can try out Devbox in your browser using the button below:

The example below creates a development environment with python 2.7 and go 1.18, even though those packages are not installed in the underlying machine:

Installing Devbox

Use the following install script to get the latest version of Devbox:

curl -fsSL https://https://raw.githubusercontent.com/synopkg/devbox/main/devbox | bash

Read more on the Devbox docs.

Benefits

A consistent shell for everyone on the team

Declare the list of tools needed by your project via a devbox.json file and run synopkg.github.io/devboxell. Everyone working on the project gets a shell environment with the exact same version of those tools.

Try new tools without polluting your laptop

Development environments created by Devbox are isolated from everything else in your laptop. Is there a tool you want to try without making a mess? Add it to a Devbox shell, and remove it when you don't want it anymore – all while keeping your laptop pristine.

Don't sacrifice speed

Devbox can create isolated environments right on your laptop, without an extra-layer of virtualization slowing your file system or every command. When you're ready to ship, it'll turn it into an equivalent container – but not before.

Good-bye conflicting versions

Are you working on multiple projects, all of which need different versions of the same binary? Instead of attempting to install conflicting versions of the same binary on your laptop, create an isolated environment for each project, and use whatever version you want for each.

Take your environment with you

Devbox's dev environments are portable. We make it possible to declare your environment exactly once, and use that single definition in several different ways, including:

• A local shell created through synopkg.github.io/devboxell
• A devcontainer you can use with VSCode
• A Dockerfile so you can build a production image with the exact same tools you used for development.
• A remote development environment in the cloud that mirrors your local environment.

Quickstart: Fast, Deterministic Shell

In this quickstart we’ll create a development shell with specific tools installed. These tools will only be available when using this Devbox shell, ensuring we don’t pollute your machine.

1. Open a terminal in a new empty folder.

2. Initialize Devbox:

   devbox init
   

   This creates a devbox.json file in the current directory. You should commit it to source control.

3. Add command-line tools from Nix. For example, to add Python 3.10:

   devbox add python@3.10
   

   Search for more packages on Nixhub.io

4. Your devbox.json file keeps track of the packages you've added, it should now look like this:

   {
      "packages": [
         "python@3.10"
       ]
   }
   

5. Start a new shell that has these tools installed:

   synopkg.github.io/devboxell
   

   You can tell you’re in a Devbox shell (and not your regular terminal) because the shell prompt changed.

6. Use your favorite tools.

   In this example we installed Python 3.10, so let’s use it.

   python --version
   

7. Your regular tools are also available including environment variables and config settings.

   git config --get user.name
   

8. To exit the Devbox shell and return to your regular shell:

   exit
   

Read more on the Devbox docs Quickstart.

Additional commands

devbox help - see all commands

See the CLI Reference for the full list of commands.

Join our Developer Community

• Chat with us by joining the Jetpack.io Discord Server – we have a #devbox channel dedicated to this project.
• File bug reports and feature requests using Github Issues
• Follow us on Jetpack's Twitter for product updates

Contributing

Devbox is an opensource project so contributions are always welcome. Please read our contributing guide before submitting pull requests.

Related Work

Thanks to Nix for providing isolated shells.

Translation

• Chinese

License

This project is proudly open-source under the Apache 2.0 License

Documentation

Overview

Package devbox creates isolated development environments.

Index

• func ExportifySystemPathWithoutWrappers() string
• func GlobalDataPath() (string, error)
• func InitConfig(dir string, writer io.Writer) (bool, error)
• func PrintEnvrcContent(w io.Writer, envFlags devopt.EnvFlags) error
• type Devbox
  • func Open(opts *devopt.Opts) (Devbox, error)

Functions

func ExportifySystemPathWithoutWrappers

func ExportifySystemPathWithoutWrappers() string

ExportifySystemPathWithoutWrappers reads $PATH, removes `virtenv/.wrappers/bin` paths, and returns a string of the form `export PATH=....`

This small utility function could have been inlined in the boxcli caller, but needed the impl.exportify functionality. It does not depend on core-devbox.

func GlobalDataPath

func GlobalDataPath() (string, error)

func InitConfig

func InitConfig(dir string, writer io.Writer) (bool, error)

InitConfig creates a default devbox config file if one doesn't already exist.

func PrintEnvrcContent

func PrintEnvrcContent(w io.Writer, envFlags devopt.EnvFlags) error

Types

type Devbox

type Devbox interface {
	Add(ctx context.Context, platforms, excludePlatforms []string, pkgs ...string) error
	Config() *devconfig.Config
	EnvVars(ctx context.Context) ([]string, error)
	Info(ctx context.Context, pkg string, markdown bool) (string, error)
	Install(ctx context.Context) error
	IsEnvEnabled() bool
	ListScripts() []string
	NixEnv(ctx context.Context, opts devopt.NixEnvOpts) (string, error)
	PackageNames() []string
	ProjectDir() string
	Pull(ctx context.Context, opts devopt.PullboxOpts) error
	Push(ctx context.Context, opts devopt.PullboxOpts) error
	Remove(ctx context.Context, pkgs ...string) error
	RunScript(ctx context.Context, scriptName string, scriptArgs []string) error
	Shell(ctx context.Context) error
	Update(ctx context.Context, opts devopt.UpdateOpts) error

	// Interact with services
	ListServices(ctx context.Context) error
	RestartServices(ctx context.Context, services ...string) error
	Services() (services.Services, error)
	StartProcessManager(ctx context.Context, requestedServices []string, background bool, processComposeFileOrDir string) error
	StartServices(ctx context.Context, services ...string) error
	StopServices(ctx context.Context, allProjects bool, services ...string) error

	// Generate files
	Generate(ctx context.Context) error
	GenerateDevcontainer(ctx context.Context, generateOpts devopt.GenerateOpts) error
	GenerateDockerfile(ctx context.Context, generateOpts devopt.GenerateOpts) error
	GenerateEnvrcFile(ctx context.Context, force bool, envFlags devopt.EnvFlags) error
}

Devbox provides an isolated development environment.

func Open

func Open(opts *devopt.Opts) (Devbox, error)

Open opens a devbox by reading the config file in dir.