Environment Variables in Sandboxes (CLI)

This guide explains how to set and read environment variables inside a sandbox from the abx CLI, and which execution rules apply to the commands you send. The underlying model — two independent process scopes inside every sandbox — is the same for the CLI and the Python SDK; the full description, with code examples for the SDK and the in-sandbox server, is in the SDK documentation linked at the bottom.

Looking for the CLI's own configuration variables (ABX_SANDBOX_API_KEY, ALIBABA_CLOUD_REGION_ID, ABX_LLM_API_KEY, …)? Those configure abx itself, not the sandbox. Each key has one variable. See the Configuration Reference.

Two process scopes

Inside every sandbox there are two independent process trees, each with its own environment:

The two scopes never leak into each other: a variable written through the server's /env endpoint is invisible to abx exec, and vice versa. There is no single "set env" command, by design.

Setting variables at creation time (envd scope)

abx create accepts --env / -e KEY=VALUE, repeatable. The variables are injected into the envd root process and inherited by all later commands for the lifetime of the sandbox:

abx create --template base --env MY_KEY=value --env LOG_LEVEL=debug

There is no CLI command that changes envd variables after creation. To use a different value for one command, wrap it explicitly (abx exec <sandbox-id> "sh -c 'MY_KEY=other python app.py'").

Secrets: values given with --env are sent to the platform API over HTTPS. Avoid putting secrets into shell history; prefer reading them from your own environment (--env "TOKEN=$TOKEN") and never commit them. Do not confuse this with the CLI's own credentials, which are stored with abx config set.

Reading variables

# One variable, as the process sees it (no shell needed)
abx exec <sandbox-id> "printenv MY_KEY"

# The environment reported by the in-sandbox server, optionally filtered
abx sandbox system env <sandbox-id> --filter PATH,HOME,LANG

abx sandbox system env automatically leaves out variables whose names contain TOKEN, SECRET, KEY, PASSWORD or CREDENTIAL.

Direct-exec semantics

Commands sent through envd are executed with a direct exec, not through a shell. Unquoted shell operators (|, ;, &&, ||, >, <, (...), $(...)) are detected and the command is transparently wrapped in sh -c. Everything else needs an explicit sh -c '...':

abx exec <sandbox-id> "ls /tmp | grep log"             # pipe: auto-wrapped
abx exec <sandbox-id> "sh -c 'echo \$HOME'"            # expansion: explicit sh -c
abx exec <sandbox-id> "sh -c 'ls *.py'"                # glob: explicit sh -c
abx exec <sandbox-id> "printenv HOME"                  # simplest way to read one variable

Because $VAR is not expanded, abx exec <id> "echo $VAR" prints the literal text unless your local shell expands it first — quote the whole command and use printenv VAR or sh -c instead.

Quick reference

Related SDK documentation

The complete model — per-call env dictionaries, run_code(envs=), the @sandbox(envs=) decorator, the server's GET/POST /env endpoints (read, set, protected and redacted variables) and recommended patterns — is documented in the SDK's Environment Variables guide in the python-sdk repository.