Execute a command in the named shell and wait for it to complete. Optionally provide callbacks to stream logs in real-time.
The command will execute in the persistent shell session, maintaining environment variables and the current working directory from previous commands. Commands are queued and execute sequentially - only one command runs at a time in the named shell.
When callbacks are provided, this method waits for both the command to complete AND all streaming data to be processed before returning.
The command to execute
Optionalparams: Omit<DevboxExecuteParams, "shell_name" | "command" | "command_id"> & ExecuteStreamingCallbacksOptional parameters (shell_name is automatically set)
Optionaloptions: RequestOptions<unknown> & {Request options with optional polling configuration
ExecutionResult with stdout, stderr, and exit status
const shell = devbox.shell('my-session');
// Simple execution
const result = await shell.exec('ls -la');
console.log(await result.stdout());
// With streaming callbacks
const result = await shell.exec('npm install', {
stdout: (line) => process.stdout.write(line),
stderr: (line) => process.stderr.write(line),
});
// Stateful execution - environment and CWD are preserved
await shell.exec('cd /app');
await shell.exec('export NODE_ENV=production');
const result = await shell.exec('npm start'); // Runs in /app with NODE_ENV=production
Execute a command in the named shell asynchronously without waiting for completion. Optionally provide callbacks to stream logs in real-time as they are produced.
The command will execute in the persistent shell session, maintaining environment variables and the current working directory from previous commands. Commands are queued and execute sequentially - only one command runs at a time in the named shell.
Callbacks fire in real-time as logs arrive. When you call execution.result(), it will wait for both the command to complete and all streaming to finish.
The command to execute
Optionalparams: Omit<DevboxExecuteAsyncParams, "shell_name" | "command"> & ExecuteStreamingCallbacksOptional parameters (shell_name is automatically set)
Optionaloptions: RequestOptions<unknown>Request options
Execution object for tracking and controlling the command
const shell = devbox.shell('my-session');
const execution = await shell.execAsync('long-running-task.sh', {
stdout: (line) => console.log(`[LOG] ${line}`),
});
// Do other work while command runs...
// Note: if you call shell.exec() or shell.execAsync() again, it will queue
// and wait for this command to complete first
const result = await execution.result();
if (result.success) {
console.log('Task completed successfully!');
}
Named shell operations for a devbox. Provides methods for executing commands in a persistent, stateful shell session.
Remarks
Use Devbox.shell to create a named shell instance. If you use the same shell name, it will re-attach to the existing named shell, preserving its state (environment variables, current working directory, etc.).
Named shells are stateful and maintain environment variables and the current working directory (CWD) across commands. Commands executed through the same named shell instance will execute sequentially - the shell can only run one command at a time with automatic queuing. This ensures that environment changes and directory changes from one command are preserved for the next command.
Example