devenv-machines-install(1)

📦 version 2.4.0, in nixpkgs unstable

💅 devenv-machines-install — the glow-up guide

okay so real talk, bestie: this is the devenv-machines-install(1) page from the General Commands Manual, and it's literally the "install NixOS on a brand new box" command. no cap.

✨ NAME ✨

devenv-machines-install — Install NixOS on a fresh target: kexec into the installer, partition via disko, copy the closure, install the bootloader, reboot.

the official docs vibe lives here: https://devenv.sh/machines/#installing-on-a-fresh-host

🎀 SYNOPSIS 🎀

devenv machines install [--max-concurrent] [--use-machines-as-builders]
[--phases] [--stop-after-disko] [--no-reboot] [--disko-mode]
[--user-config] [--from] [-o|--override-input] [-O|--option]
[-j|--max-jobs] [-u|--cores] [-s|--system] [-i|--impure] [--no-impure]
[--offline] [--nix-option] [--nix-debugger] [-c|--clean] [-P|--profile]
[--reload] [--no-reload] [--shell] [--eval-cache] [--no-eval-cache]
[--refresh-eval-cache] [--refresh-task-cache] [--secretspec-provider]
[--secretspec-profile] [--trace-to] [-v|--verbose] [-q|--quiet] [--tui]
[--no-tui] [-h|--help] <NAMES>

🦋 DESCRIPTION 🦋

so the whole serve, okay? this command installs NixOS on a fresh target machine and it does the entire main-character arc for you:

  1. kexec into the installer
  2. partition via disko
  3. copy the closure
  4. install the bootloader
  5. reboot

and yes, there's a whole webpage about it: https://devenv.sh/machines/#installing-on-a-fresh-host

💖 OPTIONS 💖

  • --max-concurrent <N> — how many machines you're installing at the same time. defaults to unbounded (yes, chaos is the default 😭). pass 1 if you want them sequential and chill.
  • --use-machines-as-builders — treat every machine that has a reachable target.host as a candidate Nix remote builder, for those cross-architecture builds. very giving "share the aux" energy.
  • --phases <PHASES> — comma-separated list of install phases to actually run: kexec, facter, disko, install, reboot. default is all phases. ⚠️ conflicts with --stop-after-disko and --no-reboot.

possible values:

  • kexec
  • facter
  • disko
  • install
  • reboot
  • --stop-after-disko — stops right after the disko phase (equivalent to --phases kexec,facter,disko). leaving early, respectfully.
  • --no-reboot — runs all phases except reboot (equivalent to --phases kexec,facter,disko,install). the machine stays up, you stay up.
  • --disko-mode <DISKO_MODE> [default: disko] — the disko partitioning mode: disko (default, destroy/create/mount), format (create the missing storage structures without the destroy phase), mount (mount existing filesystems).

possible values:

  • disko: Destroy existing partitions, create new layout, mount (default)
  • format: Create partitions without destroying existing ones
  • mount: Mount existing partitions without touching the layout
  • --user-config <USER_CONFIG> — use this user configuration file instead of the XDG default.
  • <NAMES> — the machine names to install. at least one name is required — unlike deploy, install never runs bare because it wipes disks 💀 fr fr do not skip this.

🔥 INPUT OVERRIDES 🔥

  • --from <FROM> — source for devenv.nix.

can be either a filesystem path (with a path: prefix) or a flake input reference.

examples:

--from github:cachix/devenv
--from github:cachix/devenv?dir=examples/simple
--from path:/absolute/path/to/project
--from path:./relative/path
  • -o, --override-input <NAME> <URI> — override inputs in devenv.yaml.

examples:

--override-input nixpkgs github:NixOS/nixpkgs/nixos-unstable
--override-input nixpkgs path:/path/to/local/nixpkgs
  • -O, --option <OPTION:TYPE> <VALUE> — override configuration options with typed values.

OPTION must include a type: <attribute>:<type>. supported types: string, int, float, bool, path, pkg, pkgs.

list types (pkgs) append to existing values by default. add a ! suffix to replace instead: pkgs!

examples:

--option languages.rust.channel:string beta
--option services.postgres.enable:bool true
--option languages.python.version:string 3.10
--option packages:pkgs "ncdu git"       (appends to packages)
--option packages:pkgs! "ncdu git"      (replaces all packages)

