Execute Commands on a Devbox

Start with the Runloop Quickstart to use the examples below.

Execute Commands

Once your Devbox is in a ready state you can execute commands to interact with it. The primary method of executing commands is the exec command.

result = await devbox.cmd.exec("echo Hello World")
print(f"Command output: {await result.stdout()}")
print(f"Exit code: {result.exit_code}")

const result = await devbox.cmd.exec("echo Hello World");
console.log(`Command output: ${await result.stdout()}`);
console.log(`Exit code: ${result.exitCode}`);

Long Running Commands

You can use exec_async to return a command object that you can use to control command execution. This allows you to manage commands by running them in the background and control their lifecycle.

This function will return once the devbox has started the command execution. You can use the command object to control the command execution.

command = await devbox.cmd.exec_async(
  "HOST=0.0.0.0; npx run http-server")
# When you are done, you can stop the command
await command.kill()

const command = await devbox.cmd.execAsync(
  "HOST=0.0.0.0; npx run http-server");
// When you are done, you can stop the command
await command.kill();

Streaming Output

You can stream stdout and stderr logs in real-time, this works for exec and execAsync.

Streaming is ideal for long-running commands where you want to see output as it’s generated, such as builds, tests, or log tailing.

Execute a command and stream output

command = await devbox.cmd.exec_async(
  "HOST=0.0.0.0; npx run http-server",
  output=lambda x: print(x)
)

const command = await devbox.cmd.execAsync(
  "HOST=0.0.0.0; npx run http-server",
  { output: (x: string) => console.log(x) }
);

Execute a command and stream STDOUT and STDERR

command = await devbox.cmd.exec_async(
  "HOST=0.0.0.0; npx run http-server",
  stdout=lambda x: print(x),
  stderr=lambda x: print(x)
)

const command = await devbox.cmd.execAsync(
  "HOST=0.0.0.0; npx run http-server",
  { stdout: (x: string) => console.log(x),
    stderr: (x: string) => console.error(x) }
);

Isolated Shells

By default, every Devbox command runs in a new shell session so the state of the shell is not preserved between commands.

await devbox.cmd.exec("export MY_VAR=123")

## New shell means MY_VAR is not defined
exec_result = await devbox.cmd.exec("echo $MY_VAR")
print(await exec_result.stdout())  # ""

await devbox.cmd.exec("export MY_VAR=123");

// New shell means MY_VAR is not defined
const execResult= await devbox.cmd.exec("echo $MY_VAR");
console.log(await execResult.stdout());  // ""

Stateful Shells

You can use the shell_name parameter to use a ‘stateful’ shell. This means that the shell will maintain its state across commands including environment variables and working directory. As an example, let’s create a series of interdependent commands that need to be run in the same shell:

Create and enter new directory

await devbox.cmd.exec(
  "mkdir test-area && cd test-area",
  shell_name="my-shell"
)

await devbox.cmd.exec(
  "mkdir test-area && cd test-area",
  { shell_name: "my-shell" }
)

Check new working directory is preserved

exec_result = await devbox.cmd.exec(
  "pwd", shell_name="my-shell")
print(await exec_result.stdout())  # /home/user/test-area

const execResult = await devbox.cmd.exec(
  "pwd", { shell_name: "my-shell" });
console.log(await execResult.stdout());  // /home/user/test-area

Environment variables are preserved

await devbox.cmd.exec(
  "export MY_VAR=123",
  shell_name="my-shell"
)
exec_result = await devbox.cmd.exec(
  "echo $MY_VAR",
  shell_name="my-shell"
)
print(await exec_result.stdout())  # 123

await devbox.cmd.exec(
  "export MY_VAR=123",
  { shell_name: "my-shell" }
);
const execResult = await devbox.cmd.exec(
  "echo $MY_VAR",
  { shell_name: "my-shell" }
);
console.log(await execResult.stdout());  // 123