feat: custom env vars

Author: yanxiyue

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmz-ai/sandbox-runtime",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Xmz Sandbox Runtime - A general-purpose tool for wrapping security boundaries around arbitrary processes",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -13,6 +13,7 @@ import {
   normalizeCaseForComparison,
   DANGEROUS_FILES,
   getDangerousDirectories,
+  RESERVED_ENV_VARS,
 } from './sandbox-utils.js'
 import type {
   FsReadRestrictionConfig,
@@ -51,6 +52,8 @@ export interface LinuxSandboxParams {
   mandatoryDenySearchDepth?: number
   /** Abort signal to cancel the ripgrep scan */
   abortSignal?: AbortSignal
+  /** Custom environment variables to set in the sandbox */
+  envVars?: Array<{ name: string; value: string }>
 }
 
 /** Default max depth for searching dangerous files */
@@ -1013,6 +1016,28 @@ export async function wrapCommandWithSandboxLinux(
       // If no sockets provided, network is completely blocked (--unshare-net without proxy)
     }
 
+    // ========== CUSTOM ENVIRONMENT VARIABLES ==========
+    if (params.envVars && params.envVars.length > 0) {
+      for (const { name, value } of params.envVars) {
+        if (RESERVED_ENV_VARS.has(name.toUpperCase())) {
+          logForDebugging(
+            `[Sandbox Linux] Skipping reserved environment variable: ${name}`,
+            { level: 'warn' },
+          )
+          continue
+        }
+        bwrapArgs.push('--setenv', name, value)
+      }
+      const addedCount = params.envVars.filter(
+        v => !RESERVED_ENV_VARS.has(v.name.toUpperCase()),
+      ).length
+      if (addedCount > 0) {
+        logForDebugging(
+          `[Sandbox Linux] Added ${addedCount} custom environment variable(s)`,
+        )
+      }
+    }
+
     // ========== FILESYSTEM RESTRICTIONS ==========
     const fsArgs = await generateFilesystemArgs(
       readConfig,

src/sandbox/linux-sandbox-utils.ts

@@ -10,6 +10,7 @@ import {
   containsGlobChars,
   DANGEROUS_FILES,
   getDangerousDirectories,
+  RESERVED_ENV_VARS,
 } from './sandbox-utils.js'
 import type {
   FsReadRestrictionConfig,
@@ -29,6 +30,8 @@ export interface MacOSSandboxParams {
   writeConfig: FsWriteRestrictionConfig | undefined
   ignoreViolations?: IgnoreViolationsConfig | undefined
   binShell?: string
+  /** Custom environment variables to set in the sandbox */
+  envVars?: Array<{ name: string; value: string }>
 }
 
 /**
@@ -674,7 +677,33 @@ export function wrapCommandWithSandboxMacOS(
   })
 
   // Generate proxy environment variables using shared utility
-  const proxyEnv = `export ${generateProxyEnvVars(httpProxyPort, socksProxyPort).join(' ')} && `
+  const proxyEnvVars = generateProxyEnvVars(httpProxyPort, socksProxyPort)
+
+  // Add custom environment variables (with reserved var filtering)
+  const customEnvVars: string[] = []
+  if (params.envVars && params.envVars.length > 0) {
+    for (const { name, value } of params.envVars) {
+      if (RESERVED_ENV_VARS.has(name.toUpperCase())) {
+        logForDebugging(
+          `[Sandbox macOS] Skipping reserved environment variable: ${name}`,
+          { level: 'warn' },
+        )
+        continue
+      }
+      // Shell-escape the value for safety
+      const escapedValue = value.replace(/'/g, "'\\''")
+      customEnvVars.push(`${name}='${escapedValue}'`)
+    }
+    if (customEnvVars.length > 0) {
+      logForDebugging(
+        `[Sandbox macOS] Added ${customEnvVars.length} custom environment variable(s)`,
+      )
+    }
+  }
+
+  const allEnvVars = [...proxyEnvVars, ...customEnvVars]
+  const proxyEnv =
+    allEnvVars.length > 0 ? `export ${allEnvVars.join(' ')} && ` : ''
 
   // Use the user's shell (zsh, bash, etc.) to ensure aliases/snapshots work
   // Resolve the full path to the shell binary

src/sandbox/macos-sandbox-utils.ts

@@ -165,6 +165,19 @@ export const RipgrepConfigSchema = z.object({
     ),
 })
 
+/**
+ * Environment variables configuration schema
+ * - String values: set the environment variable to that value
+ * - null values: inherit from host environment (process.env)
+ */
+export const EnvConfigSchema = z
+  .record(z.string(), z.string().nullable())
+  .optional()
+  .describe(
+    'Custom environment variables to set in sandboxed processes. ' +
+      'Keys are variable names, values can be strings (explicit value) or null (inherit from host).',
+  )
+
 /**
  * Main configuration schema for Sandbox Runtime validation
  */
@@ -193,6 +206,9 @@ export const SandboxRuntimeConfigSchema = z.object({
       'Maximum directory depth to search for dangerous files on Linux (default: 3). ' +
         'Higher values provide more protection but slower performance.',
     ),
+  env: EnvConfigSchema.describe(
+    'Custom environment variables for sandboxed processes',
+  ),
 })
 
 // Export inferred types
@@ -202,4 +218,5 @@ export type IgnoreViolationsConfig = z.infer<
   typeof IgnoreViolationsConfigSchema
 >
 export type RipgrepConfig = z.infer<typeof RipgrepConfigSchema>
+export type EnvConfig = z.infer<typeof EnvConfigSchema>
 export type SandboxRuntimeConfig = z.infer<typeof SandboxRuntimeConfigSchema>

src/sandbox/sandbox-config.ts

@@ -516,6 +516,35 @@ function getMandatoryDenySearchDepth(): number {
   return config?.mandatoryDenySearchDepth ?? 3
 }
 
+/**
+ * Get resolved environment variables configuration
+ * Resolves inherited values from host environment
+ * @returns Array of { name, value } pairs with all values resolved
+ */
+function getResolvedEnvVars(): Array<{ name: string; value: string }> {
+  if (!config?.env) {
+    return []
+  }
+
+  const resolved: Array<{ name: string; value: string }> = []
+
+  for (const [name, configValue] of Object.entries(config.env)) {
+    let value: string | undefined
+
+    if (configValue === null) {
+      value = process.env[name]
+    } else {
+      value = configValue
+    }
+
+    if (value !== undefined) {
+      resolved.push({ name, value })
+    }
+  }
+
+  return resolved
+}
+
 function getProxyPort(): number | undefined {
   return managerContext?.httpProxyPort
 }
@@ -607,6 +636,7 @@ async function wrapWithSandbox(
         allowLocalBinding: getAllowLocalBinding(),
         ignoreViolations: getIgnoreViolations(),
         binShell,
+        envVars: getResolvedEnvVars(),
       })
 
     case 'linux':
@@ -634,6 +664,7 @@ async function wrapWithSandbox(
         ripgrepConfig: getRipgrepConfig(),
         mandatoryDenySearchDepth: getMandatoryDenySearchDepth(),
         abortSignal,
+        envVars: getResolvedEnvVars(),
       })
 
     default:

