Runloop Devbox-ShellTools API

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