Documentation Index
Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
Use this file to discover all available pages before exploring further.
Use this page as a quick reference for environment variable scopes in Sandboxes.
For endpoint-level and workflow details, also see Execute Commands and PTY Sessions.
| Scope | Use this when | API surface |
|---|
| Command-scoped | Variables should apply to one command only | tl sbx exec --env KEY=VALUE ..., sandbox.run(..., env=...) |
| PTY-scoped | Variables should apply to one interactive PTY session only | tl sbx ssh --env KEY=VALUE ..., create_pty(..., env=...) / createPty({ env: ... }) |
Prerequisites
- You have the
tl CLI installed and authenticated.
- You have a running sandbox connection in the CLI, Python, or TypeScript.
- You already set
TENSORLAKE_API_KEY in your local environment.
1. Env vars for a single command in a sandbox
Use command-scoped env when values should not persist across all sandbox processes.
# Set command-scoped env vars with repeated --env flags
tl sbx exec <sandbox-id-or-name> \
--env MODE=prod \
--env DEBUG=0 \
bash -lc 'echo MODE=$MODE DEBUG=$DEBUG'
# Same pattern when creating a one-shot sandbox with tl sbx run
tl sbx run \
--env MODE=prod \
--env DEBUG=0 \
bash -lc 'echo MODE=$MODE DEBUG=$DEBUG'
from tensorlake.sandbox import Sandbox
sandbox = Sandbox.create()
result = sandbox.run(
"bash",
["-lc", "echo MODE=$MODE DEBUG=$DEBUG"],
env={"MODE": "prod", "DEBUG": "0"},
)
print(result.stdout)
# Advanced: set additional command-only variables.
result = sandbox.run(
"bash",
["-lc", "echo APP_ENV=$APP_ENV TRACE_ID=$TRACE_ID"],
env={"APP_ENV": "staging", "TRACE_ID": "req-123"},
)
const result = await sandbox.run("bash", {
args: ["-lc", "echo MODE=$MODE DEBUG=$DEBUG"],
env: { MODE: "prod", DEBUG: "0" },
});
console.log(result.stdout);
// Advanced: set additional command-only variables.
const overrideResult = await sandbox.run("bash", {
args: ["-lc", "echo APP_ENV=$APP_ENV TRACE_ID=$TRACE_ID"],
env: { APP_ENV: "staging", TRACE_ID: "req-123" },
});
2. Env vars when creating a PTY session
Use PTY-scoped env when you need custom variables inside one interactive terminal session.
# Open an interactive PTY session
tl sbx ssh <sandbox-id-or-name>
# Set custom PTY env vars
tl sbx ssh <sandbox-id-or-name> \
--env APP_ENV=dev \
--env TERM=screen-256color
# Optional: custom shell, shell args, and working directory
tl sbx ssh <sandbox-id-or-name> \
--shell /bin/zsh \
--shell-arg -l \
--workdir /workspace \
--env APP_ENV=dev
tl sbx ssh always creates a PTY session with defaults like TERM and
COLORTERM=truecolor; your --env values are merged in and can override
those defaults.from tensorlake.sandbox import Sandbox
sandbox = Sandbox.create()
pty = sandbox.create_pty(
command="/bin/bash",
args=["-l"],
env={"TERM": "xterm-256color", "APP_ENV": "dev"},
working_dir="/workspace",
rows=24,
cols=80,
)
pty.send_input("echo APP_ENV=$APP_ENV\nexit\n")
pty.wait()
const pty = await sandbox.createPty({
command: "/bin/bash",
args: ["-l"],
env: { TERM: "xterm-256color", APP_ENV: "dev" },
workingDir: "/workspace",
rows: 24,
cols: 80,
});
await pty.sendInput("echo APP_ENV=$APP_ENV\nexit\n");
await pty.wait();
Choosing the right scope
- Use
run(..., env=...) for one-off command values.
- Use PTY
env for interactive terminal sessions.
