computer, rpc, docs: forward env through the command execution path

Environment variables reached the JavaScript module backend through
process.env but were dropped on the command path: the runtime command
branch, the shell facade, the shell RPC contract, and the worker shell
backend all discarded env. Thread env end to end so a command backend
receives it too.

The runtime command branch now forwards env to the shell, WorkspaceShell
passes it on the exec envelope, the ShellRPC contract and its server
carry it to the runner, and the worker shell backend and entrypoint hand
it to just-bash. The container runner already merged a per-execution env
over its base environment; it now receives one from the wire.

Document env on the runtime interface as accepted everywhere: command
backends inherit it for the spawned command and the JavaScript backend
exposes it through process.env, applying to that execution only. Cover
the command path with tests at the entrypoint, worker shell backend,
workspace selection, and container runner layers.

Author: aron-cf

docs/05_runtime_interface.md

@@ -31,6 +31,8 @@ interface WorkspaceRuntimeExecOptions {
   encoding?: "utf8";
   input?: WorkspaceRuntimeValue;
   timeoutMs?: number;
+  env?: Record<string, string>;
+  stdin?: Uint8Array | string;
 }
 
 interface WorkspaceRuntimeExecHandle extends ReadableStream<WorkspaceRuntimeEvent> {
@@ -42,7 +44,7 @@ interface WorkspaceRuntimeExecHandle extends ReadableStream<WorkspaceRuntimeEven
 }
 ```
 
-`input` is accepted by structured module backends and rejected by command backends. `cwd` is the command working directory or the base for durable relative module imports. A handle is single-consumer: call `result()` or consume its event stream, not both. Repeated `result()` calls return the same promise. `backend` records the resolved backend needed for later reattachment.
+`input` is accepted by callable backends and rejected by the rest; it carries a structured value that the callable backend returns a structured value for. `env` is accepted everywhere: command backends inherit it for the spawned command, and the JavaScript module backend exposes it through `process.env`. Its values apply to that execution only and do not change later executions. `stdin` is the caller-supplied standard input, accepted by backends that model it (the JavaScript module backend reads it through `process.stdin`). `cwd` is the command working directory or the base for durable relative module imports. A handle is single-consumer: call `result()` or consume its event stream, not both. Repeated `result()` calls return the same promise. `backend` records the resolved backend needed for later reattachment.
 
 ## Results
 

packages/computer/src/backends/worker-shell/entrypoint.test.ts

@@ -32,7 +32,7 @@ class TestShellWorker extends ShellWorker {
     env: E,
     bashFactory: (
       command: string,
-      options: { cwd?: string; signal?: AbortSignal },
+      options: { cwd?: string; env?: Record<string, string>; signal?: AbortSignal },
     ) => Promise<{ stdout: string; stderr: string; exitCode: number }>,
   ): TestShellWorker {
     const w = new TestShellWorker(undefined as never, env as never);
@@ -189,6 +189,19 @@ describe("ShellWorker", () => {
     expect(observedCwd).toBe("/workspace/src");
   });
 
+  it("forwards per-execution environment variables to Bash", async () => {
+    let observedEnv: Record<string, string> | undefined;
+    const worker = TestShellWorker.withFakeBash(fakeEnv(), async (_command, options) => {
+      observedEnv = options.env;
+      return { stdout: "", stderr: "", exitCode: 0 };
+    });
+    await drain(
+      (await worker.exec({ command: "printenv TOKEN", env: { TOKEN: "secret", EMPTY: "" } }))
+        .events,
+    );
+    expect(observedEnv).toEqual({ TOKEN: "secret", EMPTY: "" });
+  });
+
   it("getExec without a prior exec throws ENOENT", async () => {
     const worker = new TestShellWorker(undefined as never, fakeEnv() as never);
     await expect(worker.getExec({ id: "missing" })).rejects.toMatchObject({ code: "ENOENT" });

packages/computer/src/backends/worker-shell/entrypoint.ts

@@ -30,6 +30,7 @@ export interface ExecInput {
   cwd?: string;
   id?: string;
   timeoutMs?: number;
+  env?: Record<string, string>;
 }
 
 export interface ShellWorkerOptions {
@@ -105,6 +106,7 @@ export class ShellWorker<
         command: string,
         options: {
           cwd?: string;
+          env?: Record<string, string>;
           signal?: AbortSignal;
           customCommands: CustomCommand[];
         },
@@ -171,6 +173,7 @@ export class ShellWorker<
       if (this.bashFactoryOverride !== undefined) {
         result = await this.bashFactoryOverride(input.command, {
           cwd,
+          env: input.env,
           signal: controller.signal,
           customCommands,
         });
@@ -192,7 +195,7 @@ export class ShellWorker<
           defenseInDepth: { enabled: false },
           executionLimits: { maxOutputSize: MAX_OUTPUT_BYTES },
         });
-        result = await bash.exec(input.command, { cwd, signal: controller.signal });
+        result = await bash.exec(input.command, { cwd, env: input.env, signal: controller.signal });
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);

packages/computer/src/backends/worker-shell/worker-shell.test.ts

@@ -31,7 +31,13 @@ type WireEvent =
   | { id: string; seq: number; name: "exit"; value: number };
 
 interface FakeShellFetcher {
-  exec(input: { command: string; cwd?: string; id?: string; timeoutMs?: number }): Promise<{
+  exec(input: {
+    command: string;
+    cwd?: string;
+    id?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+  }): Promise<{
     id: string;
     events: ReadableStream<Uint8Array>;
   }>;
@@ -58,7 +64,13 @@ function framedStream(events: WireEvent[]): ReadableStream<Uint8Array> {
 }
 
 function fakeFetcher(
-  exec: (input: { command: string; cwd?: string; id?: string; timeoutMs?: number }) => {
+  exec: (input: {
+    command: string;
+    cwd?: string;
+    id?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+  }) => {
     id: string;
     events: ReadableStream<Uint8Array>;
   },
@@ -148,6 +160,29 @@ describe("WorkerShellBackend", () => {
     expect(envelope.id).toBe("run-1");
   });
 
+  it("forwards per-execution environment variables to the fetcher", async () => {
+    let observedEnv: Record<string, string> | undefined;
+    const fetcher = fakeFetcher((input) => {
+      observedEnv = input.env;
+      return {
+        id: "env",
+        events: framedStream([{ id: "env", seq: 1, name: "exit", value: 0 }]),
+      };
+    });
+    const backend = new WorkerShellBackend({ fetcher: () => fetcher });
+    const handle = await backend.connect();
+    const envelope = await handle.rpc.shell.exec({
+      command: "printenv TOKEN",
+      env: { TOKEN: "secret", EMPTY: "" },
+    });
+    const reader = envelope.events.getReader();
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+    expect(observedEnv).toEqual({ TOKEN: "secret", EMPTY: "" });
+  });
+
   it("errors the stream on malformed execution frames", async () => {
     const fetcher = fakeFetcher(() => ({
       id: "bad",

packages/computer/src/backends/worker-shell/worker-shell.ts

@@ -33,7 +33,13 @@ import { SHELL_RUNTIME_MODULES } from "./runtime-modules.js";
 // implementation lives in ./entrypoint.ts; the backend consumes
 // it through the Fetcher the loader returns.
 export interface WorkerShellFetcher {
-  exec(input: { command: string; cwd?: string; id?: string; timeoutMs?: number }): Promise<{
+  exec(input: {
+    command: string;
+    cwd?: string;
+    id?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+  }): Promise<{
     id: string;
     events: ReadableStream<Uint8Array>;
   }>;
@@ -168,6 +174,7 @@ export class WorkerShellBackend implements WorkspaceBackend {
           cwd: input.cwd,
           id: input.id,
           timeoutMs: input.timeoutMs,
+          env: input.env,
         });
         return { id: envelope.id, events: decodeFramedEvents(envelope.events) };
       },

packages/computer/src/runtime/runtime.ts

@@ -60,6 +60,7 @@ export class WorkspaceRuntime {
         encoding: options.encoding,
         id: options.id,
         timeoutMs: options.timeoutMs,
+        env: options.env,
       });
       return wrapCommandHandle(handle, backend);
     }

packages/computer/src/shell.ts

@@ -105,6 +105,10 @@ export interface ExecOptions<E extends ExecEncoding = undefined> {
   // Omit to use the runner's default (typically 320_000). Pass 0
   // to disable the timeout for this call.
   timeoutMs?: number;
+  // Environment variables inherited by this command only. Values
+  // override the backend's base environment without changing later
+  // executions.
+  env?: Record<string, string>;
   // Backend selector. Omit to use the default backend (the first
   // one passed to the Workspace constructor); pass the id of
   // another configured backend to route this call there.
@@ -177,6 +181,7 @@ export class WorkspaceShell {
           id: options.id,
           cwd: options.cwd,
           timeoutMs: options.timeoutMs,
+          env: options.env,
         }),
       (span, outcome) => {
         if (outcome.ok) span.setAttribute("workspace.runtime.id", outcome.value.id);

packages/computer/src/workspace.test.ts

@@ -242,6 +242,43 @@ describe("Workspace backend selection", () => {
     expect(result).toMatchObject({ status: "completed", exitCode: 0 });
   });
 
+  it("forwards per-execution environment variables to command backends", async () => {
+    let receivedEnv: Record<string, string> | undefined;
+    const shell: import("@cloudflare/computer-rpc").ShellRPC = {
+      async exec(input) {
+        receivedEnv = input.env;
+        const id = input.id ?? "env-command";
+        return {
+          id,
+          events: new ReadableStream({
+            start(controller) {
+              controller.enqueue({ id, seq: 1, name: "exit", value: 0 });
+              controller.close();
+            },
+          }),
+        };
+      },
+      getExec: () => Promise.reject(new Error("not used")),
+      killExec: () => Promise.reject(new Error("not used")),
+      disposeExec: async () => undefined,
+    };
+    const backend: WorkspaceBackend = {
+      id: "command",
+      type: "fake",
+      async connect() {
+        return { rpc: { sync: fakeRpc(), shell }, sync: "none", close: async () => undefined };
+      },
+    };
+    const ws = new Workspace({ storage: makeStorage(), backends: [backend] });
+    await drainExec(
+      await ws.runtime.exec("printenv TOKEN", {
+        backend: "command",
+        env: { TOKEN: "secret", EMPTY: "" },
+      }),
+    );
+    expect(receivedEnv).toEqual({ TOKEN: "secret", EMPTY: "" });
+  });
+
   it("flushes incomplete trailing UTF-8 from command execution", async () => {
     const id = "utf8-command";
     const shell: import("@cloudflare/computer-rpc").ShellRPC = {

packages/computerd/src/exec/runner.test.ts

@@ -78,6 +78,31 @@ test("exec captures stdout and propagates exit code", async () => {
   }
 });
 
+test("per-execution env overrides the base env without leaking to later commands", async () => {
+  const { runner, dispose } = fixture({ env: { TOKEN: "base", BASE_ONLY: "yes" } });
+  try {
+    const first = runner.exec('printf \'%s|%s|%s\' "$TOKEN" "$BASE_ONLY" "$EMPTY"', {
+      env: { TOKEN: "override", EMPTY: "" },
+    });
+    const firstEvents = await drain(first.events);
+    const firstStdout = firstEvents
+      .filter((event) => event.name === "stdout")
+      .map((event) => decode(event.value as Uint8Array))
+      .join("");
+    expect(firstStdout).toBe("override|yes|");
+
+    const second = runner.exec("printf '%s' \"$TOKEN\"");
+    const secondEvents = await drain(second.events);
+    const secondStdout = secondEvents
+      .filter((event) => event.name === "stdout")
+      .map((event) => decode(event.value as Uint8Array))
+      .join("");
+    expect(secondStdout).toBe("base");
+  } finally {
+    dispose();
+  }
+});
+
 test("reusing a live id throws EEXEC_BUSY", async () => {
   const { runner, dispose } = fixture();
   try {

packages/rpc/src/interface.ts

@@ -104,6 +104,8 @@ export interface ShellRPC {
     // 0 disables the timeout. Omit to use the runner's default
     // (typically 320_000).
     timeoutMs?: number;
+    // Environment variables inherited by this command only.
+    env?: Record<string, string>;
   }): Promise<{
     id: string;
     events: ReadableStream<ExecEvent>;