Skip to main content
Systems are configured in the /systems/<hostname> directory. Each system requires a declaration in /systems/default.nix using the easy-hosts flake module.

​
System configuration structure

Each system follows this structure: 
systems/
└── yoursystem/
    ├── default.nix      # Main system configuration
    ├── hardware.nix     # Hardware-specific settings
    └── users.nix        # User declarations

​
Creating a new system

1

Create the system directory

Create a new directory for your system:
mkdir -p systems/yoursystem
2

Add the system configuration

Create systems/yoursystem/default.nix with your system settings:
systems/yoursystem/default.nix
{
  imports = [
    ./hardware.nix
    ./users.nix
  ];

  garden = {
    profiles = {
      workstation.enable = true;
      graphical.enable = true;
    };

    device = {
      cpu = "amd"; # or "intel"
      gpu = "amd"; # or "nvidia", "intel", null
    };
  };
}
  • workstation.enable - Development tools and utilities
  • graphical.enable - GUI applications and desktop environment
  • server.enable - Server-optimized settings
  • headless.enable - No graphical interface
3

Configure hardware

Create systems/yoursystem/hardware.nix for hardware-specific configuration:
systems/yoursystem/hardware.nix
{ modulesPath, ... }:
{
  imports = [
    (modulesPath + "/installer/scan/not-detected.nix")
  ];

  boot.initrd.availableKernelModules = [ "xhci_pci" "nvme" "usb_storage" "sd_mod" ];
  boot.kernelModules = [ "kvm-amd" ]; # or "kvm-intel"

  fileSystems."/" = {
    device = "/dev/disk/by-uuid/your-uuid-here";
    fsType = "ext4";
  };

  fileSystems."/boot" = {
    device = "/dev/disk/by-uuid/your-boot-uuid-here";
    fsType = "vfat";
  };
}
Generate hardware configuration with nixos-generate-config and copy the relevant parts.
4

Add users

Create systems/yoursystem/users.nix to declare system users:
systems/yoursystem/users.nix
{
  garden.system = {
    mainUser = "yourname";
    users = [ "yourname" ];
  };

  # Optional: Add user-specific home-manager configuration
  home-manager.users.yourname.garden = {
    profiles = {
      git.enable = true;
      shell.enable = true;
    };
  };
}
5

Register in systems/default.nix

Add your system to the hosts configuration:
systems/default.nix
{ self, inputs, ... }:
{
  config.easy-hosts = {
    hosts = {
      yoursystem = {
        arch = "x86_64";  # or "aarch64"
        class = "nixos";  # or "darwin", "iso", "wsl"
        # Optional:
        # modules = [ ./extra-module.nix ];
        # specialArgs = { someArg = "value"; };
      };
    };
  };
}

​
Configuration options

When declaring a system in systems/default.nix, you can set these options:

​
arch

  • Default: "x86_64"
  • Options: "x86_64", "aarch64"
The CPU architecture of your system.

​
class

  • Default: "nixos"
  • Options: "nixos", "darwin", "iso", "wsl"
The type of system you’re configuring:
  • nixos - Standard NixOS installation
  • darwin - macOS with nix-darwin
  • iso - Live installation media
  • wsl - Windows Subsystem for Linux

​
modules

  • Default: []
Additional NixOS/nix-darwin modules to include: 
modules = [
  ./custom-module.nix
  inputs.some-flake.nixosModules.default
];

​
specialArgs

  • Default: {}
Extra arguments passed to all modules: 
specialArgs = {
  inherit inputs;
  myVar = "custom-value";
};

​
Example configurations

# systems/myworkstation/default.nix
{
  imports = [
    ./hardware.nix
    ./users.nix
  ];

  garden = {
    profiles = {
      workstation.enable = true;
      graphical.enable = true;
    };

    device = {
      cpu = "amd";
      gpu = "amd";
    };
  };
}

​
Building and deploying

After configuring your system, you can build and deploy it: 
# Build the system
sudo nixos-rebuild switch --flake .#yoursystem

# Or build without activating
nixos-rebuild build --flake .#yoursystem
Consult the easy-hosts documentation for advanced configuration options and features.

​
Next steps

Add users

Configure user accounts for your system

Add packages

Install and configure packages

Secrets management

Set up encrypted secrets with sops-nix

Troubleshooting

Fix common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us