Environment Variables

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.

CLI
Python
TypeScript

# 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 SandboxClient

client = SandboxClient()

with client.create_and_connect() as sandbox:
    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.

CLI
Python
TypeScript

# 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 SandboxClient

client = SandboxClient()

with client.create_and_connect() as sandbox:
    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.

Overview

Guides

Use Cases

Environment Variables

Prerequisites

1. Env vars for a single command in a sandbox

2. Env vars when creating a PTY session

Choosing the right scope

Overview

Guides

Use Cases

​Prerequisites

​1. Env vars for a single command in a sandbox

​2. Env vars when creating a PTY session

​Choosing the right scope

Prerequisites

1. Env vars for a single command in a sandbox

2. Env vars when creating a PTY session

Choosing the right scope