Skip to main content
Use terminal sessions when you need an interactive shell, incremental output, or a persistent PTY-backed process inside the sandbox.

​
Create and Attach to a Terminal

Create a terminal and attach to its websocket stream: 
const terminal = await sandbox.terminal.create({
  command: "bash",
  args: ["-l"],
  rows: 24,
  cols: 80,
});

const connection = await terminal.attach();

for await (const event of connection.events()) {
  if (event.type === "output") {
    process.stdout.write(event.data);
    continue;
  }

  console.log("Exit code:", event.status.exitCode);
  break;
}

​
Write Input and Resize the PTY

Send input through the attached connection and resize the terminal: 
const terminal = await sandbox.terminal.create({
  command: "bash",
  args: ["-l"],
});

const connection = await terminal.attach();

await connection.resize(32, 110);
await connection.write("pwd\n");
await connection.write("echo terminal-ok\n");
await connection.write("exit\n");

await connection.close();

​
Get, Refresh, and Wait

Fetch an existing terminal or wait for it to complete: 
const terminal = await sandbox.terminal.create({
  command: "bash",
  args: ["-lc", "echo hello-from-terminal"],
});

const fetched = await sandbox.terminal.get(terminal.id, true);
console.log(fetched.current.output?.map((chunk) => chunk.data).join(""));

const status = await terminal.wait({
  timeoutMs: 2_000,
  includeOutput: true,
});

console.log(status.running, status.exitCode);

​
Signal and Kill

You can signal or kill a terminal-backed process: 
const terminal = await sandbox.terminal.create({
  command: "bash",
  args: ["-lc", "sleep 30"],
});

await terminal.signal("TERM");
const status = await terminal.wait({ timeoutMs: 5_000 });
console.log(status.running);

​
Common Terminal Parameters

​
command
string
required
Command to launch inside the terminal session.
​
args
string[]
Optional command arguments.
​
cwd
string
Working directory for the terminal process.
​
env
object
Environment variables to set for the terminal process.
​
rows
number
Initial terminal row count.
​
cols
number
Initial terminal column count.
​
timeoutMs
number
Optional PTY runtime limit in milliseconds.
sandbox.pty is an alias for sandbox.terminal.