ix

ix new

Create a VM from a template, a snapshot, or a flake

Usage: ix new [OPTIONS] [TARGET]

Create a VM from a template, a snapshot, or a flake.

The target's shape picks the mode. default (or no target) boots the platform base template. A template name boots that template: ix templates ls shows the region's templates. A snapshot UUID (from ix snapshot ls) restores that snapshot into a new VM. A flake reference (github:owner/repo, with an optional #config) is a template source: any flake whose configuration evaluates to a NixOS system. The first ix new of a rev builds it inside the VM being created and caches the result as a bootable template per region; later runs of the same rev boot the cached template in seconds. --fresh bypasses the cache and rebuilds.

The imperative counterpart to ix apply: new gives you a machine now, apply converges a machine on a project's configuration. After the VM is up, attach with ix shell or run one-off commands with ix shell <vm> -- <command>.

arguments

• <TARGET> default for the base template, a template name, a snapshot UUID, or a flake ref (github:owner/repo[#config]) default: default

options

• -n, --name <NAME> Human name for the VM. Defaults to a server-assigned name
• --region <REGION> Region for the VM. A snapshot restore defaults to the snapshot's own region env: IX_REGION
• --env <NAME=VALUE> Set an environment variable inside the VM; repeat for several. Not for secrets. Not honored by snapshot restores
• --l7-proxy-port <PORT> Publish a port through the HTTPS proxy. Not honored by snapshot restores
• --ipv4 <IPV4> Allocate a public IPv4 address. Not honored by snapshot restores default: false
• --secret-env <KEY=ENV> Attach a stored secret as an environment variable; repeat for several
• --secret-file <KEY=PATH[:OWNER[:MODE]]> Attach a stored secret as a file under /run/secrets; repeat for several
• --group <SLUG> Join an east-west group at creation; repeat for several. Not honored by snapshot restores
• --fresh <FRESH> Rebuild a template instead of using the cached build. Flake targets only default: false
• --no-shell <NO_SHELL> Return when the VM is ready instead of opening a shell default: false
• --message-format <MESSAGE_FORMAT> Error format one of: human, short, json default: human

examples

  ix new
  ix new <template-name>
  ix new <snapshot-id>
  ix new github:owner/repo
  ix new github:owner/repo#web