1  openapi: 3.1.0
   2  info:
   3    title: OpenSandbox Execd API
   4    version: 1.0.0
   5    description: |
   6      OpenSandbox Execd provides a comprehensive API for managing code execution, file operations,
   7      and system monitoring within a sandboxed environment. The API supports multiple programming
   8      languages, real-time streaming output via Server-Sent Events (SSE), and complete file system
   9      management capabilities.
  10  
  11      ## Key Features
  12      - **Code Execution**: Execute code in Python, JavaScript, and other languages with stateful contexts
  13      - **Command Execution**: Run shell commands with foreground/background modes
  14      - **File Operations**: Complete CRUD operations for files and directories
  15      - **Real-time Streaming**: SSE-based output streaming for code and command execution
  16      - **System Monitoring**: CPU and memory metrics with real-time watching
  17      - **Access Control**: Token-based authentication for all API endpoints
  18  
  19    contact:
  20      name: OpenSandbox Team
  21      url: https://github.com/alibaba/OpenSandbox
  22    license:
  23      name: Apache 2.0
  24      url: https://www.apache.org/licenses/LICENSE-2.0.html
  25  
  26  servers:
  27    - url: http://localhost:44772
  28      description: Local development server
  29    - url: https://api.opensandbox.example.com
  30      description: Production server
  31  
  32  security:
  33    - AccessToken: []
  34  
  35  tags:
  36    - name: Health
  37      description: Server health check and status monitoring
  38    - name: CodeInterpreting
  39      description: Code execution and context management
  40    - name: Command
  41      description: Shell command execution and interruption
  42    - name: Filesystem
  43      description: File and directory operations
  44    - name: Metric
  45      description: System resource monitoring and metrics
  46  
  47  paths:
  48    /ping:
  49      get:
  50        summary: Health check endpoint
  51        description: |
  52          Performs a simple health check to verify that the server is running and responsive.
  53          Returns HTTP 200 OK status if the server is healthy. This endpoint is typically used
  54          by load balancers, monitoring systems, and orchestration platforms (like Kubernetes)
  55          to check service availability.
  56        operationId: ping
  57        tags:
  58          - Health
  59        responses:
  60          "200":
  61            description: Server is alive and healthy
  62  
  63    /code/contexts:
  64      get:
  65        summary: List active code execution contexts
  66        description: |
  67          Lists all active/available code execution contexts.
  68          If `language` is provided, only contexts under that language/runtime are returned.
  69        operationId: listContexts
  70        tags:
  71          - CodeInterpreting
  72        parameters:
  73          - name: language
  74            in: query
  75            required: true
  76            description: Filter contexts by execution runtime (python, bash, java, etc.)
  77            schema:
  78              type: string
  79            example: python
  80        responses:
  81          "200":
  82            description: Array of active contexts
  83            content:
  84              application/json:
  85                schema:
  86                  type: array
  87                  items:
  88                    $ref: "#/components/schemas/CodeContext"
  89                examples:
  90                  python_only:
  91                    summary: Context list filtered by language
  92                    value:
  93                      - id: session-abc123
  94                        language: python
  95                      - id: session-def456
  96                        language: python
  97          "400":
  98            $ref: "#/components/responses/BadRequest"
  99          "500":
 100            $ref: "#/components/responses/InternalServerError"
 101  
 102      delete:
 103        summary: Delete all contexts under a language
 104        description: |
 105          Deletes all existing code execution contexts under the specified `language`/runtime.
 106          This is a bulk operation intended for code-interpreter context cleanup.
 107        operationId: deleteContextsByLanguage
 108        tags:
 109          - CodeInterpreting
 110        parameters:
 111          - name: language
 112            in: query
 113            required: true
 114            description: Target execution runtime whose contexts should be deleted
 115            schema:
 116              type: string
 117            example: python
 118        responses:
 119          "200":
 120            description: Contexts deleted successfully
 121          "400":
 122            $ref: "#/components/responses/BadRequest"
 123          "500":
 124            $ref: "#/components/responses/InternalServerError"
 125  
 126    /code/contexts/{context_id}:
 127      get:
 128        summary: Get a code execution context by id
 129        description: |
 130          Retrieves the details of an existing code execution context (session) by id.
 131          Returns the context ID, language, and any associated metadata.
 132        operationId: getContext
 133        tags:
 134          - CodeInterpreting
 135        parameters:
 136          - name: context_id
 137            in: path
 138            required: true
 139            description: Session/context id to get
 140            schema:
 141              type: string
 142            example: session-abc123
 143        responses:
 144          "200":
 145            description: Context details retrieved successfully
 146            content:
 147              application/json:
 148                schema:
 149                  $ref: "#/components/schemas/CodeContext"
 150          "404":
 151            $ref: "#/components/responses/NotFound"
 152          "500":
 153            $ref: "#/components/responses/InternalServerError"
 154      delete:
 155        summary: Delete a code execution context by id
 156        description: |
 157          Deletes an existing code execution context (session) by id.
 158          This should terminate the underlying context thread/process and release resources.
 159        operationId: deleteContext
 160        tags:
 161          - CodeInterpreting
 162        parameters:
 163          - name: context_id
 164            in: path
 165            required: true
 166            description: Session/context id to delete
 167            schema:
 168              type: string
 169            example: session-abc123
 170        responses:
 171          "200":
 172            description: Context deleted successfully
 173          "400":
 174            $ref: "#/components/responses/BadRequest"
 175          "404":
 176            $ref: "#/components/responses/NotFound"
 177          "500":
 178            $ref: "#/components/responses/InternalServerError"
 179  
 180    /code/context:
 181      post:
 182        summary: Create code execution context
 183        description: |
 184          Creates a new code execution environment and returns a session ID that can be used
 185          for subsequent code execution requests. The context maintains state across multiple
 186          code executions within the same session.
 187        operationId: createCodeContext
 188        tags:
 189          - CodeInterpreting
 190        requestBody:
 191          required: true
 192          content:
 193            application/json:
 194              schema:
 195                $ref: "#/components/schemas/CodeContextRequest"
 196              examples:
 197                python:
 198                  summary: Create Python context
 199                  value:
 200                    language: python
 201                bash:
 202                  summary: Create Bash context
 203                  value:
 204                    language: bash
 205        responses:
 206          "200":
 207            description: Successfully created context with session ID
 208            content:
 209              application/json:
 210                schema:
 211                  $ref: "#/components/schemas/CodeContext"
 212          "400":
 213            $ref: "#/components/responses/BadRequest"
 214          "500":
 215            $ref: "#/components/responses/InternalServerError"
 216  
 217    /code:
 218      post:
 219        summary: Execute code in context
 220        description: |
 221          Executes code using Jupyter kernel in a specified execution context and streams
 222          the output in real-time using SSE (Server-Sent Events). Supports multiple programming
 223          languages (Python, JavaScript, etc.) and maintains execution state within the session.
 224          Returns execution results, output streams, execution count, and any errors.
 225        operationId: runCode
 226        tags:
 227          - CodeInterpreting
 228        requestBody:
 229          required: true
 230          content:
 231            application/json:
 232              schema:
 233                $ref: "#/components/schemas/RunCodeRequest"
 234              examples:
 235                python:
 236                  summary: Execute Python code
 237                  value:
 238                    context:
 239                      id: session-123
 240                      language: python
 241                    code: |
 242                      print("Hello, World!")
 243                      result = 2 + 2
 244                      result
 245                stateless:
 246                  summary: Stateless execution
 247                  value:
 248                    code: echo "Hello from shell"
 249        responses:
 250          "200":
 251            description: Stream of code execution events
 252            content:
 253              text/event-stream:
 254                schema:
 255                  $ref: "#/components/schemas/ServerStreamEvent"
 256          "400":
 257            $ref: "#/components/responses/BadRequest"
 258          "500":
 259            $ref: "#/components/responses/InternalServerError"
 260  
 261      delete:
 262        summary: Interrupt code execution
 263        description: |
 264          Interrupts the currently running code execution in the specified context.
 265          This sends a signal to terminate the execution process and releases associated resources.
 266        operationId: interruptCode
 267        tags:
 268          - CodeInterpreting
 269        parameters:
 270          - name: id
 271            in: query
 272            required: true
 273            description: Session ID of the execution context to interrupt
 274            schema:
 275              type: string
 276            example: session-123
 277        responses:
 278          "200":
 279            description: Code execution successfully interrupted
 280          "400":
 281            $ref: "#/components/responses/BadRequest"
 282          "500":
 283            $ref: "#/components/responses/InternalServerError"
 284  
 285    /session:
 286      post:
 287        summary: Create bash session (create_session)
 288        description: |
 289          Creates a new bash session and returns a session ID for subsequent run_in_session requests.
 290          The session maintains shell state (e.g. working directory, environment) across multiple
 291          code executions. Request body is optional; an empty body uses default options (no cwd override).
 292        operationId: createSession
 293        tags:
 294          - Command
 295        requestBody:
 296          required: false
 297          content:
 298            application/json:
 299              schema:
 300                $ref: "#/components/schemas/CreateSessionRequest"
 301              examples:
 302                default:
 303                  summary: Default (empty body allowed)
 304                  value: {}
 305                with_cwd:
 306                  summary: With working directory
 307                  value:
 308                    cwd: /workspace
 309        responses:
 310          "200":
 311            description: Session created successfully
 312            content:
 313              application/json:
 314                schema:
 315                  $ref: "#/components/schemas/CreateSessionResponse"
 316          "400":
 317            $ref: "#/components/responses/BadRequest"
 318          "500":
 319            $ref: "#/components/responses/InternalServerError"
 320  
 321    /session/{sessionId}/run:
 322      post:
 323        summary: Run command in bash session (run_in_session)
 324        description: |
 325          Executes a shell command in an existing bash session and streams the output in real-time via SSE
 326          (Server-Sent Events). The session must have been created by create_session. Supports
 327          optional working directory override and timeout (milliseconds).
 328        operationId: runInSession
 329        tags:
 330          - Command
 331        parameters:
 332          - name: sessionId
 333            in: path
 334            required: true
 335            description: Session ID returned by create_session
 336            schema:
 337              type: string
 338            example: session-abc123
 339        requestBody:
 340          required: true
 341          content:
 342            application/json:
 343              schema:
 344                $ref: "#/components/schemas/RunInSessionRequest"
 345              examples:
 346                simple:
 347                  summary: Run shell command
 348                  value:
 349                    command: echo "Hello from session"
 350                with_options:
 351                  summary: With cwd and timeout
 352                  value:
 353                    command: ls -la
 354                    cwd: /workspace
 355                    timeout: 30000
 356        responses:
 357          "200":
 358            description: Stream of execution events
 359            content:
 360              text/event-stream:
 361                schema:
 362                  $ref: "#/components/schemas/ServerStreamEvent"
 363          "400":
 364            $ref: "#/components/responses/BadRequest"
 365          "500":
 366            $ref: "#/components/responses/InternalServerError"
 367  
 368    /session/{sessionId}:
 369      delete:
 370        summary: Delete bash session (delete_session)
 371        description: |
 372          Deletes an existing bash session by ID. Terminates the underlying shell process
 373          and releases resources. The session ID must have been returned by create_session.
 374        operationId: deleteSession
 375        tags:
 376          - Command
 377        parameters:
 378          - name: sessionId
 379            in: path
 380            required: true
 381            description: Session ID to delete
 382            schema:
 383              type: string
 384            example: session-abc123
 385        responses:
 386          "200":
 387            description: Session deleted successfully
 388          "400":
 389            $ref: "#/components/responses/BadRequest"
 390          "404":
 391            $ref: "#/components/responses/NotFound"
 392          "500":
 393            $ref: "#/components/responses/InternalServerError"
 394  
 395    /command:
 396      post:
 397        summary: Execute shell command
 398        description: |
 399          Executes a shell command and streams the output in real-time using SSE (Server-Sent Events).
 400          The command can run in foreground or background mode. The response includes stdout, stderr,
 401          execution status, and completion events.
 402          Optionally specify `timeout` (milliseconds) to enforce a maximum runtime; the server will
 403          terminate the process when the timeout is reached. You can also pass `uid`/`gid` to run
 404          with specific user/group IDs, and `envs` to inject environment variables.
 405        operationId: runCommand
 406        tags:
 407          - Command
 408        requestBody:
 409          required: true
 410          content:
 411            application/json:
 412              schema:
 413                $ref: "#/components/schemas/RunCommandRequest"
 414              examples:
 415                foreground:
 416                  summary: Foreground command
 417                  value:
 418                    command: ls -la /workspace
 419                    cwd: /workspace
 420                    background: false
 421                    timeout: 30000
 422                    uid: 1000
 423                    gid: 1000
 424                    envs:
 425                      PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 426                      PYTHONUNBUFFERED: "1"
 427                background:
 428                  summary: Background command
 429                  value:
 430                    command: python server.py
 431                    cwd: /app
 432                    background: true
 433                    timeout: 120000
 434                    uid: 1000
 435                    envs:
 436                      APP_ENV: production
 437                      LOG_LEVEL: info
 438        responses:
 439          "200":
 440            description: Stream of command execution events
 441            content:
 442              text/event-stream:
 443                schema:
 444                  $ref: "#/components/schemas/ServerStreamEvent"
 445          "400":
 446            $ref: "#/components/responses/BadRequest"
 447          "500":
 448            $ref: "#/components/responses/InternalServerError"
 449  
 450      delete:
 451        summary: Interrupt command execution
 452        description: |
 453          Interrupts the currently running command execution in the specified context.
 454          This sends a signal to terminate the execution process and releases associated resources.
 455        operationId: interruptCommand
 456        tags:
 457          - Command
 458        parameters:
 459          - name: id
 460            in: query
 461            required: true
 462            description: Session ID of the execution context to interrupt
 463            schema:
 464              type: string
 465            example: session-456
 466        responses:
 467          "200":
 468            description: Command execution successfully interrupted
 469          "400":
 470            $ref: "#/components/responses/BadRequest"
 471          "500":
 472            $ref: "#/components/responses/InternalServerError"
 473  
 474    /command/status/{id}:
 475      get:
 476        summary: Get command running status
 477        description: |
 478          Returns the current status of a command (foreground or background) by command ID.
 479          Includes running flag, exit code, error (if any), and start/finish timestamps.
 480        operationId: getCommandStatus
 481        tags:
 482          - Command
 483        parameters:
 484          - name: id
 485            in: path
 486            required: true
 487            description: Command ID returned by RunCommand
 488            schema:
 489              type: string
 490            example: cmd-abc123
 491        responses:
 492          "200":
 493            description: Command status
 494            content:
 495              application/json:
 496                schema:
 497                  $ref: "#/components/schemas/CommandStatusResponse"
 498          "400":
 499            $ref: "#/components/responses/BadRequest"
 500          "404":
 501            $ref: "#/components/responses/NotFound"
 502          "500":
 503            $ref: "#/components/responses/InternalServerError"
 504  
 505    /command/{id}/logs:
 506      get:
 507        summary: Get background command stdout/stderr (non-streamed)
 508        description: |
 509          Returns stdout and stderr for a background (detached) command by command ID.
 510          Foreground commands should be consumed via SSE; this endpoint is intended for
 511          polling logs of background commands. Supports incremental reads similar to a file seek:
 512          pass a starting line via query to fetch output after that line and receive the latest
 513          tail cursor for the next poll. When no starting line is provided, the full logs are returned.
 514          Response body is plain text so it can be rendered directly in browsers; the latest line index
 515          is provided via response header `EXECD-COMMANDS-TAIL-CURSOR` for subsequent incremental requests.
 516        operationId: getBackgroundCommandLogs
 517        tags:
 518          - Command
 519        parameters:
 520          - name: id
 521            in: path
 522            required: true
 523            description: Command ID returned by RunCommand
 524            schema:
 525              type: string
 526            example: cmd-abc123
 527          - name: cursor
 528            in: query
 529            required: false
 530            description: |
 531              Optional 0-based line cursor (behaves like a file seek). When provided, only
 532              stdout/stderr lines after this line are returned. The response includes the
 533              latest line index (`cursor`) so the client can request incremental output
 534              on subsequent calls. If omitted, the full log is returned.
 535            schema:
 536              type: integer
 537              format: int64
 538              minimum: 0
 539            example: 120
 540        responses:
 541          "200":
 542            description: Command output (plain text) and status metadata via headers
 543            content:
 544              text/plain:
 545                schema:
 546                  type: string
 547                example: |
 548                  line1
 549                  line2
 550                  warn: something on stderr
 551            headers:
 552              EXECD-COMMANDS-TAIL-CURSOR:
 553                description: Highest available 0-based line index after applying the request cursor (use as the next cursor for incremental reads)
 554                schema:
 555                  type: integer
 556                  format: int64
 557          "400":
 558            $ref: "#/components/responses/BadRequest"
 559          "404":
 560            $ref: "#/components/responses/NotFound"
 561          "500":
 562            $ref: "#/components/responses/InternalServerError"
 563  
 564    /files/info:
 565      get:
 566        summary: Get file metadata
 567        description: |
 568          Retrieves detailed metadata for one or multiple files including permissions, owner,
 569          group, size, and modification time. Returns a map of file paths to their corresponding
 570          FileInfo objects.
 571        operationId: getFilesInfo
 572        tags:
 573          - Filesystem
 574        parameters:
 575          - name: path
 576            in: query
 577            required: true
 578            description: File path(s) to get info for (can be specified multiple times)
 579            schema:
 580              type: array
 581              items:
 582                type: string
 583            style: form
 584            explode: true
 585            examples:
 586              single:
 587                summary: Single file
 588                value: ["/workspace/file.txt"]
 589              multiple:
 590                summary: Multiple files
 591                value: ["/workspace/file1.txt", "/workspace/file2.py"]
 592        responses:
 593          "200":
 594            description: Map of file paths to FileInfo objects
 595            content:
 596              application/json:
 597                schema:
 598                  type: object
 599                  additionalProperties:
 600                    $ref: "#/components/schemas/FileInfo"
 601          "404":
 602            $ref: "#/components/responses/NotFound"
 603          "500":
 604            $ref: "#/components/responses/InternalServerError"
 605  
 606    /files:
 607      delete:
 608        summary: Delete files
 609        description: |
 610          Deletes one or multiple files from the sandbox. Only removes files, not directories.
 611          Use RemoveDirs for directory removal.
 612        operationId: removeFiles
 613        tags:
 614          - Filesystem
 615        parameters:
 616          - name: path
 617            in: query
 618            required: true
 619            description: File path(s) to delete (can be specified multiple times)
 620            schema:
 621              type: array
 622              items:
 623                type: string
 624            style: form
 625            explode: true
 626            example: ["/workspace/temp.txt"]
 627        responses:
 628          "200":
 629            description: Files deleted successfully
 630          "500":
 631            $ref: "#/components/responses/InternalServerError"
 632  
 633    /files/permissions:
 634      post:
 635        summary: Change file permissions
 636        description: |
 637          Changes permissions (mode), owner, and group for one or multiple files.
 638          Accepts a map of file paths to permission settings including octal mode,
 639          owner username, and group name.
 640        operationId: chmodFiles
 641        tags:
 642          - Filesystem
 643        requestBody:
 644          required: true
 645          content:
 646            application/json:
 647              schema:
 648                type: object
 649                additionalProperties:
 650                  $ref: "#/components/schemas/Permission"
 651              example:
 652                "/workspace/script.sh":
 653                  owner: admin
 654                  group: admin
 655                  mode: 755
 656                "/workspace/config.json":
 657                  owner: admin
 658                  group: admin
 659                  mode: 755
 660        responses:
 661          "200":
 662            description: Permissions changed successfully
 663          "400":
 664            $ref: "#/components/responses/BadRequest"
 665          "500":
 666            $ref: "#/components/responses/InternalServerError"
 667  
 668    /files/mv:
 669      post:
 670        summary: Rename or move files
 671        description: |
 672          Renames or moves one or multiple files to new paths. Can be used for both
 673          renaming within the same directory and moving to different directories.
 674          Target directory must exist.
 675        operationId: renameFiles
 676        tags:
 677          - Filesystem
 678        requestBody:
 679          required: true
 680          content:
 681            application/json:
 682              schema:
 683                type: array
 684                items:
 685                  $ref: "#/components/schemas/RenameFileItem"
 686              example:
 687                - src: /workspace/old_name.txt
 688                  dest: /workspace/new_name.txt
 689                - src: /workspace/file.py
 690                  dest: /archive/file.py
 691        responses:
 692          "200":
 693            description: Files renamed/moved successfully
 694          "400":
 695            $ref: "#/components/responses/BadRequest"
 696          "404":
 697            $ref: "#/components/responses/NotFound"
 698          "500":
 699            $ref: "#/components/responses/InternalServerError"
 700  
 701    /files/search:
 702      get:
 703        summary: Search for files
 704        description: |
 705          Searches for files matching a glob pattern within a specified directory and
 706          its subdirectories. Returns file metadata including path, permissions, owner,
 707          and group. Supports glob patterns like **, *.txt, etc. Default pattern is ** (all files).
 708        operationId: searchFiles
 709        tags:
 710          - Filesystem
 711        parameters:
 712          - name: path
 713            in: query
 714            required: true
 715            description: Root directory path to search in
 716            schema:
 717              type: string
 718          - name: pattern
 719            in: query
 720            required: false
 721            description: Glob pattern to match files (default is **)
 722            schema:
 723              type: string
 724              default: "**"
 725        responses:
 726          "200":
 727            description: Array of matching files with metadata
 728            content:
 729              application/json:
 730                schema:
 731                  type: array
 732                  items:
 733                    $ref: "#/components/schemas/FileInfo"
 734          "400":
 735            $ref: "#/components/responses/BadRequest"
 736          "404":
 737            $ref: "#/components/responses/NotFound"
 738          "500":
 739            $ref: "#/components/responses/InternalServerError"
 740  
 741    /files/replace:
 742      post:
 743        summary: Replace file content
 744        description: |
 745          Performs text replacement in one or multiple files. Replaces all occurrences
 746          of the old string with the new string (similar to strings.ReplaceAll).
 747          Preserves file permissions. Useful for batch text substitution across files.
 748        operationId: replaceContent
 749        tags:
 750          - Filesystem
 751        requestBody:
 752          required: true
 753          content:
 754            application/json:
 755              schema:
 756                type: object
 757                additionalProperties:
 758                  $ref: "#/components/schemas/ReplaceFileContentItem"
 759              example:
 760                "/workspace/config.yaml":
 761                  old: "localhost:8080"
 762                  new: "0.0.0.0:9090"
 763                "/workspace/app.py":
 764                  old: "DEBUG = True"
 765                  new: "DEBUG = False"
 766        responses:
 767          "200":
 768            description: Content replaced successfully
 769          "400":
 770            $ref: "#/components/responses/BadRequest"
 771          "500":
 772            $ref: "#/components/responses/InternalServerError"
 773  
 774    /files/upload:
 775      post:
 776        summary: Upload files to sandbox
 777        description: |
 778          Uploads one or multiple files to specified paths within the sandbox.
 779          Reads metadata and file content from multipart form parts in sequence.
 780          Each file upload consists of two parts: a metadata part (JSON) followed
 781          by the actual file part.
 782        operationId: uploadFile
 783        tags:
 784          - Filesystem
 785        requestBody:
 786          required: true
 787          content:
 788            multipart/form-data:
 789              schema:
 790                type: object
 791                properties:
 792                  metadata:
 793                    type: string
 794                    description: JSON-encoded file metadata (FileMetadata object)
 795                    example: '{"path":"/workspace/file.txt","owner":"admin","group":"admin","mode":755}'
 796                  file:
 797                    type: string
 798                    format: binary
 799                    description: File to upload
 800              encoding:
 801                metadata:
 802                  contentType: application/json
 803                file:
 804                  contentType: application/octet-stream
 805        responses:
 806          "200":
 807            description: Files uploaded successfully
 808          "400":
 809            $ref: "#/components/responses/BadRequest"
 810          "500":
 811            $ref: "#/components/responses/InternalServerError"
 812  
 813    /files/download:
 814      get:
 815        summary: Download file from sandbox
 816        description: |
 817          Downloads a file from the specified path within the sandbox. Supports HTTP
 818          range requests for resumable downloads and partial content retrieval.
 819          Returns file as octet-stream with appropriate headers.
 820        operationId: downloadFile
 821        tags:
 822          - Filesystem
 823        parameters:
 824          - name: path
 825            in: query
 826            required: true
 827            description: Absolute or relative path of the file to download
 828            schema:
 829              type: string
 830            example: /workspace/data.csv
 831          - name: Range
 832            in: header
 833            required: false
 834            description: HTTP Range header for partial content requests
 835            schema:
 836              type: string
 837            example: "bytes=0-1023"
 838        responses:
 839          "200":
 840            description: File content
 841            content:
 842              application/octet-stream:
 843                schema:
 844                  type: string
 845                  format: binary
 846            headers:
 847              Content-Disposition:
 848                schema:
 849                  type: string
 850                description: Attachment header with filename
 851              Content-Length:
 852                schema:
 853                  type: integer
 854                description: File size in bytes
 855          "206":
 856            description: Partial file content (when Range header is provided)
 857            content:
 858              application/octet-stream:
 859                schema:
 860                  type: string
 861                  format: binary
 862            headers:
 863              Content-Range:
 864                schema:
 865                  type: string
 866                description: Range of bytes being returned
 867              Content-Length:
 868                schema:
 869                  type: integer
 870                description: Length of the returned range
 871          "400":
 872            $ref: "#/components/responses/BadRequest"
 873          "404":
 874            $ref: "#/components/responses/NotFound"
 875          "416":
 876            description: Requested range not satisfiable
 877            content:
 878              application/json:
 879                schema:
 880                  $ref: "#/components/schemas/ErrorResponse"
 881          "500":
 882            $ref: "#/components/responses/InternalServerError"
 883  
 884    /directories:
 885      post:
 886        summary: Create directories
 887        description: |
 888          Creates one or multiple directories with specified permissions. Creates parent
 889          directories as needed (similar to mkdir -p). Accepts a map of directory paths
 890          to permission objects.
 891        operationId: makeDirs
 892        tags:
 893          - Filesystem
 894        requestBody:
 895          required: true
 896          content:
 897            application/json:
 898              schema:
 899                type: object
 900                additionalProperties:
 901                  $ref: "#/components/schemas/Permission"
 902              example:
 903                "/workspace/project":
 904                  owner: admin
 905                  group: admin
 906                  mode: 755
 907                "/workspace/logs":
 908                  owner: admin
 909                  group: admin
 910                  mode: 755
 911        responses:
 912          "200":
 913            description: Directories created successfully
 914          "400":
 915            $ref: "#/components/responses/BadRequest"
 916          "500":
 917            $ref: "#/components/responses/InternalServerError"
 918  
 919      delete:
 920        summary: Delete directories
 921        description: |
 922          Recursively deletes one or multiple directories and all their contents.
 923          Similar to rm -rf. Use with caution as this operation cannot be undone.
 924        operationId: removeDirs
 925        tags:
 926          - Filesystem
 927        parameters:
 928          - name: path
 929            in: query
 930            required: true
 931            description: Directory path(s) to delete (can be specified multiple times)
 932            schema:
 933              type: array
 934              items:
 935                type: string
 936            style: form
 937            explode: true
 938            example: ["/workspace/temp"]
 939        responses:
 940          "200":
 941            description: Directories deleted successfully
 942          "500":
 943            $ref: "#/components/responses/InternalServerError"
 944  
 945    /metrics:
 946      get:
 947        summary: Get system metrics
 948        description: |
 949          Retrieves current system resource metrics including CPU usage percentage,
 950          CPU core count, total memory, used memory, and timestamp. Provides a snapshot
 951          of system resource utilization at the time of request.
 952        operationId: getMetrics
 953        tags:
 954          - Metric
 955        responses:
 956          "200":
 957            description: Current system metrics including CPU and memory usage
 958            content:
 959              application/json:
 960                schema:
 961                  $ref: "#/components/schemas/Metrics"
 962          "500":
 963            $ref: "#/components/responses/InternalServerError"
 964  
 965    /metrics/watch:
 966      get:
 967        summary: Watch system metrics in real-time
 968        description: |
 969          Streams system resource metrics in real-time using Server-Sent Events (SSE).
 970          Updates are sent every second, providing continuous monitoring of CPU usage,
 971          memory usage, and other system metrics. The connection remains open until
 972          the client disconnects.
 973        operationId: watchMetrics
 974        tags:
 975          - Metric
 976        responses:
 977          "200":
 978            description: Stream of system metrics updated every second
 979            content:
 980              text/event-stream:
 981                schema:
 982                  $ref: "#/components/schemas/Metrics"
 983          "500":
 984            $ref: "#/components/responses/InternalServerError"
 985  
 986  components:
 987    securitySchemes:
 988      AccessToken:
 989        type: apiKey
 990        in: header
 991        name: X-EXECD-ACCESS-TOKEN
 992        description: |
 993          Access token for API authentication. All requests must include this header
 994          with a valid token. The token is configured during server initialization.
 995  
 996    schemas:
 997      CreateSessionRequest:
 998        type: object
 999        description: Request to create a bash session (optional body; empty treated as defaults)
