This repository contains my personal Nix configuration for managing my Mac laptop and Linux home servers using a declarative, reproducible approach with Nix flakes.
This configuration manages:
- macOS laptop (cloudbank) - M-series Mac with nix-darwin
- Linux servers - Multiple headless NixOS home servers:
- ultraviolet, bluedesert, echelon
- Unified Configuration: Single repository managing both macOS and Linux systems
- Modular Design: Separated system-level and user-level configurations
- Consistent Theming: Catppuccin Mocha theme across all applications
- Custom Packages: Currently includes a customized Caddy web server
- Development Environment: Neovim, Git, Starship prompt, and modern CLI tools
- Simplified Architecture: Streamlined flake structure with minimal abstraction
- Devspace Development Environment: Persistent tmux-based remote development sessions
- Remote Link Opening: Seamless browser integration for SSH sessions
On the target machine, use the update alias or run directly:
# macOS
darwin-rebuild switch --flake ".#$(hostname -s)"
# Linux
sudo nixos-rebuild switch --flake ".#$(hostname)"nix flake updatenix build .#myCaddy # Custom Caddy web serverflake.nix- Main entry point and flake configurationhosts/- System-level configurations for each machinecommon.nix- Shared configuration for Linux servers (NFS mounts)
home-manager/- User-level dotfiles and application configscommon.nix- Shared configuration across all systemsaarch64-darwin.nix- macOS-specific user configurationheadless-x86_64-linux.nix- Linux server user configuration- Individual app modules (neovim, zsh, kitty, etc.)
pkgs/- Custom package definitionsoverlays/- Nixpkgs modificationssecrets/- Public keys
- Editor: Neovim with custom configuration
- Terminal: Kitty with Catppuccin theme
- Shell: Zsh with syntax highlighting and autosuggestions
- Version Control: Git
- AI Assistance: Claude Code (automatically installed via npm)
- Window Manager: Aerospace
- Package Management: Homebrew (declaratively managed)
- Kubernetes: k9s for cluster management
- File Sharing: NFS mounts to NAS
- Web Server: Custom Caddy build
- Simplified Flake Structure: Removed unnecessary helper functions and abstractions
- Unified Nixpkgs: Using nixpkgs-unstable as primary source
- Single Overlay: Consolidated all overlays into one default overlay
- Minimal Special Args: Only passing essential inputs and outputs
- Direct Home Manager Integration: Home Manager configured directly in flake.nix
To add a new system:
- Create a configuration in
hosts/<hostname>/ - Add to
flake.nixunder appropriate section (nixosConfigurations or darwinConfigurations) - Add hostname to the appropriate list in homeConfigurations
To add a new package:
- Create package in
pkgs/<name>/default.nix - Add to
pkgs/default.nix - Add to overlay in
overlays/default.nixif needed globally
The Devspace system provides persistent, theme-aware tmux-based development environments on remote servers. Each devspace maintains its own project context, git worktrees, and color theme.
- Persistent Sessions: Tmux sessions survive SSH disconnections and system reboots
- Automatic Restoration: Sessions and project links are restored after system rebuilds
- Minimal Resource Usage: Uninitialized devspaces show only a setup prompt
- Smart Expansion: Full environment (claude, nvim, term, logs windows) created on demand
- Git Worktree Isolation: Automatic worktree creation when multiple devspaces use the same repo
- Theme Integration: Each devspace has its own color scheme from Catppuccin palette
- State Persistence: Session state saved automatically on meaningful events
- Mercury 🚀 (flamingo) - Quick experiments and prototypes
- Venus 🎨 (pink) - Personal creative projects
- Earth 🌍 (green) - Primary work project
- Mars 🔴 (red) - Secondary work project
- Jupiter 🪐 (peach) - Large personal project
From your Mac:
# Connect to a devspace (creates minimal session if needed)
earth # Connect to Earth devspace
# First time setup - link a project
earth ~/Work/my-project # Links project and expands to full environment
earth . # Link current directory
# Subsequent connections go straight to your dev environment
earth # Reconnects to existing sessionearth # Connect to devspace (auto-restores if needed)
mars # Each devspace has its own command
venus status # Show current project and session state
jupiter worktree create feat # Create a feature branch worktree# Linking projects
earth /path/to/project # Link devspace to a project
earth setup ~/Work/project # Explicit setup command (same as above)
earth . # Link to current directory
# Status and info
earth status # Show linked project and session state
devspace-status # Show all devspaces status (alias: ds)
# Git worktrees
earth worktree create feature # Create a worktree for feature work
earth worktree list # List all worktrees for this devspace
earth worktree clean # Remove merged worktreesdevspace-sync-aws # Sync AWS creds to server (alias: dsa)
devspace-sync-aws earth # Sync to specific devspace directory# Window navigation
Ctrl-b 1 # Claude window
Ctrl-b 2 # Neovim window
Ctrl-b 3 # Terminal window
Ctrl-b 4 # Logs window
# Quick key shortcuts (when in devspace mode)
Ctrl-b c # Jump to Claude
Ctrl-b n # Jump to Neovim
Ctrl-b t # Jump to Terminal
Ctrl-b l # Jump to Logs
# Session switching (with Meta/Alt key)
Meta-E # Switch to Earth session
Meta-M # Switch to Mars session
Meta-J # Switch to Jupiter session
# ... etc (uses first letter of devspace name)# If you SSH directly without using devspace commands
earth # Attach to Earth session (auto-restores if needed)
mars status # Check Mars configuration
# Manual session management (rarely needed)
devspace-restore # Manually restore all sessions from saved state
save_session_state # Manually save current session state-
Initial State: On system boot,
devspace-restoreservice creates minimal placeholder sessions -
First Connection: Shows welcome screen with setup instructions
-
Project Linking: When you link a project, session expands to full 4-window environment
-
State Persistence: State saved automatically when:
- Projects are linked/changed
- Windows are created/destroyed
- Clients detach from sessions
- Every 30 minutes via systemd timer
- Before system shutdown/rebuild
-
Restoration: After reboot/rebuild:
- Service reads saved state from
~/.local/state/tmux-devspaces/ - Recreates sessions with their initialization state
- Restores project links if directories still exist
- Falls back to minimal sessions if restoration fails
- Service reads saved state from
When multiple devspaces need the same repository:
# First devspace gets direct link
earth ~/Work/main-repo # Links directly
# Second devspace automatically creates worktree
mars ~/Work/main-repo # Creates worktree at ~/devspaces/mars/worktrees/devspace-mars-TIMESTAMPWorktrees are automatically cleaned up when:
- Branches are merged into main
- You switch to a different project
- You run
earth worktree clean
The devspace theme is defined in pkgs/devspaces/theme.nix. To add or modify devspaces:
- Edit the theme file to add/remove spaces
- Rebuild your systems
- New devspaces automatically get:
- tmux session management
- Connection shortcuts
- Color theming
- State persistence
# Check systemd service status
systemctl status devspace-restore
# View service logs
journalctl -u devspace-restore -f
# Manually restore sessions
devspace-restore
# Check saved state
cat ~/.local/state/tmux-devspaces/sessions.txt
# Force recreation of a devspace
tmux kill-session -t devspace-earth
earth # Will auto-restoreWhen SSH'd into a server, links can be opened on your local Mac browser automatically. This is especially useful for AWS SSO authentication.
- The server sets
BROWSER=remote-link-open - When applications try to open URLs, they display as clickable links in Kitty
- Click the link in your terminal to open it in your Mac browser
# On the server
aws sso login # Will display a clickable authentication URL
remote-link-open https://example.com # Manually open a URLSee CLAUDE.md for detailed testing procedures. Quick summary:
# Validate configuration
nix flake check
# Preview changes
darwin-rebuild switch --flake ".#$(hostname -s)" --dry-run
# Build specific components
nix build .#homeConfigurations."joshsymonds@$(hostname -s)".activationPackage