Skip to main content

​
Overview

Environment variable sets (env sets) are named collections of key-value pairs that get injected into VMs at creation time via cloud-init. Use them to pass secrets, config, and connection strings without baking them into images.

​
How injection works

Variables are written to two files on the VM. Both are needed because Linux reads environment variables from different places depending on context: Injection happens during bootcmd (early boot), so variables are available before any services start.

​
Lifecycle

Variables are baked in at creation time, not live-synced.
  • Updating an env set after creation does not affect already-running VMs.
  • Deleting an env set does not affect VMs that were created with it.
  • To apply updated variables, create a new VM with the updated env set.

​
Limits

Keys must be valid POSIX names (A-Z, a-z, 0-9, _, starting with a letter or underscore). Values cannot contain newlines, carriage returns, double quotes, or null bytes.

​
Encryption

Env set variables are encrypted at rest using AES-256-GCM. Decryption happens in the application layer only when variables are read — they are never stored in plaintext in the database.

​
Snapshots

Environment variables are written to disk files on the VM. When you snapshot a VM with images new, these files are captured in the image. Any secrets in env sets will persist in the resulting snapshot. Rotate secrets after saving an image if they should not be reused.
When a VM is created from an image, stale environment variables from the snapshot are automatically purged and replaced with the new VM’s env set (if any).

​
NixOS

Env sets work on NixOS images: variables are delivered at boot into user-writable files — ~/.machine0/env.sh (sourced by login shells and every zsh invocation) and ~/.ssh/environment (applied by sshd to every SSH session, regardless of shell). Older NixOS image versions ignore env sets until the image updates.

​
Commands

See CLI reference.