Environment variables in Celesto sandboxes

You can pass configuration values, API keys, and other settings into a sandbox using environment variables. Celesto supports two approaches: setting variables when you create the sandbox, or adding them at runtime while the sandbox is running. The same Python API (env_vars=, vm.set_env_vars(...), vm.unset_env_vars(...), vm.list_env_vars(...)) works for both Linux and Windows guests. On Linux the variables are written to /etc/profile.d/smolvm_env.sh and picked up by new login shells; on Windows they’re written to HKCU\Environment and picked up by new processes. See Windows guests below for the details specific to Windows.

Setting variables at boot

Set environment variables when creating a VM:

from celesto import Celesto, VMConfig
from celesto import ImageBuilder, SSH_BOOT_ARGS

builder = ImageBuilder()
kernel, rootfs = builder.build_alpine_ssh()

config = VMConfig(
    vm_id="env-vm",
    vcpu_count=1,
    memory=512,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
    env_vars={  # Variables injected after boot
        "APP_MODE": "production",
        "DATABASE_URL": "postgres://localhost:5432/mydb",
        "API_KEY": "secret-key-value",
    },
)

with Celesto(config) as vm:
    # Variables are automatically injected during start()
    result = vm.run("echo $APP_MODE")
    print(result.output)  # "production"

How it works

When env_vars is set in VMConfig:

VM boots normally
Celesto waits for SSH to become available
Variables are written to /etc/profile.d/smolvm_env.sh
All subsequent login shells source these variables

Environment variable injection requires an SSH-capable image. Use ImageBuilder or auto-config mode to ensure your image supports this feature.

Setting variables at runtime

You can also add, update, and remove variables while a sandbox is running:

from celesto import Celesto

with Celesto() as vm:
    # Set environment variables
    vm.set_env_vars({"APP_MODE": "dev", "DEBUG": "1"})

    # Use them in commands
    result = vm.run("echo APP_MODE=$APP_MODE DEBUG=$DEBUG")
    print(result.output)  # "APP_MODE=dev DEBUG=1"

    # List current variables
    env_vars = vm.list_env_vars()
    print(env_vars)  # {"APP_MODE": "dev", "DEBUG": "1"}

    # Remove a variable
    removed = vm.unset_env_vars(["DEBUG"])
    print(removed)  # {"DEBUG": "1"}

    # Verify it's gone
    result = vm.run("echo DEBUG=$DEBUG")
    print(result.output)  # "DEBUG="

Windows sandboxes

Environment variables work for Windows sandboxes too, using the same API. The only difference is where the values are stored.

from celesto import Celesto

with Celesto(
    os="windows",
    image="~/.smolvm/images/win11.qcow2",
    ssh_user="smolvm",
    ssh_password="smolvm",
    env_vars={"OPENAI_API_KEY": "sk-..."},
) as vm:
    vm.wait_for_ssh()

    # Fresh SSH session, so the new value is visible.
    print(vm.run("$env:OPENAI_API_KEY").stdout.strip())

    vm.set_env_vars({"DEBUG": "1"})
    print(vm.list_env_vars())
    vm.unset_env_vars(["DEBUG"])

How it works on Windows:

Celesto runs [Environment]::SetEnvironmentVariable(name, value, 'User') over SSH, which writes the value into the HKCU\Environment registry hive — the standard per-user environment store on Windows.
New processes inherit the updated environment automatically. The SSH session that issued the change does not — vm.run(...) opens a fresh session every call, so the next vm.run(...) sees the new value.
Celesto tracks which keys it owns via a SMOLVM_ENV_MANAGED_KEYS sentinel value. list_env_vars() and unset_env_vars() only ever touch variables Celesto set; anything you configured inside Windows yourself is left untouched.
Values are passed through verbatim — spaces, embedded quotes, and special characters are escaped safely by Celesto before the PowerShell call.

Variable changes are visible to new processes, not the current one. Inside a single SSH session you can verify the change by spawning a fresh process — for example start-process powershell -wait, or simply rely on the fact that the next vm.run(...) call will see the new value.

Method reference

set_env_vars()

def set_env_vars(
    self,
    env_vars: dict[str, str],
    *,
    merge: bool = True,
) -> list[str]:
    """Set environment variables on a running VM.

    Variables are persisted in /etc/profile.d/smolvm_env.sh and
    affect new SSH sessions/login shells.

    Args:
        env_vars: Key/value pairs to set.
        merge: If True (default), merge with existing variables.

    Returns:
        Sorted variable names present after update.
    """

Example:

# Merge with existing variables (default)
vm.set_env_vars({"NEW_VAR": "value"})

# Replace all variables
vm.set_env_vars({"ONLY_VAR": "value"}, merge=False)

list_env_vars()

def list_env_vars(self) -> dict[str, str]:
    """Return Celesto-managed environment variables for a running VM."""

