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 in the dashboard

On Deploy and Docker, use the Environment Variables field. Add one key/value pair per row. Empty rows are ignored.

This is the supported path today. The public REST launch endpoint (POST /api/v1/instance/launch) does not currently accept env_vars — use the website (or wait for that field to land on the public API).

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

Launch-time values are the source of truth. ~/.env gets rewritten from them 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 path 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 these values like the plaintext dotenv file they become on the VM. If a value should not be readable by whoever holds the VM, do not put it in environment variables.