Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Environment variables

There are multiple ways to configure environment variables in Blaxel sandboxes.
Environment variables cannot be added or changed after a sandbox is created. Set all required variables in your Dockerfile, or at sandbox creation time.

​
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. 
FROM blaxel/base-image:latest

ENV NODE_ENV=production
ENV PORT=3000
Never add secrets in a Dockerfile.
This also applies when creating sandbox images with the declarative image builder: 
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 });

​
When instantiating sandboxes from existing images

When instantiating sandboxes from existing images, any environment variables defined in the base image are automatically available. In addition to this, 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. 
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" },
  ],
});

​
When executing sandbox processes

Environment variables can also be set at process execution, applicable only to that specific process. 
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",
  },
});

​
Secrets

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 documentation for examples.
Last modified on June 3, 2026