Full example

​
Running Commands Synchronously vs Asynchronously

The Runloop shell APIs support both synchronous for immediate results and asynchronous for long-running commands or daemons.

​
Synchronous Commands

Synchronous commands allow you to run commands and block until you get the command results including stdout, stderr, and the exit code of the command process. 
curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_sync' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "echo Hello World",
  }'
Synchronous commands using execute_sync are intended to be used for short-lived commands that return almost immediately. Use execute_async where possible.

​
Asynchronous Commands

Asynchronous commands allow you to run commands and not block until you get the command results. This can be useful for long-running commands or daemons such as launching dev servers or background processes.
1

Launch an async command

curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_async' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "while true; do echo 'Hello World'; sleep 1; done",
  }'
2

Retrieve the Status of the Async Command including the latest output

curl -X GET 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/executions/<EXECUTION_ID>' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json'
3

(Optionally) Kill the async command if needed

curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/executions/<EXECUTION_ID>/kill' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

​
Isolated vs StatefulShells

By default, every Devbox command is run in an isolated shell. This means that each command is executed in a new shell session, and the state of the shell is not preserved between commands. 
curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_sync' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"command": "echo Hello World"}'

​
Using Stateful Shells

Alternatively, 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

Check initial directory

curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_sync' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "pwd",
    "shell_name": "my-shell"
  }'
2

Create and enter new directory

curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_sync' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "mkdir mynewfolder && cd mynewfolder",
    "shell_name": "my-shell"
  }'
3

Verify new working directory is preserved!

curl -X POST 'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/execute_sync' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "pwd",
    "shell_name": "my-shell"
  }'