> ## Documentation Index
> Fetch the complete documentation index at: https://blaxel-feat-keep-alive-timeout-clarification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox variables and secrets

> Configure environment variables and secrets in Blaxel sandboxes to securely manage API keys, credentials, and runtime configuration values.

## Environment variables

There are multiple ways to configure environment variables in Blaxel sandboxes.

<Note>
  Environment variables cannot be added or changed after a sandbox is created. Set all required variables in your Dockerfile, or at sandbox creation time.
</Note>

### When building new sandbox images

Environment variables defined in the sandbox image with the `ENV` Dockerfile directive are available in every sandbox created from it.

```dockerfile theme={null}
FROM blaxel/base-image:latest

ENV NODE_ENV=production
ENV PORT=3000
```

<Warning>
  Never add secrets in a Dockerfile.
</Warning>

This also applies when creating sandbox images with the [declarative image builder](/Sandboxes/Templates#Blaxel-SDK):

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ImageInstance } from "@blaxel/core";

  const sandbox = await ImageInstance.fromRegistry("node:20-alpine")
    .workdir("/app")
    .env({
      NODE_ENV: "production",
      PORT: "3000",
    })
    .build({ name: "my-sandbox", memory: 4096 });
  ```

  ```python Python theme={null}
  from blaxel.core import ImageInstance

  sandbox = await (
      ImageInstance.from_registry("node:20-alpine")
      .workdir("/app")
      .env(NODE_ENV="production", PORT="3000")
      .build(name="my-sandbox", memory=4096)
  )
  ```
</CodeGroup>

### When instantiating sandboxes from existing images

When instantiating sandboxes from existing images, any environment variables defined in the base image are automatically available. Additional environment variables can be set using the following methods.

#### Set variables at sandbox creation time

Pass `envs` as an array of name/value objects when creating a sandbox with the Blaxel SDKs. These are set as environment variables and are available to every process running inside the deployed sandbox by default (although they can be overridden by process-level variables, discussed in the next section).

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.createIfNotExists({
    name: "my-sandbox",
    image: "blaxel/base-image:latest",
    region: "us-pdx-1",
    envs: [
      { name: "NODE_ENV", value: "production" },
      { name: "PORT", value: "3000" },
    ],
  });
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.create_if_not_exists({
    "name": "my-sandbox",
    "image": "blaxel/base-image:latest",
    "region": "us-pdx-1",
    "envs": [
      { "name": "NODE_ENV", "value": "production" },
      { "name": "PORT", "value": "3000" },
    ],
  })
  ```
</CodeGroup>

### When executing sandbox processes

Environment variables can also be set at process execution, applicable only to that specific process.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");

  const process = await sandbox.process.exec({
    command: "node server.js",
    env: {
      PORT: "8080",
      LOG_LEVEL: "debug",
    },
  });
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")

  process = await sandbox.process.exec({
    "command": "node server.js",
    "env": {
      "PORT": "8080",
      "LOG_LEVEL": "debug",
    },
  })
  ```
</CodeGroup>

## Secrets

### Use proxy injection (recommended)

The recommended way to inject secrets into a sandbox is with the Blaxel proxy. This intercepts outbound HTTPS requests from the sandbox and injects secrets server-side using `{{SECRET:name}}` placeholders. The sandbox code never sees raw API keys or credentials.

See the [proxy routing with secrets injection](/Sandboxes/Proxy-secrets-injection) documentation for examples.

### Use a .env.build file

Build variables let you pass secrets and configuration values into the Docker build phase without exposing them at runtime. This is useful when your build process needs credentials that should never appear inside the deployed sandbox.

Create a `.env.build` file in the root of your project for build secrets. A common example of this is installing private npm packages, which require an `NPM_TOKEN` during `npm install`. Variables defined here are injected during the build phase only and are never persisted in the runtime environment.

```bash .env.build theme={null}
MY_SECRET_BUILD_VAR=I_AM_A_SECRET
```

<Tip>
  Use the `--build-env-file` argument to `bl deploy` to specify a custom file name or path instead of the default `.env.build`.
</Tip>

<Warning>
  Ensure that `.env.build` is ignored during commits to avoid accidentally making secrets public.
</Warning>