Run commands - Namespace Documentation

Run non-interactive commands with exec() or shell() and wait for the result, or start them in the background with devbox.executions and check on them later. Choose between structured arguments and shell evaluation based on the command you need to run.

Command operations start a stopped Devbox automatically. Commands are retained with their output and can be inspected later with devbox.executions or devbox logs.

`exec()`

Use exec() to pass an executable and its arguments without invoking a shell. Arguments are passed literally, so shell expansion, pipelines, redirects, and environment-variable interpolation do not apply.

Example

Run a command and inspect its result:

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.exec(["node", "--version"]);
if (result.exitCode !== 0) {
  throw new Error(result.error ?? result.stderr);
}
console.log(result.stdout.trim());

API reference

exec(argv: readonly string[], options?: ExecOptions): Promise<ExecResult>

Arguments and options

readonly string[]

required

The executable followed by its arguments. The array must contain at least one item.

ExecOptions

Options for the command.

Hide properties

string

The working directory. Absolute paths are used as provided. Relative paths resolve from the Devbox workspace directory.

Record<string, string>

Additional environment variables. Names must start with a letter or underscore and contain only letters, numbers, and underscores.

string | Uint8Array

Data provided to standard input. Strings are encoded as UTF-8.

(data: Uint8Array) => void

Called for each standard-output chunk. Output is also collected in the returned result.

(data: Uint8Array) => void

Called for each standard-error chunk. Output is also collected in the returned result.

AbortSignal

Cancels the operation when the signal is aborted.

number

The total timeout budget in milliseconds, including activation and connection time. The value must be finite and non-negative.

When cwd is omitted, the command runs in the Devbox’s default directory. If the Devbox checks out a repository during creation, that directory may not exist until the checkout completes. Pass an explicit cwd when running a command immediately after creation.

Return value

exec() resolves with an ExecResult after the command finishes.

interface ExecResult {
  exitCode: number | null;
  signal: string | null;
  error?: string;
  stdout: string;
  stderr: string;
}

number | null

required

The command’s exit code, or null when no exit code is available.

string | null

required

The signal that ended the command, or null when no signal is available.

string

Agent-reported failure detail, such as a command-not-found message.

string

required

The complete standard output decoded as UTF-8.

string

required

The complete standard error decoded as UTF-8.

A non-zero exit code does not reject the promise. Check exitCode to determine whether the command succeeded. The promise rejects for failures such as an invalid request, an aborted operation, a timeout, or a transport error.

More examples

Pass arguments containing spaces

Arguments containing spaces remain single arguments.

const devbox = await client.devboxes.get("sdk-example");
await devbox.exec(["printf", "%s\n", "hello world"]);

Stream command output

Stream output while retaining it in the returned result.

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.exec(["npm", "test"], {
  cwd: "/workspace",
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  timeoutMs: 10 * 60_000,
});

`shell()`

Use shell() when a command requires shell syntax such as pipelines, redirects, variable interpolation, or multiple statements.

Example

Run a script that chains two commands, then print its standard output:

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.shell("npm install && npm test");
process.stdout.write(result.stdout);

API reference

shell(script: string, options?: ShellOptions): Promise<ExecResult>

Arguments and options

string

required

The script to evaluate with the Devbox shell.

ShellOptions

All ExecOptions, plus the shell property.

Hide additional property

string

The shell executable. The SDK uses the Devbox’s configured shell when available and otherwise falls back to /bin/sh.

Return value

shell() returns the same ExecResult as exec(). A non-zero exit code resolves normally and must be checked by the caller.

More examples

Set the working directory and environment variables

const devbox = await client.devboxes.get("sdk-example");
await devbox.shell("npm install && npm test", {
  cwd: "/workspace",
  env: { CI: "true" },
});

Use a specific shell

const devbox = await client.devboxes.get("sdk-example");
await devbox.shell("echo $SHELL", { shell: "/bin/bash" });

`executions.start()`

