Environment Variables

Environment variables let you pass configuration, secrets, and runtime settings into your sandbox. You can set them at sandbox creation time or override them for individual commands.

Setting Environment Variables at Creation

Pass environment variables when creating a sandbox. These variables are available to all commands and processes that run inside the sandbox.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  envs: {
    DATABASE_URL: 'postgresql://localhost:5432/mydb',
    API_KEY: 'sk-vibengine-abc123',
    NODE_ENV: 'production',
    LOG_LEVEL: 'debug',
  },
})

// All commands can access these variables
const result = await sandbox.commands.run('echo $NODE_ENV')
console.log(result.stdout) // "production\n"

from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "DATABASE_URL": "postgresql://localhost:5432/mydb",
    "API_KEY": "sk-vibengine-abc123",
    "NODE_ENV": "production",
    "LOG_LEVEL": "debug",
})

# All commands can access these variables
result = sandbox.commands.run("echo $NODE_ENV")
print(result.stdout)  # "production\n"

Environment variables set at creation time are available for the entire lifetime of the sandbox, across all commands and processes.

Per-Command Environment Variables

You can set or override environment variables for a single command. These only apply to that specific command and do not affect the sandbox globally.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  envs: {
    MODE: 'default',
  },
})

// Override MODE for this command only
const result1 = await sandbox.commands.run('echo $MODE', {
  envs: { MODE: 'override' },
})
console.log(result1.stdout) // "override\n"

// The sandbox-level value is unchanged
const result2 = await sandbox.commands.run('echo $MODE')
console.log(result2.stdout) // "default\n"

from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "MODE": "default",
})

# Override MODE for this command only
result1 = sandbox.commands.run("echo $MODE", envs={"MODE": "override"})
print(result1.stdout)  # "override\n"

# The sandbox-level value is unchanged
result2 = sandbox.commands.run("echo $MODE")
print(result2.stdout)  # "default\n"

Adding Extra Variables per Command

Per-command environment variables merge with the sandbox-level variables. You can add new variables without losing the existing ones.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  envs: {
    APP_NAME: 'my-app',
  },
})

// Add EXTRA_VAR for this command; APP_NAME is still available
const result = await sandbox.commands.run('echo "$APP_NAME - $EXTRA_VAR"', {
  envs: { EXTRA_VAR: 'bonus' },
})
console.log(result.stdout) // "my-app - bonus\n"

from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "APP_NAME": "my-app",
})

# Add EXTRA_VAR for this command; APP_NAME is still available
result = sandbox.commands.run(
    'echo "$APP_NAME - $EXTRA_VAR"',
    envs={"EXTRA_VAR": "bonus"},
)
print(result.stdout)  # "my-app - bonus\n"

Reading Environment Variables

You can read environment variables from within the sandbox by running shell commands or through scripts.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  envs: {
    SECRET_TOKEN: 'my-secret-123',
  },
})

// Read via shell
const result = await sandbox.commands.run('echo $SECRET_TOKEN')
console.log(result.stdout.trim()) // "my-secret-123"

// Read via a Python script
await sandbox.files.write('/home/user/check_env.py', `
import os
token = os.environ.get("SECRET_TOKEN", "not set")
print(f"Token: {token}")
`)
const pyResult = await sandbox.commands.run('python3 /home/user/check_env.py')
console.log(pyResult.stdout) // "Token: my-secret-123\n"

from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "SECRET_TOKEN": "my-secret-123",
})

# Read via shell
result = sandbox.commands.run("echo $SECRET_TOKEN")
print(result.stdout.strip())  # "my-secret-123"

# Read via a Python script
sandbox.files.write("/home/user/check_env.py", """
import os
token = os.environ.get("SECRET_TOKEN", "not set")
print(f"Token: {token}")
""")
py_result = sandbox.commands.run("python3 /home/user/check_env.py")
print(py_result.stdout)  # "Token: my-secret-123\n"

Common Patterns

Passing API Keys Securely

Use environment variables to pass API keys and secrets rather than hardcoding them in scripts.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  envs: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
  },
})

// Scripts inside the sandbox can now use these keys
await sandbox.files.write('/home/user/fetch.py', `
import os
import urllib.request

api_key = os.environ["OPENAI_API_KEY"]
print(f"Key loaded: {api_key[:8]}...")
`)

await sandbox.commands.run('python3 /home/user/fetch.py')

import os
from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "OPENAI_API_KEY": os.environ["OPENAI_API_KEY"],
    "STRIPE_SECRET_KEY": os.environ["STRIPE_SECRET_KEY"],
})

# Scripts inside the sandbox can now use these keys
sandbox.files.write("/home/user/fetch.py", """
import os
api_key = os.environ["OPENAI_API_KEY"]
print(f"Key loaded: {api_key[:8]}...")
""")

sandbox.commands.run("python3 /home/user/fetch.py")

Be careful with sensitive environment variables. Anyone with access to the sandbox ID can connect and read environment variables. Treat sandbox environment variables with the same security considerations as server-side environment variables.

Configuring Runtime Behavior

Use environment variables to change how code runs inside the sandbox without modifying the code itself.

import { Sandbox } from 'vibengine'

// Development sandbox
const devSandbox = await Sandbox.create({
  envs: { NODE_ENV: 'development', DEBUG: 'true' },
})

// Production sandbox
const prodSandbox = await Sandbox.create({
  envs: { NODE_ENV: 'production', DEBUG: 'false' },
})

from vibengine import Sandbox

# Development sandbox
dev_sandbox = Sandbox.create(envs={"NODE_ENV": "development", "DEBUG": "true"})

# Production sandbox
prod_sandbox = Sandbox.create(envs={"NODE_ENV": "production", "DEBUG": "false"})

Next Steps

Create a Sandbox — all sandbox creation options
Execute Commands — run commands with per-command env vars
Internet Access — use env vars for API keys in network calls

Environment Variables

On this page