Execute Commands on a Devbox

Run and execute code at scale

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.

Python

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

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.

Python

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()

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.

1. Execute a command and stream output

   Python

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

2. Execute a command and stream STDOUT and STDERR

   Python

   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) }
   )
   

Isolated Shells

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

Python

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())  # ""

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:

1. Create and enter new directory

   Python

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

2. Check new working directory is preserved

   Python

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

3. Environment variables are preserved

   Python

   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" }
   )
   await exec_result.stdout() == "123"