Sign in
Devbox
Devbox-ShellTools

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

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.

post/v1/devboxes/{id}/execute

Path parameters

idstring required

The Devbox ID.

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. Operation is not killed. Max is 600 seconds.

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.

Changes