Skip to main content

Environment Variables

Pass secrets, tokens, and configuration to your VM at launch time. Values you provide land in a .env file inside the VM and get refreshed on every boot.

How to set env vars at launch

When you launch a VM through the API, include an env_vars object in your launch request body. Example:

{
  "product_name": "your-product-name",
  "region_name": "your-region",
  "ssh_key_names": ["your-ssh-key"],
  "env_vars": {
    "HF_TOKEN": "hf_...",
    "OPENAI_API_KEY": "sk-...",
    "WANDB_PROJECT": "my-experiment"
  }
}

Both keys and values are strings. Full API reference: see the launch endpoint documentation.

Where the file appears on the VM

After the VM boots, your env vars are written to a .env file in the home directory of the VM's default user:

cat /home/Ubuntu/.env

The path is case-sensitive. On Ubuntu images the user is Ubuntu (capital U), so the file lives at /home/Ubuntu/.env.

File format

The file is written in standard dotenv format — one entry per line, values quoted:

HF_TOKEN="hf_..."
OPENAI_API_KEY="sk-..."
WANDB_PROJECT="my-experiment"

Special characters in values (newlines, carriage returns, backslashes, double quotes) are escaped so the file is safe to source from a shell.

How to use the values in your apps

Shell (auto-export every variable):

set -a
source ~/.env
set +a

Python (with python-dotenv):

from dotenv import load_dotenv
load_dotenv()
import os
print(os.environ["HF_TOKEN"])

Docker (pass the file directly):

docker run --env-file ~/.env your-image

The file is refreshed on every boot

The API is the source of truth. ~/.env gets rewritten from your launch-time values every time the VM boots.

This means:

  • Manual edits to the file do not survive a reboot. If you edit ~/.env on the VM and reboot, your changes are overwritten.
  • To change values, launch a new VM with the updated env_vars. There is no update endpoint for env vars on an existing VM.
  • If you launch without env_vars, no .env file is written. If a .env file already exists from a previous boot with env vars, it is removed on the next boot.

What you cannot use as keys

The following are rejected by the API at launch time:

  • Reserved keys: PATH, HOME, USER, SHELL, PWD, OLDPWD, IFS, PS1, PS2, TERM, LANG, LC_ALL.
  • Reserved prefixes: LD_ (dangerous with dynamic linkers), MC_ (reserved for Massed Compute system flags).
  • Invalid key names: keys must start with a letter or underscore and contain only letters, digits, and underscores. Max 64 characters.

Other limits:

  • Max 64 entries per VM.
  • Max 4 KiB per value.
  • Max 16 KiB total across all env vars.
  • Values must not contain NUL bytes.

Storage and privacy

  • At rest: values are encrypted server-side in the Massed Compute API database using AES-256-GCM.
  • In transit: sent over TLS.
  • On the VM: the .env file is plaintext, readable by the VM's default user. Anyone with access to that user can read the values.

Treat env_vars like the plaintext dotenv file it will become on the VM. If a value should not be readable by whoever holds the VM, do not put it in env_vars.