Use executions.start() to start a command without waiting for it to finish. The promise resolves with a DevboxExecution handle as soon as the Devbox agent accepts the command. Unlike commands run with exec() and shell(), the command keeps running after the client disconnects. Use the handle to check status, follow output, wait for the result, or stop the command, from the same process or a later one. Like exec(), executions.start() passes arguments literally without invoking a shell.

Example

Start a test run, then wait for its result:

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.start(["npm", "test"], {
  cwd: "/workspace",
});
console.log(`Started ${execution.id}`);
const result = await execution.wait();
console.log(result.exitCode);

API reference

executions.start(argv: readonly string[], options?: StartExecOptions): Promise<DevboxExecution>

Arguments and options

readonly string[]

required

The executable followed by its arguments. The array must contain at least one item.

StartExecOptions

Options for starting the command.

Hide properties

string

The working directory. Absolute paths are used as provided. Relative paths resolve from the Devbox workspace directory.

Record<string, string>

Additional environment variables. Names must start with a letter or underscore and contain only letters, numbers, and underscores.

string | Uint8Array

Data provided to standard input. Strings are encoded as UTF-8.

AbortSignal

Cancels starting the command when the signal is aborted.

number

The timeout in milliseconds for activating the Devbox, connecting, and starting the command. It does not limit how long the command runs.

StartExecOptions has no onStdout or onStderr callbacks. Pass them to execution.wait(), or read output with execution.logs().

Return value

executions.start() resolves with a DevboxExecution handle.

interface DevboxExecution {
  readonly id: string;
  status(options?: OperationOptions): Promise<ExecutionStatus>;
  stop(options?: ExecutionStopOptions): Promise<void>;
  logs(options?: OperationOptions): AsyncIterableIterator<ExecutionLogChunk>;
  wait(options?: ExecutionWaitOptions): Promise<ExecResult>;
}

string

required

The execution ID assigned by the Devbox agent. Pass it to executions.get() to reattach to the execution later.

A handle refers to an execution held by the Devbox agent. It does not cache the command’s result, so every method call queries the agent. Execution IDs and retained output are local to the Devbox’s machine and may be lost when the machine is replaced or the execution is evicted.

The SDK never retries a start request automatically. If executions.start() rejects after the request was sent, the command may still have started. Use executions.list() to check before starting it again.

`executions.startShell()`

Use executions.startShell() to start a shell script without waiting for it to finish. It accepts the same options as executions.start(), plus shell, and evaluates the script with <shell> -lc <script>.

Example

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.startShell("npm install && npm run build", {
  cwd: "/workspace",
});
console.log(execution.id);

API reference

executions.startShell(script: string, options?: StartShellOptions): Promise<DevboxExecution>

Arguments and options

string

required

The script to evaluate with the Devbox shell.

StartShellOptions

All StartExecOptions, plus the shell property.

Hide additional property

string

The shell executable. The SDK uses the Devbox’s configured shell when available and otherwise falls back to /bin/sh.

Return value

executions.startShell() resolves with the same DevboxExecution handle as executions.start().

`executions.get()`

Use executions.get() to reattach to an execution by ID, for example from a different process than the one that started it.

Example

const devbox = await client.devboxes.get("sdk-example");
const executionId = "execution-id";
const execution = await devbox.executions.get(executionId);
console.log(await execution.status());

API reference

executions.get(id: string, options?: OperationOptions): Promise<DevboxExecution>

Arguments and options

string

required

The execution ID returned by executions.start() or executions.startShell(). The ID must not be empty.

OperationOptions

Supports signal and timeoutMs. See Shared operation options.

Return value

executions.get() resolves with a DevboxExecution handle. It rejects with ExecutionNotFoundError when the Devbox agent no longer retains an execution with that ID.

`executions.list()`

Use executions.list() to list the command executions the Devbox agent retains, including running and completed ones.

Example

const devbox = await client.devboxes.get("sdk-example");
const executions = await devbox.executions.list();
for (const execution of executions) {
  const status = await execution.status();
  console.log(execution.id, status.state);
}

