Skip to content

Sao

Named after Sao, a moon of Neptune, this development VM orbits within the Neptune infrastructure platform.

System: Ubuntu 24.04.3 LTS | Purpose: Full-stack development environment

Overview

This is a fully configured Ubuntu development workstation designed for modern full-stack development. The setup prioritizes:

  • Developer ergonomics: Neovim with LSP and auto-formatting
  • Go/TypeScript/React ready: Formatters and language servers
  • Containerization: Docker Engine
  • AI integration: Claude CLI within Neovim

Agent System

Automated Documentation System

The Sao VM uses a multi-agent system powered by Claude Code that keeps the system and documentation automatically synchronized. The Main Agent handles all development work like installing tools, configuring Neovim, and managing containers, then automatically invokes the Docs Agent to update documentation. Documentation is hosted at sao.bros.ninja via MkDocs Material, enabling rich visualization and human review of all automated changes. This ensures docs never become stale, and every system change is immediately reflected without manual intervention.

graph LR
    User[User Request] --> Main[Main Agent]
    Main -->|Installs/Configures| System[System]
    System --> Main
    Main -->|Invokes with context| Docs[Docs Agent]
    Docs -->|Updates| Documentation[Documentation]
    Documentation -->|Hosted at| Web[MkDocs<br/>sao.bros.ninja]

Infrastructure

This is a VM-based development environment running on enterprise homelab infrastructure.

Part of the Neptune Platform

Sao is one satellite in the larger Neptune infrastructure, a homelab platform built on XCP-ng that provides:

  • Easy VM provisioning with XCP-ng hypervisor
  • Container orchestration via Docker on dedicated VMs
  • Public web hosting through reverse proxy (services accessible at *.bros.ninja)
  • Automated backups with XCP-ng snapshot scheduling to TrueNAS
  • ZFS storage with 40 TiB capacity and redundancy

Learn more about the full platform at bros.ninja

Virtual Machine Specs

  • Platform: Ubuntu 24.04.3 LTS Desktop (configured with SSH and NoMachine for remote access)
  • Hypervisor: XCP-ng (Xen-based virtualization)
  • Host: Dell OptiPlex 5050 (i7-7700 @ 3.60GHz, 8 cores with HT)
  • VM Resources: 6 vCPUs, 32GB RAM, 500GB storage
  • Storage Backend: TrueNAS NFS dataset ("devbox") with dynamic expansion
  • 40 TiB usable capacity in mirrored vdev pairs
  • Excellent R/W performance and data redundancy
  • Currently 10 TiB available

Remote Access

  • SSH: Terminal access for development work
  • NoMachine: Remote desktop access

NoMachine Resolution Limitation

WIP: Ultrawide resolution is currently limited by the integrated GPU capabilities.

Backup & Recovery

graph TB
    subgraph Failures[Failure Scenarios]
        F1[Hard Drive Failure]
        F5[Testing New Config]
        F2[VM Corruption/File Deletion]
    end

    subgraph Storage[TrueNAS ZFS]
        subgraph Pool[ZFS Pool - 40 TiB]
            V1[vdev Mirror 1]
            V2[vdev Mirror 2]
            V3[vdev Mirror 3]
        end
        subgraph Datasets[Datasets]
            NFS_Dev[devbox<br/>VM Storage]
            NFS_Backup[backups<br/>Snapshot Storage]
        end
        Pool --> Datasets
    end

    subgraph XCP[XCP-ng Hypervisor]
        VM[Sao VM]
        Scheduler[Snapshot Scheduler<br/>GFS Retention]
        BackupSR[XCP-ng Backups SR]
    end

    NFS_Dev <-->|NFS| VM
    NFS_Backup <-->|NFS| BackupSR

    Scheduler -.->|Creates snapshots of| VM
    Scheduler -.->|Stores to| BackupSR

    F1 -->|Tolerates up to 1 per vdev| Pool
    F2 -->|Restore from| BackupSR
    F5 -.->|Clone| VM
    F5 -.->|Or restore from| BackupSR

Redundancy & Disaster Recovery

The ZFS pool can tolerate up to one drive failure per mirrored vdev pair with zero downtime. XCP-ng snapshots are stored on a separate NFS dataset (backups), enabling the snapshot storage to be relocated to a different pool or remote location for additional redundancy.

Tech Stack

  • Go 1.25.3: Primary backend language
  • Node.js v18.20.8 (via NVM): JavaScript runtime
  • Neovim v0.11.4: Terminal-based editor with LSP support
  • Docker 28.5.1: Container runtime with Compose v2.40.0
  • Git 2.43.0: Version control

Key Features

Neovim Foundation (from kickstart.nvim)

  • Lazy.nvim plugin manager with LSP, Telescope, Treesitter
  • Mason for automatic tool installation
  • Smart completions with blink.cmp and LuaSnip
  • Catppuccin theme with custom yellow line numbers and relative numbering

Custom Extensions

  • Language tooling: Go (1.25.3), Node.js (v18.20.8 via NVM), Docker (28.5.1)
  • Auto-formatting: goimports + gofumpt (Go), Biome (TS/React), stylua (Lua)
  • Auto-import management: Adds missing imports on save
  • Claude Code integration: AI assistance directly in Neovim
  • VimBeGood: Vim practice game

Workflow & Productivity

  • tmux 3.4: Session management with Catppuccin theme, TPM plugins, persistent sessions
  • Git status bar: gitmux integration showing branch, staged/modified files
  • Custom keybindings: Optimized for rapid navigation and terminal mode
  • Vim-tmux-navigator: Seamless navigation between Neovim and tmux panes
  • Git integration: GitHub authentication configured
  • Docker without sudo: User added to docker group

Documentation

  • Setup: Complete installation guide, plugin configuration, and system packages
  • Keybindings: Neovim keybindings, window navigation, LSP shortcuts, and Claude Code integration

Maintained by: Mike Bros

GitHub: @Mike-Bros

Last Updated: October 17, 2025