ros2-humble-env

Riple Environment and Binary Creation

• Uses the original environment template setup from "ros2-humble-env" to create a WSL2 distro.
• A reproducible and declarative development environment for ROS2 Humble using Nix flakes and pixi for cross-platform compatibility.
• This repository is meant to be used as a "template" repository for robotics projects to offer an easy starting environment with a working ROS2 install.

Quick Start

Windows (WSL2 + NixOS)

# Run PowerShell as Administrator
# Download and run the bootstrap script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/FlexNetOS/ros2-humble-env/main/bootstrap.ps1" -OutFile "bootstrap.ps1"
.\bootstrap.ps1

Linux / macOS

# Clone the repository
git clone https://github.com/FlexNetOS/ros2-humble-env.git
cd ros2-humble-env

# Run the bootstrap script (installs everything)
./bootstrap.sh

# Or if you already have nix installed:
nix develop  # (or: nom develop for nicer output)

Goal

Bootstrap Environment

• ✅ A single script run from Windows PowerShell that checks for Linux and WSL2 install, then installs and updates them as needed.
• ✅ Creates the NixOS Distro, registers it, creates the ext4.vhdx hard disk image 1TB, and swap image.
• ✅ Loads the nix flake and configurations per direnv
• ✅ Sets up pixi package manager, tools, and packages
• ✅ Adds zsh and nushell (bash stays default with nix)
• ✅ Includes nom (nix-output-monitor) for nicer output (optional; nix still works)
• ✅ Installs git and gh cli

Agentic System

• 🔄 Agentic system that runs robotics, DevOps, user's personal life and work life
• ✅ Modular and Portable - Configuration modules can be imported into any Nix flake
• ✅ Built for Cross-platform Use - Linux, macOS, and Windows (WSL2) support
• ✅ Clear Configs and Schema - Documented options with types and defaults

Documentation

• ✅ AGENT.md - Agent system architecture and capabilities
• ✅ CLAUDE.md - Claude Code specific instructions
• ✅ RULES.md - Rules and contribution guidelines
• ✅ SKILL.md - Available skills and tool reference
• ✅ INDEX.md - Documentation navigation

Overview

This repository provides a complete development setup for ROS2 Humble with all necessary build tools and dependencies pre-configured. The environment works on:

• Windows (via WSL2 + NixOS)
• Linux (native, x86_64 and aarch64)
• macOS (x86_64 and arm64)

Using:

• Nix flakes: for reproducible, declarative environment setup
• pixi: for Python and ROS package management via RoboStack
• direnv: for automatic environment activation
• home-manager modules: for comprehensive shell and editor configuration

Getting Started

Windows Installation (Recommended for Windows users)

The PowerShell bootstrap script (bootstrap.ps1) automates the entire setup:

# Option 1: Run directly (requires Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force
.\bootstrap.ps1

# Option 2: With custom options
.\bootstrap.ps1 -DistroName "MyROS2" -DiskSizeGB 512 -SwapSizeGB 16

What it does:

1. Checks Windows version (requires build 19041+)
2. Enables WSL2 and Virtual Machine Platform
3. Downloads and imports NixOS-WSL distribution
4. Creates 1TB ext4.vhdx virtual disk
5. Configures swap (default 8GB)
6. Runs the Linux bootstrap script inside WSL
7. Sets up the complete ROS2 environment

Parameters:

Parameter	Default	Description
-DistroName	NixOS-ROS2	Name for the WSL distribution
-InstallPath	$HOME\WSL\NixOS-ROS2	Installation directory
-DiskSizeGB	1024	Virtual disk size (1TB)
-SwapSizeGB	8	Swap size in GB
-SkipWSLCheck	false	Skip WSL installation check
-Force	false	Replace existing distro

After installation:

# Enter the environment
wsl -d NixOS-ROS2
cd ~/ros2-humble-env
direnv allow

# If you prefer manual activation (direnv optional):
nix develop  # (or: nom develop for nicer output)

Linux / macOS Installation

./bootstrap.sh

This script will:

1. Install Nix with flakes enabled (using Determinate Systems installer)
2. Install direnv, nom, git, gh cli
3. Optionally install zsh and nushell
4. Verify the flake and pixi setup

For CI environments:

./bootstrap.sh --ci --skip-shells

Manual Installation

If you prefer to install manually:

# Install nix (experimental installer with flakes)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Enter the development environment
nix develop

# Optional (nicer output):
nom develop

Using direnv

If you have direnv installed, simply enter the directory:

cd ros2-humble-env
direnv allow

direnv will automatically load the environment.

Workspace Structure