src/sandbox/sandbox-manager.ts

@@ -25,6 +25,31 @@ export const DANGEROUS_FILES = [
  */
 export const DANGEROUS_DIRECTORIES = ['.git', '.vscode', '.idea'] as const
 
+/**
+ * Environment variables reserved by sandbox-runtime
+ * These cannot be overridden by user configuration
+ * Note: Matching is case-insensitive (names are uppercased before checking)
+ */
+export const RESERVED_ENV_VARS = new Set([
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'ALL_PROXY',
+  'NO_PROXY',
+  'FTP_PROXY',
+  'GRPC_PROXY',
+  'RSYNC_PROXY',
+  'GIT_SSH_COMMAND',
+  'DOCKER_HTTP_PROXY',
+  'DOCKER_HTTPS_PROXY',
+  'CLOUDSDK_PROXY_TYPE',
+  'CLOUDSDK_PROXY_ADDRESS',
+  'CLOUDSDK_PROXY_PORT',
+  'CLAUDE_CODE_HOST_HTTP_PROXY_PORT',
+  'CLAUDE_CODE_HOST_SOCKS_PROXY_PORT',
+  'SANDBOX_RUNTIME',
+  'TMPDIR',
+])
+
 /**
  * Get the list of dangerous directories to deny writes to.
  * Excludes .git since we need it writable for git operations -
@@ -144,7 +169,7 @@ export function generateProxyEnvVars(
   httpProxyPort?: number,
   socksProxyPort?: number,
 ): string[] {
-  const envVars: string[] = [`SANDBOX_RUNTIME=1`, `TMPDIR=/tmp/claude`]
+  const envVars: string[] = [`SANDBOX_RUNTIME=1`, `TMPDIR=/tmp/xmz-ai-sandbox`]
 
   // If no proxy ports provided, return minimal env vars
   if (!httpProxyPort && !socksProxyPort) {