Nix-based environment definitions for AI coding agents and multi-agent orchestrators.

Setting up environments for AI agent orchestrators involves repetitive work: installing the orchestrator itself, adding required runtimes (Node.js, Python, Go), configuring CLI tools, and ensuring everything works together. Each orchestrator has different dependencies and setup steps.

agentboxes provides pre-built Nix definitions for these tools. You describe what you need in agentbox.toml, and Nix produces either a development shell or an OCI image—same config, same result, anywhere.

This is similar to what you could do with devenv, devbox, or plain Nix flakes. The difference is that agentboxes has already packaged the orchestrators (schmux, gastown, openclaw, ralph) and agents (claude, codex, etc.), so you don't have to.

# Enter a shell with schmux and all its dependencies
nix develop github:farra/agentboxes#schmux

# Or build an OCI image
just build-image schmux

agentboxes builds environments. How you run them depends on your needs:

Each has tradeoffs:

• nix develop: Ephemeral. Environment disappears when you exit. No isolation from host filesystem.
• Docker/Podman: Isolated. Requires explicit volume mounts to persist state. Works everywhere containers run.
• Distrobox: Shares $HOME with host by default (convenient but less isolated). Persists between sessions. Linux only.

Choose based on your isolation and persistence requirements.

# Use an agent directly (without an orchestrator)
nix develop github:farra/agentboxes#claude

All environments include the substrate layer: git, curl, jq, ripgrep, fd, fzf, tmux, htop, and 50+ modern CLI tools.

For project-specific environments, create an agentbox.toml:

mkdir my-ai-project && cd my-ai-project
nix flake init -t github:farra/agentboxes#project

This creates flake.nix and agentbox.toml. Edit the config:

[orchestrator]
name = "schmux"

agents = ["claude-code"]
bundles = ["baseline"]
packages = ["python312", "nodejs_22"]

[image]
name = "my-project"
tag = "latest"

Then:

# Ephemeral development
nix develop

# Or build a pre-baked image for deployment
just build-image my-project

The distros/ directory contains configurations for each orchestrator with baseline tools and claude-code agent.

Use a distro as your starting point:

# Copy a distro config to your project
curl -O https://raw.githubusercontent.com/farra/agentboxes/main/distros/schmux.toml
mv schmux.toml agentbox.toml

Images are built using a Containerfile that bakes all tools into a wolfi-toolbox base:

# Build an image (uses podman or docker)
just build-image schmux

# Create and enter a distrobox
just distrobox-create schmux
just distrobox-enter schmux

# Or test locally in one step
just test-local schmux

# Push to registry
just push-image schmux

# Build, tag, and push a release
just release schmux v1.0.0

The Containerfile:

1. Starts from wolfi-toolbox base (distrobox-compatible)
2. Installs Nix using Determinate Systems installer
3. Runs nix profile install .#<name>-env to bake all tools

Images are ready to use immediately - no bootstrap or first-run installation needed.

# Image metadata
[image]
name = "my-project"
tag = "latest"
base = "wolfi"

# Orchestrator (optional)
[orchestrator]
name = "schmux"  # schmux | gastown | openclaw | ralph

# AI coding agents from numtide/llm-agents.nix
agents = ["claude-code", "codex", "gemini-cli", "opencode"]

# Tool bundles
bundles = ["baseline"]  # baseline (28 tools) or complete (61 tools)

# Rust toolchains (via rust-overlay)
# bundles = ["baseline", "rust-stable"]  # rust-stable | rust-beta | rust-nightly

# Exact nixpkgs package names
packages = ["python312", "nodejs_22", "go_1_24"]

# NUR packages (optional)
# packages = ["nur:owner/package"]

Build and transfer an OCI image:

just build-image schmux
podman save ghcr.io/farra/agentboxes-schmux:latest | ssh server 'podman load'

Then run via Docker, Podman, distrobox, or any container runtime.

See the Deployment Guide for registry publishing, team onboarding, and CI/CD examples.

agentboxes/
├── flake.nix                    # Root flake with packages and devShells
├── justfile                     # Build commands (images, testing, dev)
├── lib/
│   ├── substrate.nix            # Common tools layer
│   ├── bundles.nix              # Tool bundles (baseline, complete)
│   ├── parseAgentboxConfig.nix  # Shared TOML parsing logic
│   ├── mkProjectShell.nix       # Compose devShell from agentbox.toml
│   └── mkProfilePackage.nix     # Build env for nix profile install
├── agents/                      # Agent wrappers (claude, codex, gemini, opencode)
├── orchestrators/               # Orchestrator definitions (schmux, gastown, etc.)
├── templates/project/           # Template for `nix flake init -t`
├── images/
│   └── Containerfile            # OCI image builder
├── distros/                     # Pre-configured orchestrator configs
└── docs/                        # Documentation

• numtide/llm-agents.nix - Source for all agent packages
• distrobox - Run containers as if on host

Apache-2.0