add environment variables and working directory support to command exec (#204)

* add environment variables and working directory support to command execution

* add execution options support to test worker API endpoints

* improve environment variable handling in command execution

* updates based on review

* Fix openai agents example typecheck

* Add support for env vars and working directory in exec

Add support for environment variables and working directory in command execution.

* minor fixes and nits

* one more nit

* handling of environment variables in the session execution

* fix tests

* update tests

* additional security and tests

* nits

* fix handling of environment variable exports in session management

* Move env setting + cleanup method out of buildFIFOScript

* Fix type errors

---------

Co-authored-by: Naresh <[email protected]>

Author: whoiskatrin

.changeset/neat-shirts-bathe.md

@@ -0,0 +1,5 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+add environment variables and working directory support to command exec

packages/sandbox-container/src/handlers/execute-handler.ts

@@ -48,7 +48,9 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
         body.command,
         {
           sessionId,
-          timeoutMs: body.timeoutMs
+          timeoutMs: body.timeoutMs,
+          env: body.env,
+          cwd: body.cwd
         }
       );
 
@@ -72,7 +74,9 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
     // For non-background commands, execute and return result
     const result = await this.processService.executeCommand(body.command, {
       sessionId,
-      timeoutMs: body.timeoutMs
+      timeoutMs: body.timeoutMs,
+      env: body.env,
+      cwd: body.cwd
     });
 
     if (!result.success) {
@@ -105,7 +109,9 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
 
     // Start the process for streaming
     const processResult = await this.processService.startProcess(body.command, {
-      sessionId
+      sessionId,
+      env: body.env,
+      cwd: body.cwd
     });
 
     if (!processResult.success) {

packages/sandbox-container/src/services/process-service.ts

@@ -58,7 +58,8 @@ export class ProcessService {
         sessionId,
         command,
         options.cwd,
-        options.timeoutMs
+        options.timeoutMs,
+        options.env
       );
 
       if (!result.success) {
@@ -202,7 +203,10 @@ export class ProcessService {
             );
           }
         },
-        options.cwd,
+        {
+          cwd: options.cwd,
+          env: options.env
+        },
         processRecordData.id // Pass process ID as commandId for tracking and killing
       );
 

packages/sandbox-container/src/services/session-manager.ts

