Devbox
Devbox-ShellTools

Execute a command with a known ID, optimistically waiting for completion

Changed on

Execute a command with a known command ID on a devbox, optimistically waiting for it to complete within the specified timeout. If it completes in time, return the result. If not, return a status indicating the command is still running. Note: attach_stdin parameter is not supported; use execute_async for stdin support.

post/v1/devboxes/{id}/execute

Request

  • Base URL: https://api.runloop.ai
  • URL: https://api.runloop.ai/v1/devboxes/{id}/execute
  • Auth: HTTP bearer

Path parameters

idstring required

The Devbox ID.

Query parameters

last_nstring

Last n lines of standard error / standard out to return (default: 100)

Request body

command_idstring required

The command ID in UUIDv7 string format for idempotency and tracking

commandstring required

The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell.

shell_namestring nullable

The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.

optimistic_timeoutinteger nullable

Timeout in seconds to wait for command completion, up to 25 seconds. Defaults to 25 seconds. Operation is not killed.

Response

OK

devbox_idstring required

Devbox id where command was executed.

execution_idstring required

Ephemeral id of the execution in progress.

status'queued' | 'running' | 'completed' required
shell_namestring nullable

Shell name.

stdoutstring nullable

Standard out generated by command. This field will remain unset until the execution has completed.

stderrstring nullable

Standard error generated by command. This field will remain unset until the execution has completed.

exit_statusinteger nullable

Exit code of command execution. This field will remain unset until the execution has completed.

stdout_truncatedboolean nullable

Indicates whether the stdout was truncated due to size limits.

stderr_truncatedboolean nullable

Indicates whether the stderr was truncated due to size limits.

Changes

  • d3ddb452754cRevision changes
    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

  • 63df0e3eb49dRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status