#Environment variables
<subtitle>Read default environment variables within the sandbox and inject custom variables at global, code execution, or command execution granularity. </subtitle>

Environment variables help you pass running context to programs within the sandbox, such as business mode, external service addresses, debugging switches, or one-time parameters. UCloud Sandbox will automatically inject some default variables, and also supports injecting custom variables when creating a sandbox and executing tasks.

##Default environment variables

After the sandbox is started, the system will inject the following default variables into the command execution environment:

- `UCLOUD_SANDBOX`: fixed to `true`, used to determine whether the current process is running in UCloud Sandbox.
- `UCLOUD_SANDBOX_ID`: Current sandbox ID.
- `UCLOUD_SANDBOX_TEMPLATE_ID`: Template ID used by the current sandbox.

These variables can be read via commands within the sandbox:

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
result = sandbox.commands.run("echo $UCLOUD_SANDBOX_ID")
print(result.stdout)
```

If you enter the sandbox manually through the CLI, the default variables are also saved in the `/run/ucloud/` directory in the form of dot files:

```bash
user@ucloud:~$ ls -a /run/ucloud/
.  ..  .UCLOUD_SANDBOX  .UCLOUD_SANDBOX_ID  .UCLOUD_TEMPLATE_ID
```

> The point file under `/run/ucloud/` is used to read system injection information in the CLI session; the corresponding environment variables can be read directly during SDK command execution. Where the template ID is `.UCLOUD_TEMPLATE_ID` in the CLI point file and `UCLOUD_SANDBOX_TEMPLATE_ID` in the command environment variable.

## Set environment variables

There are three main ways to set environment variables in the sandbox:

1. Set global environment variables when creating the sandbox.
2. Temporarily set environment variables when executing code.
3. Temporarily set environment variables when executing the command.

### 1. Set global environment variables when creating a sandbox

Pass in `envs` when creating a sandbox, and these variables will be visible to subsequent processes running in the sandbox.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    envs={
        "MY_VAR": "my_value",
        "APP_MODE": "production",
    },
)

result = sandbox.commands.run("echo $MY_VAR")
print(result.stdout)
```

### 2. Temporarily set environment variables when executing code

`envs` can be passed in a code execution call. These variables only take effect for this execution.

> The scope of such environment variables is limited to this execution, but they are not private storage at the operating system level. If the variable with the same name already exists in the global environment, the value passed in this execution will overwrite the global value.

```python
from ucloud_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

result = sandbox.run_code(
    'import os; print(os.environ.get("MY_VAR"))',
    envs={
        "MY_VAR": "my_value",
    },
)

print(result.logs.stdout)
```

### 3. Temporarily set environment variables when executing commands

You can also pass in `envs` in a certain `commands.run()` call. These variables only take effect for this command execution.

> If the variable with the same name exists in both the global environment variable and `envs` of this command, the value passed in this command takes precedence.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run(
    "echo $MY_VAR",
    envs={
        "MY_VAR": "123",
    },
)

print(result.stdout)
```

## Usage suggestions

- Use default variables to identify the current sandbox and template, such as log management, callback reporting or link tracking.
- Use `envs` when created to place the configuration required during the sandbox life cycle.
- Use a single execution of `envs` to pass temporary parameters to avoid polluting subsequent commands.
- It is not recommended to store sensitive credentials for a long time through environment variables; if a key must be passed in, please control the scope of processes within the sandbox that can access it, and destroy the sandbox in a timely manner after the task is completed.