API reference

executions.list(options?: OperationOptions): Promise<DevboxExecution[]>

Arguments and options

OperationOptions

Supports signal and timeoutMs. See Shared operation options.

Return value

executions.list() resolves with DevboxExecution handles for running and completed commands, including commands started by other clients, sorted by start time. It excludes operations the Devbox runs during boot.

`execution.status()`

Use execution.status() to check whether an execution is running or has completed.

Example

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.start(["sleep", "30"]);
const status = await execution.status();
if (status.state === "completed") {
  console.log(`Exited with ${status.exitCode}`);
}

API reference

status(options?: OperationOptions): Promise<ExecutionStatus>

Arguments and options

OperationOptions

Supports signal and timeoutMs. See Shared operation options.

Return value

execution.status() resolves with an ExecutionStatus. Check state to narrow the type.

type ExecutionStatus =
  | { state: "missing" }
  | { state: "running"; startedAt?: Date }
  | { state: "completed"; startedAt?: Date; completedAt: Date; exitCode: number; error?: string };

"missing" | "running" | "completed"

required

missing means the lookup succeeded but the Devbox agent no longer retains the execution. Transport failures reject instead of returning missing.

Date

When the command started, when the agent reports it.

Date

When the command completed. Present only when state is completed.

number

The command’s exit code. Present only when state is completed.

string

Agent-reported failure detail, such as a command-not-found message. Present only when state is completed.

`execution.logs()`

Use execution.logs() to stream an execution’s output. The iterator first replays the output the agent has retained, then follows live output until the command completes. The final chunk carries the command’s result.

Example

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.startShell("npm test");
for await (const chunk of execution.logs()) {
  process.stdout.write(chunk.stdout);
  process.stderr.write(chunk.stderr);
  if (chunk.result) {
    console.log(`Exited with ${chunk.result.exitCode}`);
  }
}

API reference

logs(options?: OperationOptions): AsyncIterableIterator<ExecutionLogChunk>

Arguments and options

OperationOptions

Supports signal and timeoutMs. Connecting to the Devbox is bounded by the client’s connectionTimeoutMs instead, and timeoutMs starts once the connection is established.

Return value

execution.logs() returns an async iterator of ExecutionLogChunk objects.

interface ExecutionLogChunk {
  stdout: Uint8Array;
  stderr: Uint8Array;
  result?: { exitCode: number; error?: string };
}

Uint8Array

required

Standard-output bytes in this chunk. May be empty.

Uint8Array

required

Standard-error bytes in this chunk. May be empty.

{ exitCode: number; error?: string }

The command’s exit code and any agent-reported failure detail. Present only on the chunk delivered after the command completes.

A failed command does not make the iterator throw; check result.exitCode. The iterator throws ExecutionNotFoundError when the execution is no longer retained, and IncompleteResponseError when the stream ends without a result. Each call opens an independent reader. Readers do not track a position and do not reconnect automatically. Breaking out of the loop or aborting signal closes only that reader and does not stop the command.

`execution.wait()`

Use execution.wait() to collect an execution’s output and resolve when the command completes. It returns the same ExecResult as exec().

Example

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.start(["npm", "test"]);
const result = await execution.wait({
  onStdout: (data) => process.stdout.write(data),
  timeoutMs: 10 * 60_000,
});
console.log(result.exitCode);

API reference

wait(options?: ExecutionWaitOptions): Promise<ExecResult>

Arguments and options

ExecutionWaitOptions

Options for collecting output.

Hide properties

number

default:"10485760"

The maximum combined size of standard output and standard error to collect, in bytes. The default is 10 MiB. When the output exceeds the limit, wait() rejects with ExecutionOutputLimitError. Use execution.logs() to process larger output without collecting it.

(data: Uint8Array) => void

Called for each standard-output chunk, including replayed output. Output is also collected in the returned result.

(data: Uint8Array) => void