@@ -116,7 +116,8 @@ export class SessionManager {
     sessionId: string,
     command: string,
     cwd?: string,
-    timeoutMs?: number
+    timeoutMs?: number,
+    env?: Record<string, string>
   ): Promise<ServiceResult<RawExecResult>> {
     try {
       // Get or create session on demand
@@ -141,7 +142,10 @@ export class SessionManager {
 
       const session = sessionResult.data;
 
-      const result = await session.exec(command, cwd ? { cwd } : undefined);
+      const result = await session.exec(
+        command,
+        cwd || env ? { cwd, env } : undefined
+      );
 
       return {
         success: true,
@@ -187,10 +191,12 @@ export class SessionManager {
     sessionId: string,
     command: string,
     onEvent: (event: ExecEvent) => Promise<void>,
-    cwd: string | undefined,
+    options: { cwd?: string; env?: Record<string, string> } = {},
     commandId: string
   ): Promise<ServiceResult<{ continueStreaming: Promise<void> }>> {
     try {
+      const { cwd, env } = options;
+
       // Get or create session on demand
       let sessionResult = await this.getSession(sessionId);
 
@@ -215,7 +221,7 @@ export class SessionManager {
       const session = sessionResult.data;
 
       // Get async generator
-      const generator = session.execStream(command, { commandId, cwd });
+      const generator = session.execStream(command, { commandId, cwd, env });
 
       // CRITICAL: Await first event to ensure command is tracked before returning
       // This prevents race condition where killCommand() is called before trackCommand()

packages/sandbox-container/src/session.ts

@@ -88,6 +88,8 @@ export interface RawExecResult {
 interface ExecOptions {
   /** Override working directory for this command only */
   cwd?: string;
+  /** Environment variables for this command only (does not persist in session) */
+  env?: Record<string, string>;
 }
 
 /** Command handle for tracking and killing running commands */
@@ -233,7 +235,8 @@ export class Session {
         logFile,
         exitCodeFile,
         options?.cwd,
-        false
+        false,
+        options?.env
       );
 
       // Write script to shell's stdin
@@ -333,7 +336,8 @@ export class Session {
         logFile,
         exitCodeFile,
         options?.cwd,
-        true
+        true,
+        options?.env
       );
 
       if (this.shell!.stdin && typeof this.shell!.stdin !== 'number') {
@@ -624,7 +628,8 @@ export class Session {
     logFile: string,
     exitCodeFile: string,
     cwd?: string,
-    isBackground = false
+    isBackground = false,
+    env?: Record<string, string>
   ): string {
     // Create unique FIFO names to prevent collisions
     const stdoutPipe = join(this.sessionDir!, `${cmdId}.stdout.pipe`);
@@ -639,6 +644,32 @@ export class Session {
     const safeSessionDir = this.escapeShellPath(this.sessionDir!);
     const safePidFile = this.escapeShellPath(pidFile);
 
+    const indentLines = (input: string, spaces: number) => {
+      const prefix = ' '.repeat(spaces);
+      return input
+        .split('\n')
+        .map((line) => (line.length > 0 ? `${prefix}${line}` : ''))
+        .join('\n');
+    };
+
+    const { setup: envSetupBlock, cleanup: envCleanupBlock } =
+      this.buildScopedEnvBlocks(env, cmdId, { restore: !isBackground });
+
+    const hasScopedEnv = envSetupBlock.length > 0;
+
+    const buildCommandBlock = (exitVar: string, indent: number): string => {
+      const lines: string[] = [];
+      if (hasScopedEnv) {
+        lines.push(envSetupBlock);
+      }
+      lines.push(`  ${command}`);
+      lines.push(`  ${exitVar}=$?`);
+      if (envCleanupBlock) {
+        lines.push(envCleanupBlock);
+      }
+      return indentLines(lines.join('\n'), indent);
+    };
+
     // Build the FIFO script
     // For background: monitor handles cleanup (no trap needed)
     // For foreground: trap handles cleanup (standard pattern)
@@ -684,8 +715,7 @@ export class Session {
         script += `  if cd ${safeCwd}; then\n`;
         script += `    # Execute command in BACKGROUND (runs in subshell, enables concurrency)\n`;
         script += `    {\n`;
-        script += `      ${command}\n`;
-        script += `      CMD_EXIT=$?\n`;
+        script += `${buildCommandBlock('CMD_EXIT', 6)}\n`;
         script += `      # Write exit code\n`;
         script += `      echo "$CMD_EXIT" > ${safeExitCodeFile}.tmp\n`;
         script += `      mv ${safeExitCodeFile}.tmp ${safeExitCodeFile}\n`;
@@ -708,8 +738,7 @@ export class Session {
       } else {
         script += `  # Execute command in BACKGROUND (runs in subshell, enables concurrency)\n`;
         script += `  {\n`;
-        script += `    ${command}\n`;
-        script += `    CMD_EXIT=$?\n`;
+        script += `${buildCommandBlock('CMD_EXIT', 4)}\n`;
         script += `    # Write exit code\n`;
         script += `    echo "$CMD_EXIT" > ${safeExitCodeFile}.tmp\n`;
         script += `    mv ${safeExitCodeFile}.tmp ${safeExitCodeFile}\n`;
@@ -738,8 +767,9 @@ export class Session {
         script += `  PREV_DIR=$(pwd)\n`;
         script += `  if cd ${safeCwd}; then\n`;
         script += `    # Execute command, redirect to temp files\n`;
-        script += `    { ${command}; } < /dev/null > "$log.stdout" 2> "$log.stderr"\n`;
-        script += `    EXIT_CODE=$?\n`;
+        script += `    {\n`;
+        script += `${buildCommandBlock('EXIT_CODE', 6)}\n`;
+        script += `    } < /dev/null > "$log.stdout" 2> "$log.stderr"\n`;
         script += `    # Restore directory\n`;
         script += `    cd "$PREV_DIR"\n`;
         script += `  else\n`;
@@ -748,8 +778,9 @@ export class Session {
         script += `  fi\n`;
       } else {
         script += `  # Execute command, redirect to temp files\n`;
-        script += `  { ${command}; } < /dev/null > "$log.stdout" 2> "$log.stderr"\n`;
-        script += `  EXIT_CODE=$?\n`;
+        script += `  {\n`;
+        script += `${buildCommandBlock('EXIT_CODE', 4)}\n`;
+        script += `  } < /dev/null > "$log.stdout" 2> "$log.stderr"\n`;
       }
 
       script += `  \n`;
@@ -775,6 +806,58 @@ export class Session {
     return script;
   }
 
+  private buildScopedEnvBlocks(
+    env: Record<string, string> | undefined,
+    cmdId: string,
+    options: { restore: boolean }
+  ): { setup: string; cleanup: string } {
+    if (!env || Object.keys(env).length === 0) {
+      return { setup: '', cleanup: '' };
+    }
+
+    const sanitizeIdentifier = (value: string) =>
+      value.replace(/[^A-Za-z0-9_]/g, '_');
+
+    const setupLines: string[] = [];
+    const cleanupLines: string[] = [];
+    const cmdSuffix = sanitizeIdentifier(cmdId);
+
+    Object.entries(env).forEach(([key, value], index) => {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        throw new Error(`Invalid environment variable name: ${key}`);
+      }
+
+      const escapedValue = value.replace(/'/g, "'\\''");
+
+      if (options.restore) {
+        const stateSuffix = `${cmdSuffix}_${index}`;
+        const hasVar = `__SANDBOX_HAS_${stateSuffix}`;
+        const prevVar = `__SANDBOX_PREV_${stateSuffix}`;
+
+        setupLines.push(`  ${hasVar}=0`);
+        setupLines.push(`  if [ "\${${key}+x}" = "x" ]; then`);
+        setupLines.push(`    ${hasVar}=1`);
+        setupLines.push(`    ${prevVar}=$(printf '%q' "\${${key}}")`);
+        setupLines.push('  fi');
+        setupLines.push(`  export ${key}='${escapedValue}'`);
+
+        cleanupLines.push(`  if [ "$${hasVar}" = "1" ]; then`);
+        cleanupLines.push(`    eval "export ${key}=$${prevVar}"`);
+        cleanupLines.push('  else');
+        cleanupLines.push(`    unset ${key}`);
+        cleanupLines.push('  fi');
+        cleanupLines.push(`  unset ${hasVar} ${prevVar}`);
+      } else {
+        setupLines.push(`  export ${key}='${escapedValue}'`);
+      }
+    });
+
+    return {
+      setup: setupLines.join('\n'),
+      cleanup: options.restore ? cleanupLines.join('\n') : ''
+    };
+  }
+
   /**
    * Wait for exit code file to appear using hybrid fs.watch + polling
    *

packages/sandbox-container/src/validation/schemas.ts

@@ -17,7 +17,9 @@ export const ExecuteRequestSchema = z.object({
   command: z.string().min(1, 'Command cannot be empty'),
   sessionId: z.string().optional(),
   background: z.boolean().optional(),
-  timeoutMs: z.number().positive().optional()
+  timeoutMs: z.number().positive().optional(),
+  env: z.record(z.string()).optional(),
+  cwd: z.string().optional()
 });
 
 // File operation schemas

packages/sandbox-container/tests/services/process-service.test.ts

@@ -108,7 +108,8 @@ describe('ProcessService', () => {
         'default', // sessionId
         'echo "hello world"',
         '/tmp', // cwd
-        undefined // timeoutMs (not provided in options)
+        undefined, // timeoutMs (not provided in options)
+        undefined // env (not provided in options)
       );
     });
 
@@ -180,7 +181,7 @@ describe('ProcessService', () => {
         'session-123',
         'sleep 10',
         expect.any(Function), // event handler callback
-        '/tmp',
+        expect.objectContaining({ cwd: '/tmp' }),
         expect.any(String) // commandId (generated dynamically)
       );
 

packages/sandbox-container/tests/session.test.ts

@@ -151,6 +151,82 @@ describe('Session', () => {
       expect(result2.stdout.trim()).toContain('subdir');
     });
 
+    it('should scope per-command environment variables', async () => {
+      const result = await session.exec('printenv TEMP_CMD_VAR', {
+        env: { TEMP_CMD_VAR: 'scoped-value' }
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe('scoped-value');
+
+      const verify = await session.exec('printenv TEMP_CMD_VAR');
+      expect(verify.exitCode).not.toBe(0);
+    });
+
+    it('should reject invalid per-command environment variable names', async () => {
+      await expect(
+        session.exec('pwd', {
+          env: { 'INVALID-NAME': 'value' }
+        })
+      ).rejects.toThrow(/Invalid environment variable name/);
+    });
+
+    it('should safely handle env values with shell special chars', async () => {
+      const result = await session.exec('echo "$SPECIAL"', {
+        env: { SPECIAL: '$(whoami) `date` $PATH' }
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe('$(whoami) `date` $PATH');
+    });
+
+    it('should handle env values with quotes', async () => {
+      const result = await session.exec('echo "$QUOTED"', {
+        env: { QUOTED: "it's got 'quotes'" }
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe("it's got 'quotes'");
+    });
+
+    it('should restore existing env vars with special characters', async () => {
+      await session.destroy();
+      session = new Session({
+        id: 'test-exec',
+        cwd: testDir,
+        env: { RESTORE_VAR: '$(whoami) $PATH' }
+      });
+      await session.initialize();
+
+      const initial = await session.exec('echo "$RESTORE_VAR"');
+      expect(initial.exitCode).toBe(0);
+      expect(initial.stdout.trim()).toBe('$(whoami) $PATH');
+
+      const overrideResult = await session.exec('echo "$RESTORE_VAR"', {
+        env: { RESTORE_VAR: 'temporary-value' }
+      });
+      expect(overrideResult.exitCode).toBe(0);
+      expect(overrideResult.stdout.trim()).toBe('temporary-value');
+
+      const restoredResult = await session.exec('echo "$RESTORE_VAR"');
+      expect(restoredResult.exitCode).toBe(0);
+      expect(restoredResult.stdout.trim()).toBe('$(whoami) $PATH');
+    });
+
+    it('should restore overridden environment variables', async () => {
+      await session.exec('export EXISTING="original"');
+
+      const overrideResult = await session.exec('echo "$EXISTING"', {
+        env: { EXISTING: 'temp' }
+      });
+      expect(overrideResult.exitCode).toBe(0);
+      expect(overrideResult.stdout.trim()).toBe('temp');
+
+      const restoredResult = await session.exec('echo "$EXISTING"');
+      expect(restoredResult.exitCode).toBe(0);
+      expect(restoredResult.stdout.trim()).toBe('original');
+    });
+
     it('should override cwd temporarily when option provided', async () => {
       // Create a subdirectory
       await session.exec('mkdir -p tempdir');