ix new

Create a VM from an OCI image or a snapshot.

The positional picks what the machine runs. An OCI image reference (registry/repo:tag or registry/repo@sha256:...) boots that image: the control plane resolves it to a digest once, at create, pulls and unpacks it, and prints the digest it resolved. A snapshot UUID (from ix snapshot ls) restores that snapshot into a new VM. With no positional, ix new boots ix/debian:12.

A private registry needs --registry-secret, the name of an account secret (ix secret) that holds the registry credentials. --arch picks x86_64 or arm64; an image with no manifest for it fails with the architectures it does publish.

After the VM is up, attach with ix shell or run one-off commands with ix shell <vm> -- <command>.

Usage

ix new [OPTIONS] [IMAGE] [-- <COMMAND>...]

Arguments

Argument	Description
`<IMAGE>`	An OCI image reference or a snapshot UUID. Omit it to boot `ix/debian:12`

Options

Flag	Description
`-n, --name <NAME>`	Human name for the VM. Defaults to a server-assigned name
`--region <REGION>`	Region for the VM. Without one the server picks its default region; a snapshot restore defaults to the snapshot's own Reads `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`	Allocate a public IPv4 address. Not honored by snapshot restores
`--cpus <N>`	How many vCPUs the machine boots with: 2, 4, 8, 16, 32 or 64. Omit it for the platform default, which is the full ceiling and what a bare `ix new` has always booted. Ask for fewer to fit more machines on a node -- placement admits against this number, and the guest genuinely sees only these vCPUs rather than a throttled slice of more. Hotplug headroom is unchanged: the machine can still grow back to the platform ceiling without a recreate. Billing does not change. Machines are billed on what they consume, not on the size they were created at, so a smaller machine costs less only insofar as it uses less. Not honored by snapshot restores, which rebuild the captured machine's own shape.
`--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
`--arch <ARCH>`	The CPU architecture to run on: `x86_64` or `arm64`. Omit it to take the architecture of the cheapest node with capacity. Not honored by snapshot restores, which keep the architecture they were captured on One of `x86_64`, `arm64`.
`--cpu <CLASS>`	Pin the machine to a host CPU class: `epyc-5` or `graviton-5`. The machine sees that host's real CPU features and restores only on the same class. Omit it for a baseline machine on any host of the architecture. Not honored by snapshot restores One of `epyc-5`, `graviton-5`.
`--registry-secret <NAME>`	Name of an account secret (see `ix secret`) holding the registry credentials used to pull a private image. Not honored by snapshot restores
`--no-shell`	Return when the VM is ready instead of opening a shell

Examples

  ix new
  ix new ix/python:3.13
  ix new ghcr.io/owner/app@sha256:<digest>
  ix new registry.example.com/team/app:1 --registry-secret team-registry
  ix new <snapshot-id>
  ix new -- uname -a