🌈 NIX OPTIONS 🌈

  • -j, --max-jobs <MAX_JOBS> — max number of Nix builds running concurrently.

defaults to 1/4 of available CPU cores (minimum 1).

  • -u, --cores <CORES> — number of CPU cores available to each build.

defaults to available cores divided by max-jobs (minimum 1).

  • -s, --system <SYSTEM> — override the target system.

defaults to the host system (e.g. aarch64-darwin, x86_64-linux).

  • -i, --impure — relax the hermeticity of the environment.
  • --no-impure — force a hermetic environment, overriding config.
  • --offline — disable substituters and consider all previously downloaded files up-to-date.
  • --nix-option <NAME> <VALUE> — pass additional options to nix commands.

these options are passed directly to Nix using the --option flag. see man nix.conf for the full list of available options.

examples:

--nix-option sandbox false
--nix-option keep-outputs true
--nix-option system x86_64-darwin
  • --nix-debugger — enter the Nix debugger on failure. (character development arc, but for flakes 🫶)

🐚 SHELL OPTIONS 🐚

  • -c, --clean [<CLEAN>...] — ignore existing environment variables when entering the shell. pass a list of comma-separated environment variables to let through.
  • -P, --profile <PROFILES> — activate one or more profiles defined in devenv.nix.

profiles let you define different configurations that can be merged with your base configuration.

see https://devenv.sh/profiles for more information.

examples:

--profile python-3.14
--profile backend --profile fast-startup
  • --reload — enable auto-reload when config files change (default).
  • --no-reload — disable auto-reload when config files change.
  • --shell <SHELL_TYPE> — shell to use for interactive sessions (bash, zsh, fish, nu).

possible values:

  • bash
  • zsh
  • fish
  • nu

⭐ CACHE OPTIONS ⭐

  • --eval-cache — enable caching of Nix evaluation results (default).
  • --no-eval-cache — disable caching of Nix evaluation results.
  • --refresh-eval-cache — force a refresh of the Nix evaluation cache.
  • --refresh-task-cache — force a refresh of the task cache.

🍓 SECRETSPEC OPTIONS 🍓

  • --secretspec-provider <SECRETSPEC_PROVIDER> — override the secretspec provider.
  • --secretspec-profile <SECRETSPEC_PROFILE> — override the secretspec profile.

hush hush 🤫

🧚 TRACING OPTIONS 🧚

  • --trace-to <TRACE_TO> — enable tracing and set output destination(s). can be repeated for multiple outputs.

syntax: [format:]destination

examples:

--trace-to stderr                              # json to stderr
--trace-to pretty:stderr                       # pretty format to stderr
--trace-to json:file:/tmp/trace.json           # JSON to file
--trace-to otlp-grpc                           # OTLP gRPC to default endpoint
--trace-to otlp-grpc:http://collector:4317     # OTLP gRPC to custom endpoint

multiple outputs:

--trace-to pretty:stderr --trace-to json:file:/tmp/t.json

destinations: stdout, stderr, file:<path>, http(s)://<host>:<port>. formats: json (default), pretty, full, otlp-grpc, otlp-http-protobuf, otlp-http-json.

when format is omitted, defaults to json. tracing is disabled by default.

[env: DEVENV_TRACE_TO=] (comma-separated) [env: DEVENV_TRACE_DEFAULT_TO=] (comma-separated, used only when no explicit tracing is configured; set to empty string to suppress)

ok important: the env var one is only consulted when nothing explicit is configured — and an empty string is how you suppress it entirely. iykyk 💅

👑 GLOBAL OPTIONS 👑

  • -v, --verbose — enable additional debug logs.
  • -q, --quiet — silence all logs. (not a single peep 🙈)
  • --tui <TUI> — enable the interactive terminal interface (default when interactive).

possible values:

  • true
  • false
  • --no-tui — disable the interactive terminal interface.
  • -h, --help — print help (see a summary with -h).

🌸 SEE ALSO 🌸

tbh the page doesn't list a SEE ALSO section, but the description points you at https://devenv.sh/machines/#installing-on-a-fresh-host and the profiles note points at https://devenv.sh/profiles — go read those, they ate 💖

and that's the whole thing, bestie 🫶 this page was served to you from the General Commands Manual, footer edition: source/version <rainbow>install</rainbow> and its date, matched up right against devenv-machines-install(1) — iconic, no notes, periodt. ✨💜

📦 where this page comes from