NixOS on InstaVM: reproducible dev environments you can snapshot and restore

InstaVM has always been about one thing: give an AI agent (or a human) a fast, isolated microVM to run untrusted code in, then throw it away (unless you want longer vms). Each sandbox is a Firecracker VM that boots in about a second, runs your command, and disappears.

The default sandbox is great for "run this script." But the moment you want a real development environment, with a specific toolchain, pinned versions, the same setup on every machine, a prebuilt image starts to feel rigid. You apt install a thing, it works today, and three weeks later the base image moved and it doesn't. Doesn't happen very frequently but if your provider says "we will out for a couple of hours to update the OS" - you kind of dread that.

So we added a new environment: image_variant="nix-dev", a real NixOS(https://nixos.org/) guest, with full Nix (flakes), where the whole operating system is described as code. Same Firecracker isolation, same warm pool, same one-second boot, same SDK and CLI. Just a reproducible OS on top.

Honestly, nix-dev is less a feature for us and more a thing we believe. Most sandbox platforms hand you a fixed menu of runtimes and hope one of them fits. We'd rather hand you the dial. Your environment is yours to define, as code, not something you negotiate with a base image we picked for you.

What nix-dev adds to the normal sandbox

nix-dev isn't a replacement for the standard sandbox. It's a sibling. Everything you already rely on stays exactly the same; you just get a declarative, reproducible OS underneath.

So what actually changes? In the standard sandbox your environment is a prebuilt Docker rootfs and you mutate it "imperatively" at runtime. You can snapshot it and reuse. Don't get me wrong, that's a fine workflow too. But a better way is, in nix-dev your environment is a flake.nix, pinned by a flake.lock to exact hashes, and every package you add is reproducible and rollback-able. Also auditable, every developer knows what has been installed etc, they can change it if they want!

Getting started

You can drive nix-dev from the Python SDK or the CLI. Here's both, one after the other.

From the SDK

nix-dev is just another image_variant:

from instavm import InstaVM

client = InstaVM(api_key=API_KEY, base_url="https://api.instavm.io")

# Boot a real NixOS sandbox
vm = client.vms.create(image_variant="nix-dev")
print("booted", vm["vm_id"])

# Check Nix is there. One detail: /execute defaults to Python,
# so pass language="bash" for shell commands.
client.execute("nix --version", language="bash")

Installing a package has two small gotchas that bit us, so we'll save you the detour. First, nixpkgs flake commands need the experimental-features flag turned on explicitly, and you want nix profile add (not the deprecated nix-env -i):

client.execute(
    "nix --extra-experimental-features 'nix-command flakes' "
    "profile add nixpkgs#cowsay",
    language="bash",
)

Second, nix profile add drops binaries into ~/.nix-profile/bin, and a fresh /execute shell doesn't have that directory on PATH yet, so prepend it before you call the tool:

client.execute(
    "export PATH=$HOME/.nix-profile/bin:$PATH && cowsay 'reproducible!'",
    language="bash",
)
#  _______________
# < reproducible! >
#  ---------------
#         \   ^__^

From the CLI

The `instavm` CLI drives the same lifecycle. As of v0.24.0 you can boot a nix-dev VM straight from the CLI, snapshot it once, and let anyone boot an identical copy on demand:

# Boot a NixOS (nix-dev) sandbox directly
instavm create --image-variant nix-dev

# Snapshot a running nix-dev VM into a reusable base
instavm snapshot create <vm_id> --name nix-dev-base

# List your snapshots to grab the ID
instavm snapshot ls

# Boot a fresh VM straight from that snapshot (your packages are already there)
instavm create --snapshot <snapshot_id>

# Drop into a shell, or attach an interactive PTY
instavm connect <vm_id>
instavm pty <vm_id>

Bake the environment once, then everyone (a teammate or an agent) boots the exact same box.

Snapshot and restore

A nix-dev VM does everything a standard VM does: you can freeze it into a snapshot, then boot fresh copies from that snapshot, packages and all.

# Boot a nix-dev VM and install a package
vm = client.vms.create(image_variant="nix-dev")
client.execute(
    "nix --extra-experimental-features 'nix-command flakes' "
    "profile add nixpkgs#cowsay",
    language="bash",
)

# Freeze it into a reusable snapshot
snap = client.vms.snapshot(vm["vm_id"], name="cowsay-ready")
snapshot_id = snap["snapshot_id"]

# Boot a brand-new VM from the snapshot (the package is already there)
restored = client.vms.create(snapshot_id=snapshot_id)

# Verify it survived the round trip (add the nix profile to PATH first)
out = client.execute(
    "export PATH=$HOME/.nix-profile/bin:$PATH && cowsay moo && command -v cowsay",
    language="bash",
)
print(out["stdout"])   # the cow moos ✓

(btw, you can also use CLI instead of above python code)

The flow, conceptually:

flowchart LR
  A["vms.create
image_variant=nix-dev"] --> B["nix profile add
cowsay"]
  B --> C["vms.snapshot
flatten ext4 upper"]
  C --> D["vms.create
snapshot_id=…"]
  D --> E["cowsay present ✓"]

The snapshot flattens that writable ext4 store and re-attaches it on restore, which is why your installed packages reappear in the new VM, even though / was throwaway tmpfs.

When should you reach for nix-dev?

• Reproducible toolchains: pin an exact compiler, interpreter, or CLI set in a flake and get the same box every single time.
• Agent dev loops: give an AI agent a real OS it can nix profile add into, snapshot the good state, and fork experiments from it cheaply.
• "Golden environment" templates: configure once, snapshot, and let everyone (or every job) boot an identical copy.
• Anything that hates drift: if "works on my machine" has ever cost you a day, declarative beats imperative.
• Devs already use nixos

And if you just need to run a script in a fast, isolated VM, the standard sandbox pool is still right there. nix-dev is the same sandbox, with a reproducible OS, and the confidence that a snapshot will bring your whole environment along for your work. This is great to share between your team members when you expect reproducibility.

Other platforms decide your environment for you; we'd rather hand you the definition and get out of the way. Whether you stay on the standard pool or describe your own world in a flake, the deal is the same: the environment is yours, as code. Try nix-dev, and tell us what you build with it :)