> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machine0.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

## 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.

```bash theme={"theme":"css-variables"}
machine0 env new production
machine0 env set production DATABASE_URL=postgres://... REDIS_URL=redis://...
machine0 new my-vm --env production
```

## 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:

| File                             | Read by                                                   |
| -------------------------------- | --------------------------------------------------------- |
| `/etc/environment`               | PAM and systemd (services, cron jobs, non-login sessions) |
| `/etc/profile.d/machine0-env.sh` | Login shells (SSH sessions)                               |

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

| Limit             | Value |
| ----------------- | ----- |
| Variables per set | 100   |
| Sets per user     | 50    |
| Value size        | 4 KB  |
| Total set size    | 64 KB |

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

<Warning>
  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.
</Warning>

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

<Warning>
  Env sets are not supported with NixOS images. NixOS uses declarative Nix configuration instead of cloud-init.
</Warning>

## Commands

See [CLI reference](/cli/env).