Nix Development Environment

We use Nix Flakes. Run nix develop and you get exactly the same tools as everyone else on the team. Gleam 1.14.0. Rust 1.93. Bun 1.3. Erlang/OTP 27. All pinned. No version drift. No “works on my machine.”

Why Nix Flakes?

npm manages Node packages. cargo manages Rust crates. apt manages system packages. Nix manages all of it — your entire development environment.

What you get:

• Exact versions — Pin Gleam 1.14.0, not “latest 1.x.” Same for every tool.
• Zero system pollution — Dependencies live in /nix/store. Exit the shell, they’re gone.
• Same everywhere — Your laptop, your coworker’s laptop, CI. Identical.
• One file — flake.nix declares everything. No README instructions for installing dependencies.

Colony orchestrates Gleam/OTP, Rust, Node.js, Caddy, dnsmasq, and Jujutsu. That’s too many moving parts to manage manually.

What the Flake Provides

Colony’s flake.nix includes:

Tool	Version	Purpose
Gleam	1.14.0	Mycelium backend language
Erlang/OTP	27	Runtime for Gleam/OTP actors
Rust	1.93+	Stem TUI and Rust tooling
Bun	1.3+	Bloom web dashboard (SolidJS)
Caddy	Latest	Reverse proxy with dynamic routing
dnsmasq	Latest	DNS resolver for *.colony.local
Jujutsu	0.38+	Version control system
Protobuf	3.x	Protocol buffer compiler
Overmind	2.5+	Process manager (Procfile)

Plus standard build tools: gcc, pkg-config, openssl, etc.

Entering the Development Shell

From the Colony repository root:

cd ~/dev/colony
nix develop

Nix reads flake.nix and flake.lock, downloads dependencies (cached after first run), and drops you into a shell.

Now gleam, cargo, node, jj, caddy — everything’s in your $PATH. Nothing installed system-wide.

direnv Integration

Want automatic activation when you cd into the directory?

# Install direnv
nix-env -iA nixpkgs.direnv

# Add to ~/.zshrc or ~/.bashrc
eval "$(direnv hook zsh)"  # or bash

# Allow Colony's .envrc
cd ~/dev/colony
echo "use flake" > .envrc
direnv allow

Now cd ~/dev/colony automatically activates the environment. No manual nix develop.

Adding Dependencies

System Tools

Edit flake.nix and add to the buildInputs list:

buildInputs = with pkgs; [
  gleam
  erlang_27
  # ... existing tools
  postgresql  # Add a new tool
];

Then update the lock file:

nix flake update

Language-Specific Dependencies

Nix provides the runtimes. Use language-native tools for libraries:

• Gleam: Add to gleam.toml → gleam deps download
• Rust: Add to Cargo.toml → cargo build
• Node.js/Bun: Add to package.json → bun install

How Colony Uses Nix Internally

Beyond development, Colony uses Nix concepts for colony provisioning:

1. Per-colony environments — Colonies specify required tools in colony.toml
2. Isolated shells — Mycelium spawns processes inside Nix shells
3. Build isolation — CI runs tests in nix develop for clean environments

Phase 1 uses basic provisioning. Future versions will integrate Nix more deeply.

CI/CD with Nix

CI uses the same flake:

- name: Set up Nix
  uses: cachix/install-nix-action@v22
  with:
    enable_flakes: true

- name: Enter dev environment
  run: nix develop --command make test

CI tests run in the exact same environment as your laptop. No “CI passed but local failed” surprises.

Nix Store Location

All dependencies live in /nix/store/. Content-addressed. Each package identified by a hash of its inputs.

Example path:

/nix/store/abc123...-gleam-1.14.0/bin/gleam

Multiple projects share the same paths. Two projects using Gleam 1.14.0? Same /nix/store/ entry. Zero duplication.

Upgrading Versions

Update everything:

nix flake update

This updates flake.lock with new hashes. Commit the lock file.

Pin a specific version:

# Pin to specific nixpkgs commit
inputs.nixpkgs.url = "github:NixOS/nixpkgs/abc123def456";

Troubleshooting

Command Not Found After nix develop

Check that the tool is listed in buildInputs. If it’s there, try:

nix flake update
nix develop --refresh

Slow Download on First Run

Nix uses binary caches (pre-built packages). If a package isn’t cached, Nix builds from source. First run can take a while. Be patient.

direnv Not Activating

Ensure .envrc contains use flake and you’ve run direnv allow. Check direnv status for diagnostics.

Next Steps

• Configuration Reference — Understanding colony.toml and environment variables
• Contributing Guide — How to contribute to Colony (Nix knowledge helps)
• Architecture Overview — How all the pieces fit together