Called for each standard-error chunk, including replayed output. Output is also collected in the returned result.

AbortSignal

Stops waiting when the signal is aborted.

number

The time to wait in milliseconds, starting once the connection to the Devbox is established.

wait() does not inherit options passed to executions.start().

Return value

execution.wait() resolves with an ExecResult, including when the command exits with a non-zero code or the agent reports a command error. It rejects with ExecutionNotFoundError when the execution is no longer retained. Aborting, timing out, or reaching maxOutputBytes stops only this wait. The command keeps running. Each call opens an independent reader and replays the retained output, so callbacks receive that output again on every call.

`execution.stop()`

Use execution.stop() to request that a running command terminate. The promise resolves when the agent accepts the request, without waiting for the command to exit. Use status(), logs(), or wait() to observe completion.

Example

const devbox = await client.devboxes.get("sdk-example");
const execution = await devbox.executions.start(["sleep", "600"]);
await execution.stop();
const result = await execution.wait();
console.log(result.exitCode);

API reference

stop(options?: ExecutionStopOptions): Promise<void>

Arguments and options

ExecutionStopOptions

Options for stopping the command.

Hide properties

"graceful" | "force"

default:"graceful"

graceful sends SIGTERM and does not escalate automatically. force sends SIGKILL.

AbortSignal

Cancels the request when the signal is aborted.

number

The timeout in milliseconds for connecting and sending the stop request.

The signal goes to the command’s original process group until its leader exits. Processes that detach from that group or outlive the leader are not signaled. Stopping a command that has already completed, or stopping it again, has no effect. To escalate, call stop({ mode: "force" }) after a graceful stop. The method rejects with ExecutionNotFoundError when the execution is no longer retained.

Aborting or timing out a stop request cannot undo a stop that the agent has already accepted.

Choose a command method

Use	When
`exec()`	You have an executable and structured arguments and do not need shell evaluation. This is the safer default for arguments derived from external input.
`shell()`	You need pipelines, redirects, variable interpolation, command chaining, or another shell feature.
`executions.start()` or `executions.startShell()`	The command must keep running after the client disconnects, or you want to start it now and collect the result later or from another process.

Use interactive terminals

Open and control interactive terminal sessions.

Create and manage Devboxes

Create a Devbox and control its lifecycle.

Handle errors and timeouts

Cancel operations and handle SDK failures.

​exec()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Pass arguments containing spaces

​Stream command output

​shell()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Set the working directory and environment variables

​Use a specific shell

​executions.start()

​Example

​API reference

​Arguments and options

​Return value

​executions.startShell()

​Example

​API reference

​Arguments and options

​Return value

​executions.get()

​Example

​API reference

​Arguments and options

​Return value

​executions.list()

​Example

​API reference

​Arguments and options

​Return value

​execution.status()

​Example

​API reference

​Arguments and options

​Return value

​execution.logs()

​Example

​API reference

​Arguments and options

​Return value

​execution.wait()

​Example

​API reference

​Arguments and options

​Return value

​execution.stop()

​Example

​API reference

​Arguments and options

​Choose a command method

​Related documentation

Use interactive terminals

Create and manage Devboxes

Handle errors and timeouts

`exec()`

Example

API reference

Arguments and options

Return value

More examples

Pass arguments containing spaces

Stream command output

`shell()`

Example

API reference

Arguments and options

Return value

More examples

Set the working directory and environment variables

Use a specific shell

`executions.start()`

Example

API reference

Arguments and options

Return value

`executions.startShell()`

Example

API reference

Arguments and options

Return value

`executions.get()`

Example

API reference

Arguments and options

Return value

`executions.list()`

Example

API reference

Arguments and options

Return value

`execution.status()`

Example

API reference

Arguments and options

Return value

`execution.logs()`

Example

API reference

Arguments and options

Return value

`execution.wait()`

Example

API reference

Arguments and options

Return value

`execution.stop()`

Example

API reference

Arguments and options

Choose a command method

Related documentation