openapi: 3.0.0
info:
  contact: {}
  description: API for manipulating filesystem, processes and network.
  title: Sandbox API
  version: 0.0.1
paths:
  "/codegen/fastapply/{path}":
    put:
      description: >-
        Uses the configured LLM provider (Relace or Morph) to apply a code edit to the original content.


        To use this endpoint as an agent tool, follow these guidelines:


        Use this tool to make an edit to an existing file. This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.


        When writing the edit, you should specify each edit in sequence, with the special comment "// ... existing code ..." to represent unchanged code in between edited lines.


        Example format:

        // ... existing code ...

        FIRST_EDIT

        // ... existing code ...

        SECOND_EDIT

        // ... existing code ...

        THIRD_EDIT

        // ... existing code ...


        You should still bias towards repeating as few lines of the original file as possible to convey the change. But, each edit should contain minimally sufficient context of unchanged lines around the code you're editing to resolve ambiguity.


        DO NOT omit spans of pre-existing code (or comments) without using the "// ... existing code ..." comment to indicate its absence. If you omit the existing code comment, the model may inadvertently delete these lines.


        If you plan on deleting a section, you must provide context before and after to delete it. If the initial code is "Block 1\nBlock 2\nBlock 3", and you want to remove Block 2, you would output "// ... existing code ...\nBlock 1\nBlock 3\n// ... existing code ...".


        Make sure it is clear what the edit should be, and where it should be applied. Make edits to a file in a single edit_file call instead of multiple edit_file calls to the same file. The apply model can handle many distinct edits at once.
      parameters:
        - description: Path to the file to edit (relative to workspace)
          in: path
          name: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplyEditRequest"
        description: Code edit request
        required: true
      responses:
        "200":
          description: Code edit applied successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplyEditResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity - failed to process the request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Service unavailable - no provider configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Apply code edit
      tags:
        - fastapply
  "/codegen/reranking/{path}":
    get:
      description: >-
        Uses Relace's code reranking model to find the most relevant files for a given query. This is useful as a first pass in agentic exploration to narrow down the search space.


        Based on: https://docs.relace.ai/docs/code-reranker/agent


        Query Construction: The query can be a short question or a more detailed conversation with the user request included. For a first pass, use the full conversation; for subsequent calls, use more targeted questions.


        Token Limit and Score Threshold: For 200k token context models like Claude 4 Sonnet, recommended defaults are scoreThreshold=0.5 and tokenLimit=30000.


        The response will be a list of file paths and contents ordered from most relevant to least relevant.
      parameters:
        - description: Path to search in (relative to workspace)
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Natural language query to search for
          in: query
          name: query
          required: true
          schema:
            type: string
        - description: "Minimum relevance score (default: 0.5)"
          in: query
          name: scoreThreshold
          schema:
            type: number
        - description: "Maximum tokens to return (default: 30000)"
          in: query
          name: tokenLimit
          schema:
            type: integer
        - description: Regex pattern to filter files (e.g., .*\\.ts$ for TypeScript files)
          in: query
          name: filePattern
          schema:
            type: string
      responses:
        "200":
          description: Relevant files found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RerankingResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity - failed to process the request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Service unavailable - Relace not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Code reranking/semantic search
      tags:
        - codegen
  /drives/mount:
    get:
      description: Returns a list of all currently mounted drives managed by blfs
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriveListResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - BearerAuth: []
      summary: List currently mounted drives
      tags:
        - drive
    post:
      description: Mounts an agent drive using the blfs binary to a local path, optionally mounting a subpath within the drive
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DriveMountRequest"
        description: Drive attachment parameters
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriveMountResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - BearerAuth: []
      summary: Attach a drive to a local path
      tags:
        - drive
  "/drives/mount/{mountPath}":
    delete:
      description: Unmounts a previously mounted drive from the specified local path
      parameters:
        - description: Mount path to detach (must start with /, e.g. /mnt/test)
          in: path
          name: mountPath
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriveUnmountResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - BearerAuth: []
      summary: Detach a drive from a local path
      tags:
        - drive
  "/filesystem-content-search/{path}":
    get:
      description: Searches for text content inside files using ripgrep. Returns matching lines with context.
      parameters:
        - description: Directory path to search in
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Text to search for
          in: query
          name: query
          required: true
          schema:
            type: string
        - description: "Case sensitive search (default: false)"
          in: query
          name: caseSensitive
          schema:
            type: boolean
        - description: "Maximum number of results to return (default: 100)"
          in: query
          name: maxResults
          schema:
            type: integer
        - description: File pattern to include (e.g., *.go)
          in: query
          name: filePattern
          schema:
            type: string
        - description: "Comma-separated directory names to skip (default: node_modules,vendor,.git,dist,build,target,__pycache__,.venv,.next,coverage)"
          in: query
          name: excludeDirs
          schema:
            type: string
      responses:
        "200":
          description: Content search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentSearchResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Search for text content in files
      tags:
        - filesystem
  "/filesystem-find/{path}":
    get:
      description: Finds files and directories using the find command.
      parameters:
        - description: Path to search in (e.g., /home/user/projects)
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Type of search (file or directory)
          in: query
          name: type
          schema:
            type: string
        - description: Comma-separated file patterns to include (e.g., *.go,*.js)
          in: query
          name: patterns
          schema:
            type: string
        - description: "Maximum number of results to return (default: 20). If set to 0, all results will be returned."
          in: query
          name: maxResults
          schema:
            type: integer
        - description: "Comma-separated directory names to skip (default: node_modules,vendor,.git,dist,build,target,__pycache__,.venv,.next,coverage). Use empty string to skip no directories."
          in: query
          name: excludeDirs
          schema:
            type: string
        - description: "Exclude hidden files and directories (default: true)"
          in: query
          name: excludeHidden
          schema:
            type: boolean
      responses:
        "200":
          description: Find results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Find files and directories
      tags:
        - filesystem
  /filesystem-multipart:
    get:
      description: List all active multipart uploads
      responses:
        "200":
          description: List of active uploads
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipartListUploadsResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: List multipart uploads
      tags:
        - filesystem
  "/filesystem-multipart/{uploadId}/abort":
    delete:
      description: Abort a multipart upload and clean up all parts
      parameters:
        - description: Upload ID
          in: path
          name: uploadId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Upload aborted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Upload not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Abort multipart upload
      tags:
        - filesystem
  "/filesystem-multipart/{uploadId}/complete":
    post:
      description: Complete a multipart upload by assembling all parts
      parameters:
        - description: Upload ID
          in: path
          name: uploadId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultipartCompleteRequest"
        description: List of parts
        required: true
      responses:
        "200":
          description: Upload completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Upload not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Complete multipart upload
      tags:
        - filesystem
  "/filesystem-multipart/{uploadId}/part":
    put:
      description: Upload a single part of a multipart upload
      parameters:
        - description: Upload ID
          in: path
          name: uploadId
          required: true
          schema:
            type: string
        - description: Part number (1-10000)
          in: query
          name: partNumber
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: Part data
                  type: string
                  format: binary
              required:
                - file
        required: true
      responses:
        "200":
          description: Part uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipartUploadPartResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Upload not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Upload part
      tags:
        - filesystem
  "/filesystem-multipart/{uploadId}/parts":
    get:
      description: List all uploaded parts for a multipart upload
      parameters:
        - description: Upload ID
          in: path
          name: uploadId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of parts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipartListPartsResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Upload not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: List parts
      tags:
        - filesystem
  "/filesystem-multipart/initiate/{path}":
    post:
      description: Initiate a multipart upload session for a file
      parameters:
        - description: File path
          in: path
          name: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultipartInitiateRequest"
        description: Optional permissions
      responses:
        "200":
          description: Upload session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipartInitiateResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Initiate multipart upload
      tags:
        - filesystem
  "/filesystem-search/{path}":
    get:
      description: Performs fuzzy search on filesystem paths using fuzzy matching algorithm. Optimized alternative to find and grep commands.
      parameters:
        - description: Path to search in (e.g., /home/user/projects)
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: "Maximum number of results to return (default: 20)"
          in: query
          name: maxResults
          schema:
            type: integer
        - description: Comma-separated file patterns to include (e.g., *.go,*.js)
          in: query
          name: patterns
          schema:
            type: string
        - description: "Comma-separated directory names to skip (default: node_modules,vendor,.git,dist,build,target,__pycache__,.venv,.next,coverage). Use empty string to skip no directories."
          in: query
          name: excludeDirs
          schema:
            type: string
        - description: "Exclude hidden files and directories (default: true)"
          in: query
          name: excludeHidden
          schema:
            type: boolean
      responses:
        "200":
          description: Fuzzy search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FuzzySearchResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Fuzzy search for files and directories
      tags:
        - filesystem
  "/filesystem/{path}":
    delete:
      description: Delete a file or directory
      parameters:
        - description: File or directory path
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Delete directory recursively
          in: query
          name: recursive
          schema:
            type: boolean
      responses:
        "200":
          description: Success message
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: File or directory not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Delete file or directory
      tags:
        - filesystem
    get:
      description: Get content of a file or listing of a directory. Use Accept header to control response format for files.
      parameters:
        - description: File or directory path
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Force download mode for files
          in: query
          name: download
          schema:
            type: boolean
      responses:
        "200":
          description: Directory listing
          content:
            application/json:
              schema:
                oneOf:
                    - $ref: "#/components/schemas/Directory"
                    - $ref: "#/components/schemas/FileWithContent"
                    - type: string
                      format: binary
            application/octet-stream:
              schema:
                oneOf:
                    - $ref: "#/components/schemas/Directory"
                    - $ref: "#/components/schemas/FileWithContent"
                    - type: string
                      format: binary
        "404":
          description: File or directory not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Get file or directory information
      tags:
        - filesystem
    put:
      description: Create or update a file or directory
      parameters:
        - description: File or directory path
          in: path
          name: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileRequest"
        description: File or directory details
        required: true
      responses:
        "200":
          description: Success message
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Create or update a file or directory
      tags:
        - filesystem
  "/filesystem/tree/{path}":
    delete:
      description: Delete a directory tree recursively
      parameters:
        - description: Root directory path
          in: path
          name: path
          required: true
          schema:
            type: string
        - description: Delete directory recursively
          in: query
          name: recursive
          schema:
            type: boolean
      responses:
        "200":
          description: Directory deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Delete directory tree
      tags:
        - filesystem
    get:
      description: Get a recursive directory tree structure starting from the specified path
      parameters:
        - description: Root directory path
          in: path
          name: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Directory tree
          content:
            application/json:
              schema:
                oneOf:
                    - $ref: "#/components/schemas/Directory"
                    - $ref: "#/components/schemas/FileWithContent"
                    - type: string
                      format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Get directory tree
      tags:
        - filesystem
    put:
      description: Create or update multiple files within a directory tree structure
      parameters:
        - description: Root directory path
          in: path
          name: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TreeRequest"
        description: Map of file paths to content
        required: true
      responses:
        "200":
          description: Updated directory tree
          content:
            application/json:
              schema:
                oneOf:
                    - $ref: "#/components/schemas/Directory"
                    - $ref: "#/components/schemas/FileWithContent"
                    - type: string
                      format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Create or update directory tree
      tags:
        - filesystem
  /health:
    get:
      description: >-
        Returns health status and system information including upgrade count and binary details

        Also includes last upgrade attempt status with detailed error information if available
      responses:
        "200":
          description: Health status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
      summary: Health check
      tags:
        - system
  "/network/process/{pid}/monitor":
    delete:
      description: Stop monitoring for new ports opened by a process
      parameters:
        - description: Process ID
          in: path
          name: pid
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Object containing PID and success message
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        "400":
          description: Invalid process ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Stop monitoring ports for a process
      tags:
        - network
    post:
      description: Start monitoring for new ports opened by a process
      parameters:
        - description: Process ID
          in: path
          name: pid
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PortMonitorRequest"
        description: Port monitor configuration
        required: true
      responses:
        "200":
          description: Object containing PID and success message
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Start monitoring ports for a process
      tags:
        - network
  "/network/process/{pid}/ports":
    get:
      description: Get a list of all open ports for a process
      parameters:
        - description: Process ID
          in: path
          name: pid
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Object containing PID and array of network.PortInfo
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        "400":
          description: Invalid process ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Get open ports for a process
      tags:
        - network
  /network/tunnel:
    delete:
      description: "Stop the network tunnel and restore the original network configuration. WARNING: After disconnecting, the sandbox will lose all outbound internet connectivity (no egress). Inbound connections to the sandbox will still work. Use PUT /network/tunnel/config to re-establish the tunnel."
      responses:
        "200":
          description: Tunnel disconnected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: No tunnel is running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to stop tunnel
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Disconnect tunnel
      tags:
        - network
  /network/tunnel/config:
    put:
      description: Apply a new tunnel configuration on the fly. The existing tunnel is torn down and a new one is established. This endpoint is write-only; there is no corresponding GET to read the config back.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TunnelConfigRequest"
        description: Base64-encoded tunnel configuration
        required: true
      responses:
        "200":
          description: Configuration applied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Invalid tunnel configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to apply configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Update tunnel configuration
      tags:
        - network
  /process:
    get:
      description: Get a list of all running and completed processes
      responses:
        "200":
          description: Process list
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/ProcessResponse"
                type: array
      summary: List all processes
      tags:
        - process
    post:
      description: Execute a command and return process information. If Accept header is text/event-stream, streams logs in SSE format and returns the process response as a final event.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessRequest"
        description: Process execution request
        required: true
      responses:
        "200":
          description: Process information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ProcessResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Execute a command
      tags:
        - process
  "/process/{identifier}":
    delete:
      description: Gracefully stop a running process
      parameters:
        - description: Process identifier (PID or name)
          in: path
          name: identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Process stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Stop a process
      tags:
        - process
    get:
      description: Get information about a process by its PID or name
      parameters:
        - description: Process identifier (PID or name)
          in: path
          name: identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Process information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Get process by identifier
      tags:
        - process
  "/process/{identifier}/kill":
    delete:
      description: Forcefully kill a running process
      parameters:
        - description: Process identifier (PID or name)
          in: path
          name: identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Process killed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Kill a process
      tags:
        - process
  "/process/{identifier}/logs":
    get:
      description: Get the stdout and stderr output of a process
      parameters:
        - description: Process identifier (PID or name)
          in: path
          name: identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Process logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessLogs"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Get process logs
      tags:
        - process
  "/process/{identifier}/logs/stream":
    get:
      description: Streams the stdout and stderr output of a process in real time, one line per log, prefixed with 'stdout:' or 'stderr:'. Closes when the process exits or the client disconnects.
      parameters:
        - description: Process identifier (PID or name)
          in: path
          name: identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Stream of process logs, one line per log (prefixed with stdout:/stderr:)
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: Process not found
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Unprocessable entity
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Stream process logs in real time
      tags:
        - process
  /upgrade:
    post:
      description: >-
        Triggers an upgrade of the sandbox-api process. Returns 200 immediately before upgrading.

        The upgrade will: download the specified binary from GitHub releases, validate it, and restart.

        All running processes will be preserved across the upgrade.

        Available versions: "develop" (default), "main", "latest", or specific tag like "v1.0.0"

        You can also specify a custom baseUrl for forks (defaults to https://github.com/blaxel-ai/sandbox/releases)
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpgradeRequest"
        description: Upgrade options
      responses:
        "200":
          description: Upgrade initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Upgrade the sandbox-api
      tags:
        - system
  "/watch/filesystem/{path}":
    get:
      description: Streams the path of modified files (one per line) in the given directory. Closes when the client disconnects.
      parameters:
        - description: Ignore patterns (comma-separated)
          in: query
          name: ignore
          schema:
            type: string
        - description: Directory path to watch
          in: path
          name: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Stream of modified file paths, one per line
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid path
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      summary: Stream file modification events in a directory
      tags:
        - filesystem
servers:
  - url: https://sbx-{sandbox_id}-{workspace_id}.{region}.bl.run
    variables:
      sandbox_id:
        default: unknown
      workspace_id:
        default: unknown
      region:
        default: unknown
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ApplyEditRequest:
      properties:
        codeEdit:
          example: |-
            // Add world parameter
            function hello(world) {
              console.log('Hello', world);
            }
          type: string
        model:
          example: auto
          type: string
      required:
        - codeEdit
      type: object
    ApplyEditResponse:
      properties:
        message:
          example: Code edit applied successfully
          type: string
        originalContent:
          example: |-
            function hello() {
              console.log('Hello');
            }
          type: string
        path:
          example: src/main.js
          type: string
        provider:
          example: Relace
          type: string
        success:
          example: true
          type: boolean
        updatedContent:
          example: |-
            function hello(world) {
              console.log('Hello', world);
            }
          type: string
      type: object
    ContentSearchMatch:
      properties:
        column:
          example: 10
          type: integer
        context:
          example: |-
            previous line
            current line
            next line
          type: string
        line:
          example: 42
          type: integer
        path:
          example: src/main.go
          type: string
        text:
          example: const searchText = 'example'
          type: string
      required:
        - column
        - line
        - path
        - text
      type: object
    ContentSearchResponse:
      properties:
        matches:
          items:
            $ref: "#/components/schemas/ContentSearchMatch"
          type: array
        query:
          example: searchText
          type: string
        total:
          example: 5
          type: integer
      required:
        - matches
        - query
        - total
      type: object
    Directory:
      properties:
        files:
          items:
            $ref: "#/components/schemas/File"
          type: array
        name:
          type: string
        path:
          type: string
        subdirectories:
          description: "@name Subdirectories"
          items:
            $ref: "#/components/schemas/Subdirectory"
          type: array
      required:
        - files
        - name
        - path
        - subdirectories
      type: object
    DriveListResponse:
      properties:
        mounts:
          items:
            $ref: "#/components/schemas/DriveMountInfo"
          type: array
      type: object
    DriveMountInfo:
      properties:
        driveName:
          type: string
        drivePath:
          type: string
        mountPath:
          type: string
        readOnly:
          type: boolean
      type: object
    DriveMountRequest:
      properties:
        driveName:
          type: string
        drivePath:
          description: Optional, defaults to "/"
          type: string
        mountPath:
          type: string
        readOnly:
          description: Optional, defaults to false
          type: boolean
      required:
        - driveName
        - mountPath
      type: object
    DriveMountResponse:
      properties:
        driveName:
          type: string
        drivePath:
          type: string
        message:
          type: string
        mountPath:
          type: string
        readOnly:
          type: boolean
        success:
          type: boolean
      type: object
    DriveUnmountResponse:
      properties:
        message:
          type: string
        mountPath:
          type: string
        success:
          type: boolean
      type: object
    ErrorResponse:
      properties:
        error:
          example: Error message
          type: string
      required:
        - error
      type: object
    File:
      properties:
        group:
          type: string
        lastModified:
          type: string
        name:
          type: string
        owner:
          type: string
        path:
          type: string
        permissions:
          type: string
        size:
          type: integer
      required:
        - group
        - lastModified
        - name
        - owner
        - path
        - permissions
        - size
      type: object
    FileRequest:
      properties:
        content:
          example: file contents here
          type: string
        isDirectory:
          example: false
          type: boolean
        permissions:
          example: "0644"
          type: string
      type: object
    FileWithContent:
      properties:
        content:
          type: string
        group:
          type: string
        lastModified:
          type: string
        name:
          type: string
        owner:
          type: string
        path:
          type: string
        permissions:
          type: string
        size:
          type: integer
      required:
        - content
        - group
        - lastModified
        - name
        - owner
        - path
        - permissions
        - size
      type: object
    FindMatch:
      properties:
        path:
          example: src/main.go
          type: string
        type:
          description: '"file" or "directory"'
          example: file
          type: string
      required:
        - path
        - type
      type: object
    FindResponse:
      properties:
        matches:
          items:
            $ref: "#/components/schemas/FindMatch"
          type: array
        total:
          example: 5
          type: integer
      required:
        - matches
        - total
      type: object
    FuzzySearchMatch:
      properties:
        path:
          example: src/main.go
          type: string
        score:
          example: 100
          type: integer
        type:
          description: '"file" or "directory"'
          example: file
          type: string
      required:
        - path
        - score
        - type
      type: object
    FuzzySearchResponse:
      properties:
        matches:
          items:
            $ref: "#/components/schemas/FuzzySearchMatch"
          type: array
        total:
          example: 5
          type: integer
      required:
        - matches
        - total
      type: object
    HealthResponse:
      properties:
        arch:
          example: amd64
          type: string
        buildTime:
          example: 2026-01-29T17:36:52Z
          type: string
        gitCommit:
          example: abc123
          type: string
        goVersion:
          example: go1.25.0
          type: string
        lastUpgrade:
          $ref: "#/components/schemas/UpgradeStatus"
        os:
          example: linux
          type: string
        startedAt:
          example: 2026-01-29T18:45:49Z
          type: string
        status:
          example: ok
          type: string
        upgradeCount:
          example: 0
          type: integer
        uptime:
          example: 1h30m
          type: string
        uptimeSeconds:
          example: 5400.5
          type: number
        version:
          example: v0.1.0
          type: string
      required:
        - arch
        - buildTime
        - gitCommit
        - goVersion
        - lastUpgrade
        - os
        - startedAt
        - status
        - upgradeCount
        - uptime
        - uptimeSeconds
        - version
      type: object
    MultipartCompleteRequest:
      properties:
        parts:
          items:
            $ref: "#/components/schemas/MultipartPartInfo"
          type: array
      type: object
    MultipartInitiateRequest:
      properties:
        permissions:
          example: "0644"
          type: string
      type: object
    MultipartInitiateResponse:
      properties:
        path:
          example: /tmp/largefile.dat
          type: string
        uploadId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      type: object
    MultipartListPartsResponse:
      properties:
        parts:
          items:
            $ref: "#/components/schemas/filesystem.UploadedPart"
          type: array
        uploadId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      type: object
    MultipartListUploadsResponse:
      properties:
        uploads:
          items:
            $ref: "#/components/schemas/filesystem.MultipartUpload"
          type: array
      type: object
    MultipartPartInfo:
      properties:
        etag:
          example: 5d41402abc4b2a76b9719d911017c592
          type: string
        partNumber:
          example: 1
          type: integer
      type: object
    MultipartUploadPartResponse:
      properties:
        etag:
          example: 5d41402abc4b2a76b9719d911017c592
          type: string
        partNumber:
          example: 1
          type: integer
        size:
          example: 5242880
          type: integer
      type: object
    PortMonitorRequest:
      properties:
        callback:
          description: URL to call when a new port is detected
          example: http://localhost:3000/callback
          type: string
      type: object
    ProcessLogs:
      properties:
        logs:
          example: logs output
          type: string
        stderr:
          example: stderr output
          type: string
        stdout:
          example: stdout output
          type: string
      required:
        - logs
        - stderr
        - stdout
      type: object
    ProcessRequest:
      properties:
        command:
          example: ls -la
          type: string
        env:
          additionalProperties:
            type: string
          example:
            "{\"PORT\"": ' "3000"}'
          type: object
        keepAlive:
          description: Disable scale-to-zero while process runs. Default timeout is 600s (10 minutes). Set timeout to 0 for infinite.
          example: false
          type: boolean
        maxRestarts:
          example: 3
          type: integer
        name:
          example: my-process
          type: string
        restartOnFailure:
          example: true
          type: boolean
        timeout:
          description: Timeout in seconds. When keepAlive is true, defaults to 600s (10 minutes). Set to 0 for infinite (no auto-kill).
          example: 30
          type: integer
        waitForCompletion:
          example: false
          type: boolean
        waitForPorts:
          example:
            - 3000
            - 8080
          items:
            type: integer
          type: array
        workingDir:
          example: /home/user
          type: string
      required:
        - command
      type: object
    ProcessResponse:
      properties:
        command:
          example: ls -la
          type: string
        completedAt:
          example: Wed, 01 Jan 2023 12:01:00 GMT
          type: string
        exitCode:
          example: 0
          type: integer
        keepAlive:
          description: Whether scale-to-zero is disabled for this process
          example: false
          type: boolean
        logs:
          example: logs output
          type: string
        maxRestarts:
          example: 3
          type: integer
        name:
          example: my-process
          type: string
        pid:
          example: "1234"
          type: string
        restartCount:
          example: 2
          type: integer
        restartOnFailure:
          example: true
          type: boolean
        startedAt:
          example: Wed, 01 Jan 2023 12:00:00 GMT
          type: string
        status:
          enum:
            - failed
            - killed
            - stopped
            - running
            - completed
          example: running
          type: string
        stderr:
          example: stderr output
          type: string
        stdout:
          example: stdout output
          type: string
        workingDir:
          example: /home/user
          type: string
      required:
        - command
        - completedAt
        - exitCode
        - logs
        - name
        - pid
        - startedAt
        - status
        - stderr
        - stdout
        - workingDir
      type: object
    RankedFile:
      properties:
        content:
          type: string
        path:
          type: string
        score:
          type: number
      type: object
    RerankingResponse:
      properties:
        files:
          items:
            $ref: "#/components/schemas/RankedFile"
          type: array
        message:
          example: Found 5 relevant files
          type: string
        success:
          example: true
          type: boolean
      type: object
    Subdirectory:
      properties:
        name:
          type: string
        path:
          type: string
      required:
        - name
        - path
      type: object
    SuccessResponse:
      properties:
        message:
          example: File created successfully
          type: string
        path:
          example: /path/to/file
          type: string
      required:
        - message
      type: object
    TreeRequest:
      properties:
        files:
          additionalProperties:
            type: string
          example:
            '"dir/file2.txt"': '"content2"}'
            "{\"file1.txt\"": '"content1"'
          type: object
      type: object
    TunnelConfigRequest:
      properties:
        config:
          description: Base64-encoded tunnel config JSON
          example: eyJsb2NhbF9pcCI6ICIxMC4wLjAuMS8zMiIsIC4uLn0=
          type: string
      required:
        - config
      type: object
    UpgradeRequest:
      properties:
        baseUrl:
          description: Base URL for releases (useful for forks)
          example: https://github.com/blaxel-ai/sandbox/releases
          type: string
        version:
          description: 'Version to upgrade to: "develop", "main", "latest", or specific tag like "v1.0.0"'
          example: develop
          type: string
      type: object
    UpgradeStatus:
      properties:
        binaryPath:
          description: Path to downloaded binary
          example: /tmp/sandbox-api-new
          type: string
        bytesDownloaded:
          description: Bytes downloaded
          example: 25034936
          type: integer
        downloadUrl:
          description: URL used for download
          example: https://github.com/...
          type: string
        error:
          description: Error message if failed
          example: Failed to download binary
          type: string
        lastAttempt:
          description: When the upgrade was attempted
          type: string
        status:
          allOf:
            - $ref: "#/components/schemas/process.UpgradeState"
          description: Current state (idle, running, completed, failed)
          example: running
        step:
          description: Current/last step (none, starting, download, validate, replace, completed, skipped)
          example: download
          type: string
        version:
          description: Version being upgraded to
          example: latest
          type: string
      required:
        - status
        - step
        - version
      type: object
    filesystem.MultipartUpload:
      properties:
        initiatedAt:
          type: string
        parts:
          additionalProperties:
            $ref: "#/components/schemas/filesystem.UploadedPart"
          type: object
        path:
          example: /tmp/largefile.dat
          type: string
        permissions:
          example: 420
          type: integer
        uploadId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      type: object
    filesystem.UploadedPart:
      properties:
        etag:
          example: 5d41402abc4b2a76b9719d911017c592
          type: string
        partNumber:
          example: 1
          type: integer
        size:
          example: 5242880
          type: integer
        uploadedAt:
          type: string
      type: object
    process.UpgradeState:
      enum:
        - idle
        - running
        - completed
        - failed
      type: string
      x-enum-comments:
        UpgradeStateCompleted: Upgrade completed successfully
        UpgradeStateFailed: Upgrade failed
        UpgradeStateIdle: No upgrade in progress
        UpgradeStateRunning: Upgrade is currently running
      x-enum-descriptions:
        - No upgrade in progress
        - Upgrade is currently running
        - Upgrade completed successfully
        - Upgrade failed
      x-enum-varnames:
        - UpgradeStateIdle
        - UpgradeStateRunning
        - UpgradeStateCompleted
        - UpgradeStateFailed
security:
  - BearerAuth: []