Example:

env_vars = vm.list_env_vars()
for key, value in env_vars.items():
    print(f"{key}={value}")

unset_env_vars()

def unset_env_vars(self, keys: list[str]) -> dict[str, str]:
    """Remove environment variables from a running VM.

    Args:
        keys: Variable names to remove.

    Returns:
        Mapping of removed keys to their previous values.
    """

Example:

# Remove multiple variables
removed = vm.unset_env_vars(["VAR1", "VAR2"])
print(f"Removed: {removed}")

Complete example

From examples/env_injection.py:

from celesto import Celesto

def main() -> int:
    with Celesto() as vm:
        print(f"VM started: {vm.vm_id}")

        print("\n1) Set environment variables")
        vm.set_env_vars({"APP_MODE": "dev", "DEBUG": "1"})
        print(vm.list_env_vars())

        print("\n2) Use env vars in a command")
        # vm.run() opens a fresh SSH session, so new values are available
        print(vm.run("echo APP_MODE=$APP_MODE DEBUG=$DEBUG").output)

        print("\n3) Remove one variable")
        removed = vm.unset_env_vars(["DEBUG"])
        print(f"Removed: {removed}")
        print(vm.list_env_vars())

    print("\nDone.")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

Passing host environment into the sandbox

You can forward environment variables from your host machine into the sandbox. This is useful for sharing API keys without hardcoding them:

import os
from celesto import Celesto, VMConfig
from celesto import ImageBuilder, SSH_BOOT_ARGS

def collect_host_env() -> dict[str, str]:
    """Collect API keys from host environment."""
    env_vars = {}

    if api_key := os.getenv("OPENAI_API_KEY"):
        env_vars["OPENAI_API_KEY"] = api_key

    if api_key := os.getenv("ANTHROPIC_API_KEY"):
        env_vars["ANTHROPIC_API_KEY"] = api_key

    return env_vars

builder = ImageBuilder()
kernel, rootfs = builder.build_alpine_ssh()

config = VMConfig(
    vm_id="host-env-vm",
    vcpu_count=1,
    memory=512,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
    env_vars=collect_host_env(),  # Inject host environment
)

with Celesto(config) as vm:
    result = vm.run("env | grep API_KEY")
    print(result.output)

This pattern is used in examples/openclaw.py to inject OPENROUTER_API_KEY and OPENAI_API_KEY from the host.

Host-side variables Celesto reads

A few environment variables on your host machine change how Celesto itself behaves. Set these in your shell, not inside the sandbox.

Celesto behavior

string

Override the virtual machine monitor Celesto uses. Accepts firecracker, qemu, or auto (the default). On macOS the default is QEMU; on Linux it is Firecracker.

string

Folder containing the Firecracker binary on Linux. When set, Celesto installs to and looks for Firecracker only in this folder. When unset, celesto setup installs to ~/.smolvm/bin, and Celesto discovery checks PATH first, then ~/.smolvm/bin. Set this when you install Firecracker to a custom folder that is not on PATH:

export SMOLVM_FIRECRACKER_DIR="$HOME/.local/bin"
celesto setup

The one-off equivalent is celesto setup --firecracker-dir <dir>, which overrides this variable for that run.

string

default:"1"

Controls the published-image fast path. On by default. Set to 0, false, or no to force Celesto to build images locally instead of downloading pre-built ones. Useful when you’re testing changes to a preset’s install script.

string

Show the guest kernel’s full boot log on the serial console. Off by default — Celesto appends quiet to the kernel command line so boots stay fast and clean. Set to 1, true, yes, or on to drop quiet and surface every kernel message, which is the first thing to try when a sandbox hangs during start or panics before the agent answers.

SMOLVM_VERBOSE_BOOT=1 celesto sandbox create --name verbose-boot

This only affects sandboxes that use the default low-latency boot profile (MICROVM_DIRECT). It does not change behaviour after the guest is up.

Coding-agent presets

When you launch a coding-agent preset, Celesto forwards a small list of host environment variables into the sandbox so the agent can authenticate without an extra login step.

string

Forwarded to presets that talk to OpenAI APIs, including codex, opencode, and openclaw.

string

Forwarded to the openclaw and opencode presets and any preset that supports OpenRouter.

string

Forwarded to the opencode preset for Anthropic models.

string

Forwarded to the opencode preset for Google models. GEMINI_API_KEY is forwarded as well.

string

Forwarded to the opencode preset for Amazon Bedrock. AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, and AWS_REGION are forwarded together with it.

string

Forwarded to the openclaw preset. OpenClaw rejects boot with a clear error message if neither this nor OPENCLAW_GATEWAY_PASSWORD is set, so populate one of the two before running celesto openclaw start.

string

Alternative to OPENCLAW_GATEWAY_TOKEN for the openclaw preset. Use whichever credential type matches your OpenClaw deployment.

