Commands

client.commands runs processes inside a sandbox and tracks each one as a Command record with status, output, and logs. run waits for the process to exit by default. Set background: true to return immediately while it runs.

run

Execute a command and wait for it to exit. The resolved Command includes exitCode, stdout, and stderr.

run(
  sandboxId: `sbx_${string}`,
  command: string,
  input?: RunCommandOptions,
): Promise<Command>

RunCommandOptions:

const result = await client.commands.run(sandbox.id, "pytest -q", {
  cwd: "/workspace/app",
  timeoutMs: 120_000,
  collect: [{ path: "report.xml", name: "test-report" }],
  collectOn: "always",
});

console.log(result.status, result.exitCode);
console.log(result.stdout);

When collect is set, the command's collectStatus reports the outcome (succeeded, partial, failed, skipped, pending, or not_requested), with per-file details in collectErrors.

Error codes: invalid_request, forbidden, not_found, sandbox_destroyed, quota_exceeded.

Run a command in the background when you need the Command record immediately. The TypeScript input union rejects collect and collectOn when background: true.

const cmd = await client.commands.run(sandbox.id, "python3 server.py", {
  background: true,
});

get

Fetch the current state of a command.

get(commandId: `cmd_${string}`): Promise<Command>

const cmd = await client.commands.get("cmd_abc123");
console.log(cmd.status, cmd.exitCode);

cancel

Cancel a running command. Graceful mode sends SIGTERM; force mode sends SIGKILL. The operation is idempotent by state.

cancel(
  commandId: `cmd_${string}`,
  input?: { mode?: "graceful" | "force" },
): Promise<Command>

const canceled = await client.commands.cancel(cmd.id, { mode: "force" });
console.log(canceled.status); // "canceled"

logs

Fetch stored log chunks for a command.

logs(
  commandId: `cmd_${string}`,
  input?: { afterSeq?: number; limit?: number },
): Promise<ListCommandLogsResponse>

Each CommandLogChunk is { commandId, createdAt, data, seq, stream: "stdout" | "stderr" }.

const chunks = await client.commands.logs(cmd.id, { limit: 100 });
for (const chunk of chunks.data) {
  process.stdout.write(chunk.data);
}

streamLogs

Stream logs live over server-sent events as an async iterable. The stream ends with a terminal event carrying the final command state.

streamLogs(
  commandId: `cmd_${string}`,
  input?: CommandStreamInput,
): AsyncIterable<CommandLogStreamEvent>

timeoutMs bounds connection establishment and becomes the default stream inactivity window after response headers arrive. Set streamIdleTimeoutMs to override only the inactivity phase. Every received byte, including a server heartbeat, resets that deadline. You can also pass signal to cancel the stream directly.

CommandLogStreamEvent is a union:

Run a background command, then read events until the terminal event:

const cmd = await client.commands.run(sandbox.id, "npm test", {
  background: true,
});

for await (const event of client.commands.streamLogs(cmd.id)) {
  if (event.type === "log") process.stdout.write(event.data);
  if (event.type === "error") throw new Error(event.message);
  if (event.type === "terminal") {
    console.log("exit code:", event.command.exitCode);
    break;
  }
}

Pass afterSeq to resume after the last sequence number you've seen. If the requested sequence is outside the retention window, the stream emits an error event with code stream_gap.

Command object

The Command type includes id (cmd_ prefix), sandboxId, command, cwd, env, status (queued, starting, running, exited, failed, canceled, timed_out, killed), exitCode, stdout, stderr, stdoutTruncated, stderrTruncated, startedAt, finishedAt, durationMs, collectStatus, collectErrors, cancelMode, canceledAt, killedReason (sandbox_destroyed), and terminationSignal (SIGTERM or SIGKILL).

Next steps

• Files — write inputs and read outputs.
• Artifacts — keep command outputs after the sandbox is gone.
• Errors — error codes and retry guidance.