Execute Commands
The Runloop shell APIs provide different methods for command execution to optimize for both performance and reliability.Choosing the Right Method
| Method | Use Case | Benefits | Python | TypeScript |
|---|---|---|---|---|
| Optimistic Execute | Most scenarios | Optimistic execution, automatic fallback, configurable timeout | execute | executeAndAwaitCompletion |
| Simple Execute | Simple commands in tools | Simplified logic, automatically waits for completion, cleaner code | execute_and_await_completion | executeAndAwaitCompletion |
| Async Execute | Advanced async workflows | Full control over async execution, multiple concurrent commands | execute_async | executeAsync |
Execute (Recommended)
Theexecute endpoint is the recommended method for most command execution scenarios. It combines the best aspects of synchronous and asynchronous execution with optimistic execution that waits up to 15 seconds (configurable up to 60s) for command completion before falling back to an async polling pattern.
Key benefits:
- Single API call for fast commands (< 15s default)
- Automatic fallback to async polling for longer operations
- No API Gateway timeout risks
- Maintains durability and correctness
- Configurable wait time (up to 60s)
- For quick commands, you can also use
executeAndAwaitCompletion/execute_and_await_completionwhich simplifies the logic by automatically waiting for command completion.
Migration from
execute_sync: The new execute endpoint is a drop-in replacement for execute_sync with improved reliability and performance. Simply replace execute_sync calls with execute - no other code changes required.The
execute endpoint is optimized for all command types. For short-lived commands (< 15s), it behaves like a synchronous call. For longer commands, it automatically uses async polling while maintaining reliability.Using
execute directly: When making calls to the execute endpoint, you must include a uuidv7 parameter in your request body to ensure proper execution tracking and idempotency.Asynchronous Commands (Advanced)
For specific use cases where you need explicit async control,execute_async remains available. This is useful when you have specific async workflow requirements or need to manage multiple long-running commands independently.
1
Launch an async command
2
Retrieve the Status of the Async Command including the latest output
3
(Optionally) Stream output in real-time
You can stream stdout and stderr logs in real-time using Server-Sent Events (SSE) for async executions:
Streaming is ideal for long-running commands where you want to see output as it’s generated, such as builds, tests, or log tailing.
4
(Optionally) Send input to stdin for interactive commands
For commands that expect interactive input, you can send content to stdin while the execution is running:
This is useful for interactive commands that wait for user input, such as prompts, REPLs, or commands that read from stdin.
5
(Optionally) Kill the async command if needed
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.Using Stateful Shells
Alternatively, you can use theshell_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
2
Create and enter new directory
3
Verify new working directory is preserved!