Sambë

Per-project sandboxed development VMs using MicroVM isolation. Each project runs in its own cloud-hypervisor VM with virtiofs file sharing and SSH access.

Features

• VM isolation: Each project runs in its own cloud-hypervisor VM
• Session persistence: Zellij inside VM preserves terminal state across detach/reattach
• Nushell: Default shell with modern CLI tooling (helix, starship, direnv, etc.)
• Per-project SSH keys: Useful for GitHub deploy keys
• Per-project tool configs: Share different configurations (Claude Code accounts, credentials, etc.) per project via virtiofs

Prerequisites

• NixOS host with KVM support
• Physical LAN interface for bridge networking
• User in kvm group

Host Setup

Add the NixOS module to your system configuration:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    sambe.url = "github:grodaus/sambe";
  };

  outputs = { nixpkgs, sambe, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        sambe.nixosModules.default
        {
          services.sambe = {
            enable = true;
            lanInterface = "enp8s0";  # Your physical LAN interface
          };
        }
      ];
    };
  };
}

Rebuild your system (nixos-rebuild switch), then log out and back in for group changes.

Usage

cd ~/projects/my-project
sambe                  # Start VM (if needed) and attach via SSH + zellij

Once inside the VM, your project files are at their original path. Detach with Ctrl+B D, reattach by running sambe again.

Commands

sambe              # Start + attach (default)
sambe start        # Start VM only
sambe attach       # Attach to running VM
sambe stop         # Stop VM
sambe restart      # Restart VM
sambe status       # Show systemd service status
sambe logs [-f]    # View VM logs
sambe ssh-key      # Display SSH public key (for deploy keys)
sambe config       # Show/set project config
sambe secrets edit # Edit encrypted project secrets

# Global VM management
sambe vms              # List all VMs
sambe vms stop <name>  # Stop VM by project name
sambe vms attach <name> # Attach to VM by project name
sambe vms logs <name>  # View logs for VM

Per-Project Tool Configs

Share different tool configurations (e.g., separate Claude Code accounts for work/personal) per project using virtiofs shares. See the tool configs guide for setup instructions.

Module Options

services.sambe = {
  enable = true;
  lanInterface = "enp8s0";       # Required: physical LAN interface
  bridge = "br0";                # Bridge name (default)
  bridgeAddress = null;          # Static IP, or null for DHCP

  vm = {
    mem = 2048;                  # Memory in MB
    vcpu = 2;                    # Virtual CPUs
  };

  # VM customization
  homeModules = [];              # home-manager modules for sandbox user
};

How It Works

• Each project gets a unique 12-char SHA256 hash of its path for systemd services, MAC address, and TAP interface
• VMs are on your LAN via bridge networking (DHCP from your router)
• /nix/store is shared read-only via virtiofs; builds happen on host via nix-daemon forwarding
• Project directory is mounted at its original path for seamless tool integration
• SSH keys are unique per-project hash (useful for GitHub deploy keys)

Documentation

Read the full documentation

• Getting Started
• Usage
• NixOS Module Options
• Architecture
• Secrets Management

Development

nix develop          # Enter dev shell
nix build            # Build package
nu test.nu           # Run tests

License

AGPL-3.0-or-later