Skip to main content
The Exec module lets you run shell commands inside a sandbox. Access it via sandbox.exec. There are two ways to run commands:
  • sandbox.exec.run() — run a command and wait for it to finish (simple, synchronous)
  • sandbox.exec.start() — start a long-running command and stream its output (async, with callbacks)

​
Quick commands with sandbox.exec.run

Run a shell command and get the result when it completes. 
const result = await sandbox.exec.run('echo "Hello, World!"');

console.log(result.stdout);   // Hello, World!
console.log(result.stderr);   // (empty)
console.log(result.exitCode); // 0

​
sandbox.exec.run(command, opts?)

Executes a shell command and waits for it to complete.
​
command
string
required
The shell command to execute.
​
opts
RunOpts
Returns: Promise<ProcessResult>

​
ProcessResult

FieldTypeDescription
exitCodenumberExit code of the process (0 = success)
stdoutstringStandard output
stderrstringStandard error

​
Examples

// Run with a working directory
const result = await sandbox.exec.run('ls -la', { cwd: '/app' });

// Run with environment variables
const result = await sandbox.exec.run('echo $MY_VAR', {
  env: { MY_VAR: 'hello' },
});

// Run with a timeout
const result = await sandbox.exec.run('sleep 30', { timeout: 5 });

// Chain commands
const result = await sandbox.exec.run(
  'cd /app && npm install && npm run build'
);

​
Async commands with sandbox.exec.start

Start a long-running command and stream its output via callbacks. The command runs in the background and you get a session handle to interact with it. 
const session = await sandbox.exec.start("npm run dev", {
  cwd: "/app",
  onStdout: (data) => {
    console.log("stdout:", new TextDecoder().decode(data));
  },
  onStderr: (data) => {
    console.error("stderr:", new TextDecoder().decode(data));
  },
  onExit: (exitCode) => {
    console.log(`Process exited with code: ${exitCode}`);
  },
});

// Send input to the process
session.sendStdin("some input\n");

// Kill the process later
await session.kill();

// Or wait for it to finish
const exitCode = await session.done;

​
sandbox.exec.start(command, opts?)

Starts a command and returns an interactive session.
​
command
string
required
The command to execute.
​
opts
ExecStartOpts
Returns: Promise<ExecSession>

​
ExecSession

Property / MethodTypeDescription
sessionIdstringUnique session identifier
donePromise<number>Resolves with the exit code when the process exits
sendStdin(data)(data: string | Uint8Array) => voidSend input to the process
kill(signal?)(signal?: number) => Promise<void>Kill the process
close()() => voidClose the WebSocket connection

​
Examples

​
Start a dev server and keep it running

const devServer = await sandbox.exec.start("npm run dev", {
  cwd: "/app",
  onStdout: (data) => {
    const text = new TextDecoder().decode(data);
    if (text.includes("ready")) {
      console.log("Dev server is ready!");
    }
  },
});

// Do other work while the server runs...

// Stop it when done
await devServer.kill();

​
List running exec sessions

const sessions = await sandbox.exec.list();
for (const s of sessions) {
  console.log(`${s.sessionID} — ${s.command} — running: ${s.running}`);
}

​
Attach to an existing session

Reconnect to a running exec session by its ID: 
const session = await sandbox.exec.attach("session-id", {
  onStdout: (data) => console.log(new TextDecoder().decode(data)),
  onExit: (code) => console.log(`Exited: ${code}`),
});