# Environment Variables
<subtitle>Configure runtime context variables for sandboxes, supporting built-in system variables and custom injection.</subtitle>

## Environment Setup

Before using the SDK, please ensure that the `AGENTBOX_API_KEY` environment variable is configured.

>
> You can obtain your API key from the [Console API Keys page](https://console.ucloud.cn/modelverse/experience/api-keys).

```bash
export AGENTBOX_API_KEY=your_api_key
```

Environment variables are an important means of controlling Agent runtime logic. UCloud Sandbox provides a series of built-in variables and also allows users to inject custom variables at different stages.

## Built-in System Variables

After the sandbox starts, the system will automatically inject the following variables for programs to identify the current runtime environment:

*   `UCLOUD_SANDBOX`: Always `true`, used for code self-check to determine if currently running in a sandbox.
*   `UCLOUD_SANDBOX_ID`: Unique identifier of the current sandbox.
*   `UCLOUD_TEAM_ID`: Team ID.
*   `UCLOUD_TEMPLATE_ID`: Template ID used to start this sandbox.

**Verify through SDK:**

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
result = sandbox.commands.run("echo $UCLOUD_SANDBOX_ID")
print(f"Current Sandbox ID: {result.stdout}")
```

>
> **CLI Access Path**: If you manually enter the sandbox through CLI, you can read these variables by checking dot files in the `/run/ucloud/` directory.

---

## Inject Custom Variables

Injecting environment variables usually has three granularities, choose as needed:

### 1. Global Environment Variables (Valid for Lifecycle)

Specified when creating the sandbox, visible to all subsequent processes executed within this sandbox.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    envs={
        'BASE_URL': 'https://api.example.com',
        'APP_MODE': 'production'
    },
)

res = sandbox.commands.run("echo $BASE_URL")
print(res.stdout)

res = sandbox.commands.run("echo $APP_MODE")
print(res.stdout)
```

### 2. Temporary Injection When Executing Code

Only effective for a single `run_code` call.

```python
# Only effective for this Python code execution
from ucloud_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

res = sandbox.run_code(
    'import os; print(os.environ.get("TEMP_KEY"))',
    envs={'TEMP_KEY': 'temporary_value'}
)
print(res.logs.stdout)
```

### 3. Temporary Injection When Executing Commands

Only effective for a single `commands.run` call.

```python
# Only effective for this Shell command execution
from ucloud_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

res = sandbox.commands.run(
    'echo $DEBUG_LEVEL',
    envs={'DEBUG_LEVEL': 'verbose'}
)
print(res)
```

## Override Priority Rules

>
> **Override Note**: If a variable name exists in both global settings and single execution settings, **single execution settings will have higher priority** and override global settings.