openapi: 3.0.3 info: title: Runloop agents Devbox-ShellTools API version: '0.1' description: Register, version, and mount Agents — packaged agent definitions sourced from Git, npm, pip, or storage objects that can be installed on Devboxes for fast, reproducible agent execution. contact: name: Runloop AI Support url: https://runloop.ai email: support@runloop.ai servers: - url: https://api.runloop.ai description: Runloop API variables: {} security: - bearerAuth: [] tags: - name: Devbox-ShellTools paths: /pty/{session_name}: get: tags: - Devbox-ShellTools summary: Create or reconnect to a PTY session. description: 'Looks up the PTY session identified by the path session_name and either reconnects to the existing session or creates it if it does not yet exist. The session_name is a client-chosen session identifier, not an opaque server-issued ID. It must be non-empty (1..=256 chars) and use only ASCII letters, digits, ''-'' and ''_''. A newly created PTY session starts an interactive bash shell on the Devbox. Optional cols and rows query parameters apply an initial terminal size before any I/O; they must both be present and in the range 1..=1000 to take effect. The response returns a PtyConnectView containing connect_url (a server-relative path to the WebSocket data plane), idle_ttl_seconds (how long this session is retained after the last client disconnects), and the resulting cols/rows. The interactive byte stream itself is intentionally not modeled in OpenAPI; see the controller-level documentation for the WebSocket close-code conventions. The single-attach contract is enforced when a client opens the WebSocket data plane, not on this bootstrap call: bootstrap always succeeds for a valid session_name, even if another client is currently attached. Rejection of a second concurrent attach happens at WebSocket upgrade time. If the active client disconnects, the session is preserved for the idle TTL so a later connect using the same session_name resumes the same shell. After the TTL expires, after an explicit close control action, or after the underlying Devbox lifecycle replaces the PTY process (such as through suspend/resume), a later request with the same session_name creates a fresh PTY session without the previous shell state. Documentation note: this operation is published from mux strictly as an OpenAPI contract stub for the PTY service control plane. It is not evidence that mux itself serves the interactive PTY transport.' operationId: connectDevboxPtySession parameters: - name: session_name in: path description: The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. Reusing the same name reconnects to the same logical PTY session when it is still available. required: true deprecated: false allowEmptyValue: false schema: type: string - name: cols in: query description: Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored. required: false deprecated: false allowEmptyValue: false schema: type: integer format: int32 - name: rows in: query description: Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored. required: false deprecated: false allowEmptyValue: false schema: type: integer format: int32 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PtyConnectView' '400': description: Malformed session_name (alphabet or length out of range). '503': description: PTY session could not be spawned (host resource exhaustion). deprecated: false /pty/{session_name}/control: post: tags: - Devbox-ShellTools summary: Send a control command to a PTY session. description: 'Applies a PTY control operation to an existing session. The action field selects the operation; the other fields in PtyControlParameters are interpreted only when they are relevant to the chosen action. resize: cols and rows are required and must each be in 1..=1000. A 0 or out-of-range value returns 400. The new winsize is applied to the PTY master and the kernel delivers SIGWINCH to the foreground process group. signal: signal is the POSIX signal name (for example ''SIGTERM'', ''SIGHUP'', ''SIGINT'', ''SIGUSR1''). Unknown signal names return 400. The signal is delivered to the slave''s foreground process group via killpg(2). If the shell has already exited and there is no foreground process group, returns 400. close: terminates the session. Sends SIGHUP to the foreground process group (best-effort; ignored if the shell has already exited) and drops the session from the server''s session cache. A subsequent connect with the same session_name will create a fresh PTY session. Documentation note: this operation is published from mux strictly as an OpenAPI contract stub for the PTY service control plane. It is not evidence that mux itself serves the interactive PTY transport.' operationId: controlDevboxPtySession parameters: - name: session_name in: path description: The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PtyControlParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PtyControlResultView' '400': description: 'Invalid action parameters: out-of-range cols/rows on resize, unknown signal name on signal, or no foreground process group on signal.' '404': description: PTY session not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}: get: tags: - Devbox-ShellTools summary: Get status of an asynchronous execution on a Devbox. description: Get the latest status of a previously launched asynchronous execuction including stdout/error and the exit code if complete. operationId: queryAsyncCommand parameters: - name: devbox_id in: path description: The Devbox ID required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Execution ID required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/kill: post: tags: - Devbox-ShellTools summary: Kill an asynchronous execution currently running on a devbox description: Kill a previously launched asynchronous execution if it is still running by killing the launched process. Optionally kill the entire process group. operationId: killAsyncExecution parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxKillExecutionRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox or Execution not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/send_std_in: post: tags: - Devbox-ShellTools summary: Send Content to Std In for a running execution. description: Send content to the Std In of a running execution. operationId: sendStdIn parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxSendStdInRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxSendStdInResult' '404': description: Devbox or Execution not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/wait_for_status: post: tags: - Devbox-ShellTools summary: Wait for an asynchronous execution to reach a specific status. description: Polls the asynchronous execution's status until it reaches one of the desired statuses or times out. Max is 25 seconds. operationId: waitForCommandCompletion parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxWaitForCommandRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '400': description: Invalid status provided or Devbox not in proper state. '404': description: Devbox or Execution not found. '408': description: Timeout waiting for command completion. deprecated: false /v1/devboxes/{id}/execute: post: tags: - Devbox-ShellTools summary: Execute a command with a known ID, optimistically waiting for completion description: '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.' operationId: executeCommand parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxStartExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. '408': description: Command timed out. deprecated: false /v1/devboxes/{id}/execute_async: post: tags: - Devbox-ShellTools summary: Asynchronously execute a command via the Devbox shell description: Execute the given command in the Devbox shell asynchronously and returns the execution that can be used to track the command's progress. operationId: execAsyncCommand parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxCreateExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/execute_sync: post: tags: - Devbox-ShellTools summary: (Deprecated, please use /execute_async) Synchronously execute a shell command on a Devbox description: 'Execute a bash command in the Devbox shell, await the command completion and return the output. Note: attach_stdin parameter is not supported for synchronous execution.' operationId: execSyncCommand parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxCreateExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxExecutionDetailView' deprecated: true components: schemas: DevboxSendStdInRequest: type: object additionalProperties: false properties: text: type: string nullable: true description: Text to send to std in of the running execution. signal: $ref: '#/components/schemas/SignalType' nullable: true description: Signal to send to std in of the running execution. DevboxStartExecutionParameters: type: object additionalProperties: false properties: command_id: type: string description: The command ID in UUIDv7 string format for idempotency and tracking command: type: string description: 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_name: type: string nullable: true description: 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_timeout: type: integer format: int32 nullable: true description: Timeout in seconds to wait for command completion, up to 25 seconds. Defaults to 25 seconds. Operation is not killed. required: - command_id - command DevboxCreateExecutionParameters: type: object additionalProperties: false properties: command: type: string description: 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_name: type: string nullable: true description: 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. attach_stdin: type: boolean nullable: true description: Whether to attach stdin streaming for async commands. Not valid for execute_sync endpoint. Defaults to false if not specified. required: - command DevboxKillExecutionRequest: type: object additionalProperties: false properties: kill_process_group: type: boolean nullable: true description: 'Whether to kill the entire process group (default: false). If true, kills all processes in the same process group as the target process.' DevboxExecutionDetailView: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command was executed. stdout: type: string description: Standard out generated by command. stderr: type: string description: Standard error generated by command. exit_status: type: integer format: int32 description: Exit status of command execution. shell_name: type: string nullable: true description: Shell name. required: - devbox_id - stdout - stderr - exit_status PtyControlAction: type: string enum: - resize - signal - close DevboxSendStdInResult: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command is executing. execution_id: type: string description: Execution id that received the stdin. success: type: boolean description: Whether the stdin was successfully sent. required: - devbox_id - execution_id - success DevboxWaitForCommandRequest: type: object additionalProperties: false properties: statuses: type: array items: $ref: '#/components/schemas/DevboxExecutionStatus' description: The command execution statuses to wait for. At least one status must be provided. The command will be returned as soon as it reaches any of the provided statuses. timeout_seconds: type: integer format: int32 nullable: true description: (Optional) Timeout in seconds to wait for the status, up to 25 seconds. Defaults to 25 seconds. required: - statuses PtyConnectView: type: object additionalProperties: false properties: session_name: type: string status: type: string protocol_version: type: string connect_url: type: string created: type: boolean attached: type: boolean cols: type: integer format: int32 rows: type: integer format: int32 idle_ttl_seconds: type: integer format: int64 required: - created - attached PtyControlResultView: type: object additionalProperties: false properties: session_name: type: string status: type: string PtyControlParameters: type: object additionalProperties: false properties: action: $ref: '#/components/schemas/PtyControlAction' cols: type: integer format: int32 rows: type: integer format: int32 signal: type: string SignalType: type: string enum: - EOF - INTERRUPT DevboxExecutionStatus: type: string enum: - queued - running - completed DevboxAsyncExecutionDetailView: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command was executed. execution_id: type: string description: Ephemeral id of the execution in progress. status: $ref: '#/components/schemas/DevboxExecutionStatus' description: Current status of the execution. shell_name: type: string nullable: true description: Shell name. stdout: type: string nullable: true description: Standard out generated by command. This field will remain unset until the execution has completed. stderr: type: string nullable: true description: Standard error generated by command. This field will remain unset until the execution has completed. exit_status: type: integer format: int32 nullable: true description: Exit code of command execution. This field will remain unset until the execution has completed. stdout_truncated: type: boolean nullable: true description: Indicates whether the stdout was truncated due to size limits. stderr_truncated: type: boolean nullable: true description: Indicates whether the stderr was truncated due to size limits. required: - devbox_id - execution_id - status securitySchemes: bearerAuth: scheme: bearer type: http