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

# Environment Variables

> Set per-command and per-PTY environment variables in the CLI, Python, and TypeScript.

Use this page as a quick reference for environment variable scopes in Sandboxes.
For endpoint-level and workflow details, also see [Execute Commands](./commands) and [PTY Sessions](./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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # 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'
    ```

    ```bash theme={null}
    # 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'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```

    ```python theme={null}
    # 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"},
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const result = await sandbox.run("bash", {
      args: ["-lc", "echo MODE=$MODE DEBUG=$DEBUG"],
      env: { MODE: "prod", DEBUG: "0" },
    });

    console.log(result.stdout);
    ```

    ```typescript theme={null}
    // 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" },
    });
    ```
  </Tab>
</Tabs>

## 2. Env vars when creating a PTY session

Use PTY-scoped env when you need custom variables inside one interactive terminal session.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Open an interactive PTY session
    tl sbx ssh <sandbox-id-or-name>
    ```

    ```bash theme={null}
    # Set custom PTY env vars
    tl sbx ssh <sandbox-id-or-name> \
      --env APP_ENV=dev \
      --env TERM=screen-256color
    ```

    ```bash theme={null}
    # 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.
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Choosing the right scope

* Use `run(..., env=...)` for one-off command values.
* Use PTY `env` for interactive terminal sessions.