nem

Reproducible development environments for your projects.

Documentation   •   Getting started   •   Guides   •   Reference

[!NOTE] nem is in active development. Expect breaking changes and rough edges — feedback and contributions are very welcome!

nem gives each project a reproducible set of developer tools and environment variables. Declare what you need in a nem.ver file — nem fetches, installs, and puts it on your PATH, identically for every teammate, agent, and CI pipeline.

• Reproducible environments — commit a nem.ver and everyone gets the same tools and variables, on demand, per directory.
• Least privilege by design — runs without root; downloads are checksum-verified and source builds run sandboxed.
• Air-gapped friendly — distribute tool catalogs and packages through any OCI registry, audited like any other artifact.

Installation

Install nem using the provided installation script:

curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | sh

By default, nem is installed to ~/.local/bin. Add this directory to your PATH if it isn't already:

export PATH="$HOME/.local/bin:$PATH"

You can customize the installation directory and version by setting the NEM_INSTALL_DIR and NEM_VERSION environment variables:

# Install to a custom directory
curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | NEM_INSTALL_DIR=/usr/local/bin sh

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | NEM_VERSION=v1.2.3 sh

Prebuilt binaries for Linux and macOS are also attached to every GitHub release.

[!NOTE] By default, nem uses the public vi-dev/nem-catalog package catalog (the official catalog) with no extra setup. Set NEM_USE_OFFICIAL_CATALOG=0 (or use-official-catalog: false in ~/.nem/config.yaml) to disable, or run nem catalog add to configure your own.

[!NOTE] Source-build packages run their build steps in a sandbox by default. Set NEM_SANDBOX=0 (or sandbox: false in ~/.nem/config.yaml) to disable it — builds then run with unrestricted network and filesystem access.

Quick start

nem activate
exec $SHELL
cd ~/code/my-project
nem use kubectl@v1.34.1
kubectl version --client

Activating nem also enables tab completion for the nem command in your shell (bash, zsh, fish). If you don't want to install the shell integration, you can source completions directly with eval "$(nem completion zsh)" (or the equivalent for your shell).

Documentation

Full documentation lives at vi-dev.org/nem:

• Getting started — install, set up your first environment, and learn how nem works.
• Guides — shell integration, managing environments, catalogs, sandboxed builds, containers, and troubleshooting.
• Authoring packages — write, validate, and publish your own catalog.
• Reference — CLI commands, configuration, the nem.ver format, and the pkg.yaml schema.

Container image

Signed multi-arch images are published to ghcr.io/vi-dev/nem on every release:

docker run --rm --privileged ghcr.io/vi-dev/nem version

See the container image guide for information on tag schemes, usages, provenance verification, and more.

Contributing

Contributions are welcome. The developer docs explain how nem is built:

• Architecture — package layout and how the internals fit together.
• Architecture decisions — the ADR log behind key design choices.
• Messages — conventions for user-facing output.

Please open an issue to discuss substantial changes before sending a pull request.

Security

See SECURITY.md.

License

MPL-2.0.