1000        properties:
1001          cwd:
1002            type: string
1003            description: Working directory for the session (optional)
1004            example: /workspace
1005  
1006      CreateSessionResponse:
1007        type: object
1008        description: Response for create_session
1009        properties:
1010          session_id:
1011            type: string
1012            description: Unique session ID for run_in_session and delete_session
1013            example: session-abc123
1014        required:
1015          - session_id
1016  
1017      RunInSessionRequest:
1018        type: object
1019        description: Request to run a command in an existing bash session
1020        required:
1021          - command
1022        properties:
1023          command:
1024            type: string
1025            description: Shell command to execute in the session
1026            example: echo "Hello"
1027          cwd:
1028            type: string
1029            description: Working directory override for this run (optional)
1030            example: /workspace
1031          timeout:
1032            type: integer
1033            format: int64
1034            minimum: 0
1035            description: Maximum execution time in milliseconds (optional; server may not enforce if omitted)
1036            example: 30000
1037  
1038      CodeContextRequest:
1039        type: object
1040        description: Request to create a code execution context
1041        properties:
1042          language:
1043            type: string
1044            description: Execution runtime (python, bash, java, etc.)
1045            example: python
1046  
1047      CodeContext:
1048        type: object
1049        description: Code execution context with session identifier
1050        properties:
1051          id:
1052            type: string
1053            description: Unique session identifier returned by CreateContext
1054            example: session-abc123
1055          language:
1056            type: string
1057            description: Execution runtime
1058            example: python
1059        required:
1060          - language
1061  
1062      RunCodeRequest:
1063        type: object
1064        required:
1065          - code
1066        description: Request to execute code in a context
1067        properties:
1068          context:
1069            $ref: "#/components/schemas/CodeContext"
1070          code:
1071            type: string
1072            description: Source code to execute
1073            example: |
1074              import numpy as np
1075              result = np.array([1, 2, 3])
1076              print(result)
1077  
1078      RunCommandRequest:
1079        type: object
1080        required:
1081          - command
1082        description: Request to execute a shell command
1083        properties:
1084          command:
1085            type: string
1086            description: Shell command to execute
1087            example: ls -la /workspace
1088          cwd:
1089            type: string
1090            description: Working directory for command execution
1091            example: /workspace
1092          background:
1093            type: boolean
1094            description: Whether to run command in detached mode
1095            default: false
1096            example: false
1097          timeout:
1098            type: integer
1099            format: int64
1100            description: Maximum allowed execution time in milliseconds before the command is forcefully terminated by the server. If omitted, the server will not enforce any timeout.
1101            example: 60000
1102          uid:
1103            type: integer
1104            format: int32
1105            minimum: 0
1106            description: |
1107              Unix user ID used to run the command. If `gid` is provided, `uid` is required.
1108            example: 1000
1109          gid:
1110            type: integer
1111            format: int32
1112            minimum: 0
1113            description: |
1114              Unix group ID used to run the command. Requires `uid` to be provided.
1115            example: 1000
1116          envs:
1117            type: object
1118            description: Environment variables injected into the command process.
1119            additionalProperties:
1120              type: string
1121            example:
1122              PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1123              PYTHONUNBUFFERED: "1"
1124  
1125      CommandStatusResponse:
1126        type: object
1127        description: Command execution status (foreground or background)
1128        properties:
1129          id:
1130            type: string
1131            description: Command ID returned by RunCommand
1132            example: cmd-abc123
1133          content:
1134            type: string
1135            description: Original command content
1136            example: ls -la
1137          running:
1138            type: boolean
1139            description: Whether the command is still running
1140            example: false
1141          exit_code:
1142            type: integer
1143            format: int32
1144            nullable: true
1145            description: Exit code if the command has finished
1146            example: 0
1147          error:
1148            type: string
1149            description: Error message if the command failed
1150            example: permission denied
1151          started_at:
1152            type: string
1153            format: date-time
1154            description: Start time in RFC3339 format
1155            example: "2025-12-22T09:08:05Z"
1156          finished_at:
1157            type: string
1158            format: date-time
1159            nullable: true
1160            description: Finish time in RFC3339 format (null if still running)
1161            example: "2025-12-22T09:08:09Z"
1162  
1163      ServerStreamEvent:
1164        type: object
1165        description: Server-sent event for streaming execution output
1166        properties:
1167          type:
1168            type: string
1169            enum:
1170              - init
1171              - status
1172              - error
1173              - stdout
1174              - stderr
1175              - result
1176              - execution_complete
1177              - execution_count
1178              - ping
1179            description: Event type for client-side handling
1180            example: stdout
1181          text:
1182            type: string
1183            description: Textual data for status, init, and stream events
1184            example: "Hello, World!\n"
1185          execution_count:
1186            type: integer
1187            description: Cell execution number in the session
1188            example: 1
1189          execution_time:
1190            type: integer
1191            format: int64
1192            description: Execution duration in milliseconds
1193            example: 150
1194          timestamp:
1195            type: integer
1196            format: int64
1197            description: When the event was generated (Unix milliseconds)
1198            example: 1700000000000
1199          results:
1200            type: object
1201            additionalProperties: true
1202            description: Execution output in various MIME types (e.g., "text/plain", "text/html")
1203            example:
1204              text/plain: "4"
1205          error:
1206            type: object
1207            description: Execution error details if an error occurred
1208            properties:
1209              ename:
1210                type: string
1211                description: Error name/type
1212                example: "NameError"
1213              evalue:
1214                type: string
1215                description: Error value/message
1216                example: "name 'undefined_var' is not defined"
1217              traceback:
1218                type: array
1219                items:
1220                  type: string
1221                description: Stack trace lines
1222                example:
1223                  - "Traceback (most recent call last):"
1224                  - '  File "<stdin>", line 1, in <module>'
1225                  - "NameError: name 'undefined_var' is not defined"
1226  
1227      FileInfo:
1228        type: object
1229        description: File metadata including path and permissions
1230        properties:
1231          path:
1232            type: string
1233            description: Absolute file path
1234            example: /workspace/file.txt
1235          size:
1236            type: integer
1237            format: int64
1238            description: File size in bytes
1239            example: 2048
1240          modified_at:
1241            type: string
1242            format: date-time
1243            description: Last modification time
1244            example: 2025-11-16T14:30:45Z
1245          created_at:
1246            type: string
1247            format: date-time
1248            description: File creation time
1249            example: 2025-11-16T14:30:45Z
1250          owner:
1251            type: string
1252            description: File owner username
1253            example: admin
1254          group:
1255            type: string
1256            description: File group name
1257            example: admin
1258          mode:
1259            type: integer
1260            description: File permissions in octal format
1261            example: 755
1262        required: [path, size, modified_at, created_at, owner, group, mode]
1263  
1264      Permission:
1265        type: object
1266        description: File ownership and mode settings
1267        properties:
1268          owner:
1269            type: string
1270            description: Owner username
1271            example: root
1272          group:
1273            type: string
1274            description: Group name
1275            example: root
1276          mode:
1277            type: integer
1278            description: Permission mode in octal format (e.g., 644, 755)
1279            default: 755
1280            example: 755
1281        required: [mode]
1282  
1283      FileMetadata:
1284        type: object
1285        description: File metadata for upload operations
1286        properties:
1287          path:
1288            type: string
1289            description: Target file path
1290            example: /workspace/upload.txt
1291          owner:
1292            type: string
1293            description: File owner
1294            example: admin
1295          group:
1296            type: string
1297            description: File group
1298            example: admin
1299          mode:
1300            type: integer
1301            description: File permissions in octal
1302            example: 755
1303  
1304      RenameFileItem:
1305        type: object
1306        description: File rename/move operation
1307        properties:
1308          src:
1309            type: string
1310            description: Source file path
1311            example: /workspace/old.txt
1312          dest:
1313            type: string
1314            description: Destination file path
1315            example: /workspace/new.txt
1316        required: [src, dest]
1317  
1318      ReplaceFileContentItem:
1319        type: object
1320        description: Content replacement operation
1321        properties:
1322          old:
1323            type: string
1324            description: String to be replaced
1325            example: "localhost"
1326          new:
1327            type: string
1328            description: Replacement string
1329            example: "0.0.0.0"
1330        required: [old, new]
1331  
1332      Metrics:
1333        type: object
1334        description: System resource usage metrics
1335        properties:
1336          cpu_count:
1337            type: number
1338            format: float
1339            description: Number of CPU cores
1340            example: 4.0
1341          cpu_used_pct:
1342            type: number
1343            format: float
1344            description: CPU usage percentage
1345            example: 45.5
1346          mem_total_mib:
1347            type: number
1348            format: float
1349            description: Total memory in MiB
1350            example: 8192.0
1351          mem_used_mib:
1352            type: number
1353            format: float
1354            description: Used memory in MiB
1355            example: 4096.0
1356          timestamp:
1357            type: integer
1358            format: int64
1359            description: Timestamp when metrics were collected (Unix milliseconds)
1360            example: 1700000000000
1361        required:
1362          [cpu_count, cpu_used_pct, mem_total_mib, mem_used_mib, timestamp]
1363  
1364      ErrorResponse:
1365        type: object
1366        description: Standard error response format
1367        properties:
1368          code:
1369            type: string
1370            description: Error code for programmatic handling
1371            example: INVALID_REQUEST_BODY
1372          message:
1373            type: string
1374            description: Human-readable error message
1375            example: "error parsing request, MAYBE invalid body format"
1376        required: [code, message]
1377  
1378    responses:
1379      BadRequest:
1380        description: Invalid request body format or missing required fields
1381        content:
1382          application/json:
1383            schema:
1384              $ref: "#/components/schemas/ErrorResponse"
1385            example:
1386              code: INVALID_REQUEST_BODY
1387              message: "error parsing request, MAYBE invalid body format"
1388  
1389      NotFound:
1390        description: File or resource not found
1391        content:
1392          application/json:
1393            schema:
1394              $ref: "#/components/schemas/ErrorResponse"
1395            example:
1396              code: FILE_NOT_FOUND
1397              message: "file not found"
1398  
1399      InternalServerError:
1400        description: Runtime server error during operation
1401        content:
1402          application/json:
1403            schema:
1404              $ref: "#/components/schemas/ErrorResponse"
1405            example:
1406              code: RUNTIME_ERROR
1407              message: "error running code execution"