Set these variables in the shell that runs celesto openclaw start. Celesto forwards the selected values into that sandbox, but it does not copy ~/.openclaw/openclaw.json, ~/.openclaw/.env, or other OpenClaw state from your machine.

Variable validation

Celesto validates environment variable keys:

from celesto.env import validate_env_key

# Valid keys
validate_env_key("MY_VAR")      # OK
validate_env_key("_PRIVATE")    # OK
validate_env_key("VAR_123")     # OK

# Invalid keys
validate_env_key("")            # ValueError: cannot be empty
validate_env_key("123VAR")      # ValueError: must start with letter or _
validate_env_key("MY-VAR")      # ValueError: only [A-Za-z0-9_] allowed

Keys must match the pattern: [A-Za-z_][A-Za-z0-9_]*

Persistence details

File location

Variables are stored in /etc/profile.d/smolvm_env.sh inside the guest:

# Inside the VM
$ cat /etc/profile.d/smolvm_env.sh
#!/bin/sh
# Celesto managed environment variables

export APP_MODE='production'
export DATABASE_URL='postgres://localhost:5432/mydb'

Atomic updates

All writes are atomic (write to temp file → mv into place) to prevent partial updates on failure.

Quoting and escaping

Celesto uses shlex.quote() to safely handle special characters:

vm.set_env_vars({
    "MESSAGE": "Hello, World!",
    "PATH_VAR": "/usr/local/bin:/usr/bin",
    "COMPLEX": "value with 'quotes' and spaces",
})

# All values are safely quoted in the generated shell script

Use cases

Configuration management

config = VMConfig(
    vm_id="app-vm",
    # ... other config ...
    env_vars={
        "DATABASE_URL": "postgres://db:5432/app",
        "REDIS_URL": "redis://cache:6379",
        "LOG_LEVEL": "info",
    },
)

Secret injection

import os

with Celesto() as vm:
    # Inject secrets from host environment or secrets manager
    vm.set_env_vars({
        "API_KEY": os.getenv("API_KEY", "default-key"),
        "DB_PASSWORD": get_secret("db-password"),
    })

    vm.run("my-application")

Dynamic configuration updates

with Celesto() as vm:
    # Start in dev mode
    vm.set_env_vars({"APP_MODE": "dev"})
    vm.run("start-app")

    # Switch to production mode
    vm.set_env_vars({"APP_MODE": "production"})
    vm.run("restart-app")

Troubleshooting

Variables not available

If variables don’t appear in your commands:

Verify SSH support

if not vm.can_run_commands():
    print("VM does not support SSH - cannot inject variables")

Check the file was created

result = vm.run("cat /etc/profile.d/smolvm_env.sh")
print(result.output)

Ensure you're using a login shell

Variables are only available in login shells:

# This works - uses login shell (default)
vm.run("echo $MY_VAR", shell="login")

# This may not work - raw execution
vm.run("echo $MY_VAR", shell="raw")

Next steps

Custom images

Build images with pre-baked environment configuration

AI agent integration

Use environment variables for agent configuration

Port forwarding

Expose services configured via environment variables

Get Started

Features

Guides

Architecture

Operations

Environment variables in Celesto sandboxes

Setting variables at boot

How it works

Setting variables at runtime

Windows sandboxes

Method reference

set_env_vars()

list_env_vars()

unset_env_vars()

Complete example

Passing host environment into the sandbox

Host-side variables Celesto reads

Celesto behavior

Coding-agent presets

Variable validation

Persistence details

File location

Atomic updates

Quoting and escaping

Use cases

Configuration management

Secret injection

Dynamic configuration updates

Troubleshooting

Variables not available

Next steps

Custom images

AI agent integration

Port forwarding

​Setting variables at boot

​How it works

​Setting variables at runtime

​Windows sandboxes

​Method reference

​set_env_vars()

​list_env_vars()

​unset_env_vars()

​Complete example

​Passing host environment into the sandbox

​Host-side variables Celesto reads

​Celesto behavior

​Coding-agent presets

​Variable validation

​Persistence details

​File location

​Atomic updates

​Quoting and escaping

​Use cases

​Configuration management

​Secret injection

​Dynamic configuration updates

​Troubleshooting

​Variables not available

​Next steps

Custom images

AI agent integration

Port forwarding

Setting variables at boot

How it works

Setting variables at runtime

Windows sandboxes

Method reference

set_env_vars()

list_env_vars()

unset_env_vars()

Complete example

Passing host environment into the sandbox

Host-side variables Celesto reads

Celesto behavior

Coding-agent presets

Variable validation

Persistence details

File location

Atomic updates

Quoting and escaping

Use cases

Configuration management

Secret injection

Dynamic configuration updates

Troubleshooting

Variables not available

Next steps