Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

119 KB
Raw Blame
openapi: 3.1.0
info:
  title: OpenSandbox Execd API
  version: 1.0.0
  description: |
    OpenSandbox Execd provides a comprehensive API for managing code execution, file operations,
    and system monitoring within a sandboxed environment. The API supports multiple programming
    languages, real-time streaming output via Server-Sent Events (SSE), and complete file system
    management capabilities.

    ## Key Features
    - **Code Execution**: Execute code in Python, JavaScript, and other languages with stateful contexts
    - **Command Execution**: Run shell commands with foreground/background modes
    - **File Operations**: Complete CRUD operations for files and directories
    - **Real-time Streaming**: SSE-based output streaming for code and command execution
    - **System Monitoring**: CPU and memory metrics with real-time watching
    - **Access Control**: Token-based authentication for all API endpoints

  contact:
    name: OpenSandbox Team
    url: https://github.com/opensandbox-group/OpenSandbox
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: http://localhost:44772
    description: Local development server
  - url: https://api.opensandbox.example.com
    description: Production server

security:
  - AccessToken: []

tags:
  - name: Health
    description: Server health check and status monitoring
  - name: CodeInterpreting
    description: Code execution and context management
  - name: Command
    description: Shell command execution and interruption
  - name: Filesystem
    description: File and directory operations
  - name: FilesystemIdentity
    description: Linux filesystem operations under an explicit execution identity
  - name: Metric
    description: System resource monitoring and metrics
  - name: IsolatedExecution
    description: Per-session namespace isolation, code execution, and filesystem proxy

paths:
  /ping:
    get:
      summary: Health check endpoint
      description: |
        Performs a simple health check to verify that the server is running and responsive.
        Returns HTTP 200 OK status if the server is healthy. This endpoint is typically used
        by load balancers, monitoring systems, and orchestration platforms (like Kubernetes)
        to check service availability.
      operationId: ping
      tags:
        - Health
      responses:
        "200":
          description: Server is alive and healthy

  /code/contexts:
    get:
      summary: List active code execution contexts
      description: |
        Lists all active/available code execution contexts.
        If `language` is provided, only contexts under that language/runtime are returned.
      operationId: listContexts
      tags:
        - CodeInterpreting
      parameters:
        - name: language
          in: query
          required: true
          description: Filter contexts by execution runtime (python, bash, java, etc.)
          schema:
            type: string
          example: python
      responses:
        "200":
          description: Array of active contexts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CodeContext"
              examples:
                python_only:
                  summary: Context list filtered by language
                  value:
                    - id: session-abc123
                      language: python
                    - id: session-def456
                      language: python
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete all contexts under a language
      description: |
        Deletes all existing code execution contexts under the specified `language`/runtime.
        This is a bulk operation intended for code-interpreter context cleanup.
      operationId: deleteContextsByLanguage
      tags:
        - CodeInterpreting
      parameters:
        - name: language
          in: query
          required: true
          description: Target execution runtime whose contexts should be deleted
          schema:
            type: string
          example: python
      responses:
        "200":
          description: Contexts deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /code/contexts/{context_id}:
    get:
      summary: Get a code execution context by id
      description: |
        Retrieves the details of an existing code execution context (session) by id.
        Returns the context ID, language, and any associated metadata.
      operationId: getContext
      tags:
        - CodeInterpreting
      parameters:
        - name: context_id
          in: path
          required: true
          description: Session/context id to get
          schema:
            type: string
          example: session-abc123
      responses:
        "200":
          description: Context details retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CodeContext"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      summary: Delete a code execution context by id
      description: |
        Deletes an existing code execution context (session) by id.
        This should terminate the underlying context thread/process and release resources.
      operationId: deleteContext
      tags:
        - CodeInterpreting
      parameters:
        - name: context_id
          in: path
          required: true
          description: Session/context id to delete
          schema:
            type: string
          example: session-abc123
      responses:
        "200":
          description: Context deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /code/context:
    post:
      summary: Create code execution context
      description: |
        Creates a new code execution environment and returns a session ID that can be used
        for subsequent code execution requests. The context maintains state across multiple
        code executions within the same session.
      operationId: createCodeContext
      tags:
        - CodeInterpreting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CodeContextRequest"
            examples:
              python:
                summary: Create Python context
                value:
                  language: python
              bash:
                summary: Create Bash context
                value:
                  language: bash
      responses:
        "200":
          description: Successfully created context with session ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CodeContext"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /code:
    post:
      summary: Execute code in context
      description: |
        Executes code using Jupyter kernel in a specified execution context and streams
        the output in real-time using SSE (Server-Sent Events). Supports multiple programming
        languages (Python, JavaScript, etc.) and maintains execution state within the session.
        Returns execution results, output streams, execution count, and any errors.
      operationId: runCode
      tags:
        - CodeInterpreting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunCodeRequest"
            examples:
              python:
                summary: Execute Python code
                value:
                  context:
                    id: session-123
                    language: python
                  code: |
                    print("Hello, World!")
                    result = 2 + 2
                    result
              stateless:
                summary: Stateless execution
                value:
                  code: echo "Hello from shell"
      responses:
        "200":
          description: Stream of code execution events
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ServerStreamEvent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Interrupt code execution
      description: |
        Interrupts the currently running code execution in the specified context.
        This sends a signal to terminate the execution process and releases associated resources.
      operationId: interruptCode
      tags:
        - CodeInterpreting
      parameters:
        - name: id
          in: query
          required: true
          description: |
            Execution session ID of the running code execution to interrupt
            (the `init` event's id for the current run). Passing an unknown
            id fails loudly with a 500 "no such session" error; it is not
            silently ignored.
          schema:
            type: string
          example: exec-123
      responses:
        "200":
          description: Code execution successfully interrupted
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /session:
    post:
      summary: Create bash session (create_session)
      description: |
        Creates a new bash session and returns a session ID for subsequent run_in_session requests.
        The session maintains shell state (e.g. working directory, environment) across multiple
        code executions. Request body is optional; an empty body uses default options (no cwd override).
      operationId: createSession
      tags:
        - Command
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSessionRequest"
            examples:
              default:
                summary: Default (empty body allowed)
                value: {}
              with_cwd:
                summary: With working directory
                value:
                  cwd: /workspace
      responses:
        "200":
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSessionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /session/{sessionId}/run:
    post:
      summary: Run command in bash session (run_in_session)
      description: |
        Executes a shell command in an existing bash session and streams the output in real-time via SSE
        (Server-Sent Events). The session must have been created by create_session. Supports
        optional working directory override and timeout (milliseconds).
        The run streams a single merged `stdout` event stream (session stderr is merged into it).
        Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate
        text from the stdout events to recover the run's output; blank lines appear as events
        containing only the line ending, and the final event may be an unterminated fragment.
        A line longer than 16 MiB is split across several events, and only the last of them
        ends with the line ending.
      operationId: runInSession
      tags:
        - Command
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Session ID returned by create_session
          schema:
            type: string
          example: session-abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunInSessionRequest"
            examples:
              simple:
                summary: Run shell command
                value:
                  command: echo "Hello from session"
              with_options:
                summary: With cwd and timeout
                value:
                  command: ls -la
                  cwd: /workspace
                  timeout: 30000
      responses:
        "200":
          description: Stream of execution events
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ServerStreamEvent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /session/{sessionId}:
    delete:
      summary: Delete bash session (delete_session)
      description: |
        Deletes an existing bash session by ID. Terminates the underlying shell process
        and releases resources. The session ID must have been returned by create_session.
      operationId: deleteSession
      tags:
        - Command
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Session ID to delete
          schema:
            type: string
          example: session-abc123
      responses:
        "200":
          description: Session deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /command:
    post:
      summary: Execute shell command or native argv
      description: |
        Executes shell text (`command`) or native arguments (`argv`) and streams output using SSE; supply exactly one input mode.
        The command can run in foreground or background mode. The response includes stdout, stderr,
        execution status, and completion events.
        In foreground mode, stdout and stderr event text preserves the original line endings
        (`\n`, `\r`, or `\r\n`). Concatenate text from each stream's events to recover its output;
        the final event may contain an unterminated fragment.
        Optionally specify `timeout` (milliseconds) to enforce a maximum runtime; the server will
        terminate the process when the timeout is reached. You can also pass `uid`/`gid` to run
        with specific user/group IDs, and `envs` to inject environment variables.
      operationId: runCommand
      tags:
        - Command
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunCommandRequest"
            examples:
              foreground:
                summary: Foreground command
                value:
                  command: ls -la /workspace
                  cwd: /workspace
                  background: false
                  timeout: 30000
                  uid: 1000
                  gid: 1000
                  envs:
                    PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
                    PYTHONUNBUFFERED: "1"
              background:
                summary: Background command
                value:
                  command: python server.py
                  cwd: /app
                  background: true
                  timeout: 120000
                  uid: 1000
                  envs:
                    APP_ENV: production
                    LOG_LEVEL: info
      responses:
        "200":
          description: Stream of command execution events
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ServerStreamEvent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Interrupt command execution
      description: |
        Interrupts the currently running command execution in the specified context.
        This sends a signal to terminate the execution process and releases associated resources.
      operationId: interruptCommand
      tags:
        - Command
      parameters:
        - name: id
          in: query
          required: true
          description: Session ID of the execution context to interrupt
          schema:
            type: string
          example: session-456
      responses:
        "200":
          description: Command execution successfully interrupted
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /command/status/{id}:
    get:
      summary: Get command running status
      description: |
        Returns the current status of a command (foreground or background) by command ID.
        Includes running flag, exit code, error (if any), and start/finish timestamps.
        Completed command metadata is retained for at least 24 hours and then removed
        by an hourly cleanup. Running commands are never removed by retention cleanup.
      operationId: getCommandStatus
      tags:
        - Command
      parameters:
        - name: id
          in: path
          required: true
          description: Command ID returned by RunCommand
          schema:
            type: string
          example: cmd-abc123
      responses:
        "200":
          description: Command status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommandStatusResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /command/{id}/logs:
    get:
      summary: Get background command stdout/stderr (non-streamed)
      description: |
        Returns stdout and stderr for a background (detached) command by command ID.
        Foreground commands should be consumed via SSE; this endpoint is intended for
        polling logs of background commands. Supports incremental reads similar to a file seek:
        pass a starting line via query to fetch output after that line and receive the latest
        tail cursor for the next poll. When no starting line is provided, the full logs are returned.
        Response body is plain text so it can be rendered directly in browsers; the latest line index
        is provided via response header `EXECD-COMMANDS-TAIL-CURSOR` for subsequent incremental requests.
        Completed background command output is retained for at least 24 hours and then
        removed by an hourly cleanup. Running command output is never removed by retention cleanup.
      operationId: getBackgroundCommandLogs
      tags:
        - Command
      parameters:
        - name: id
          in: path
          required: true
          description: Command ID returned by RunCommand
          schema:
            type: string
          example: cmd-abc123
        - name: cursor
          in: query
          required: false
          description: |
            Optional 0-based line cursor (behaves like a file seek). When provided, only
            stdout/stderr lines after this line are returned. The response includes the
            latest line index (`cursor`) so the client can request incremental output
            on subsequent calls. If omitted, the full log is returned.
          schema:
            type: integer
            format: int64
            minimum: 0
          example: 120
      responses:
        "200":
          description: Command output (plain text) and status metadata via headers
          content:
            text/plain:
              schema:
                type: string
              example: |
                line1
                line2
                warn: something on stderr
          headers:
            EXECD-COMMANDS-TAIL-CURSOR:
              description: Highest available 0-based line index after applying the request cursor (use as the next cursor for incremental reads)
              schema:
                type: integer
                format: int64
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/info:
    get:
      summary: Get file metadata
      description: |
        Retrieves detailed metadata for one or multiple files including permissions, owner,
        group, size, and modification time. Returns a map of file paths to their corresponding
        FileInfo objects.
      operationId: getFilesInfo
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: File path(s) to get info for (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          examples:
            single:
              summary: Single file
              value: ["/workspace/file.txt"]
            multiple:
              summary: Multiple files
              value: ["/workspace/file1.txt", "/workspace/file2.py"]
      responses:
        "200":
          description: Map of file paths to FileInfo objects
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/FileInfo"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files:
    delete:
      summary: Delete files
      description: |
        Deletes one or multiple files from the sandbox. Only removes files, not directories.
        Use RemoveDirs for directory removal.
      operationId: removeFiles
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: File path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["/workspace/temp.txt"]
      responses:
        "200":
          description: Files deleted successfully
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/permissions:
    post:
      summary: Change file permissions
      description: |
        Changes permissions (mode), owner, and group for one or multiple files.
        Accepts a map of file paths to permission settings including octal mode,
        owner username, and group name.
      operationId: chmodFiles
      tags:
        - Filesystem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
            example:
              "/workspace/script.sh":
                owner: admin
                group: admin
                mode: 755
              "/workspace/config.json":
                owner: admin
                group: admin
                mode: 755
      responses:
        "200":
          description: Permissions changed successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/mv:
    post:
      summary: Rename or move files
      description: |
        Renames or moves one or multiple files to new paths. Can be used for both
        renaming within the same directory and moving to different directories.
        Target directory must exist.
      operationId: renameFiles
      tags:
        - Filesystem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/RenameFileItem"
            example:
              - src: /workspace/old_name.txt
                dest: /workspace/new_name.txt
              - src: /workspace/file.py
                dest: /archive/file.py
      responses:
        "200":
          description: Files renamed/moved successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/search:
    get:
      summary: Search for files
      description: |
        Searches for files matching a glob pattern within a specified directory and
        its subdirectories. Returns file metadata including path, permissions, owner,
        and group. Supports glob patterns like **, *.txt, etc. Default pattern is ** (all files).
      operationId: searchFiles
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: Root directory path to search in
          schema:
            type: string
        - name: pattern
          in: query
          required: false
          description: Glob pattern to match files (default is **)
          schema:
            type: string
            default: "**"
      responses:
        "200":
          description: Array of matching files with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/replace:
    post:
      summary: Replace file content
      description: |
        Performs text replacement in one or multiple files. Replaces all occurrences
        of the old string with the new string (similar to strings.ReplaceAll).
        Preserves file permissions. Useful for batch text substitution across files.

        When `verbose=true` is set, the response includes per-file replacement counts.
        Without this parameter, the response body is empty (backward-compatible behavior).
      operationId: replaceContent
      tags:
        - Filesystem
      parameters:
        - name: verbose
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, return per-file replacement counts in the response body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/ReplaceFileContentItem"
            example:
              "/workspace/config.yaml":
                old: "localhost:8080"
                new: "0.0.0.0:9090"
              "/workspace/app.py":
                old: "DEBUG = True"
                new: "DEBUG = False"
      responses:
        "200":
          description: |
            Content replaced successfully. When `verbose=true`, returns per-file
            replacement counts. Otherwise, the response body is empty.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/ReplaceFileContentResult"
              example:
                "/workspace/config.yaml":
                  replacedCount: 1
                "/workspace/app.py":
                  replacedCount: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/upload:
    post:
      summary: Upload files to sandbox
      description: |
        Uploads one or multiple files to specified paths within the sandbox.
        Reads metadata and file content from multipart form parts in sequence.
        Each file upload consists of two parts: a metadata part (JSON) followed
        by the actual file part.
      operationId: uploadFile
      tags:
        - Filesystem
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: JSON-encoded file metadata (FileMetadata object)
                  example: '{"path":"/workspace/file.txt","owner":"admin","group":"admin","mode":755}'
                file:
                  type: string
                  format: binary
                  description: File to upload
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: application/octet-stream
      responses:
        "200":
          description: Files uploaded successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /files/download:
    get:
      summary: Download file from sandbox
      description: |
        Downloads a file from the specified path within the sandbox. Supports HTTP
        range requests for resumable downloads and partial content retrieval.
        Returns file as octet-stream with appropriate headers.

        When offset/limit query parameters are provided, the endpoint performs
        line-based reading and returns text/plain content instead. Line-based
        parameters are mutually exclusive with the Range header.
      operationId: downloadFile
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: Absolute or relative path of the file to download
          schema:
            type: string
          example: /workspace/data.csv
        - name: offset
          in: query
          required: false
          description: >
            Starting line number (1-based) for line-based reading.
            Mutually exclusive with the Range header.
          schema:
            type: integer
            minimum: 1
          example: 100
        - name: limit
          in: query
          required: false
          description: >
            Number of lines to return for line-based reading.
            Mutually exclusive with the Range header.
          schema:
            type: integer
            minimum: 1
          example: 20
        - name: Range
          in: header
          required: false
          description: HTTP Range header for partial content requests. Mutually exclusive with offset/limit.
          schema:
            type: string
          example: "bytes=0-1023"
      responses:
        "200":
          description: |
            File content. Returns application/octet-stream for full or byte-range
            downloads, or text/plain for line-based reads (when offset/limit are provided).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                description: Line-based content returned when offset/limit parameters are used
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Attachment header with filename (byte-range mode only)
            Content-Length:
              schema:
                type: integer
              description: File size in bytes (byte-range mode only)
        "206":
          description: Partial file content (when Range header is provided)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Range:
              schema:
                type: string
              description: Range of bytes being returned
            Content-Length:
              schema:
                type: integer
              description: Length of the returned range
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "416":
          description: Requested range not satisfiable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /directories/list:
    get:
      summary: List directory contents
      description: |
        Lists entries under a directory with optional depth control. By default,
        only immediate children are returned (`depth=1`). Set `depth` to a larger
        value to include descendants up to that many levels below `path`. The
        root directory itself is not included in the response.

        Symbolic links are reported with `type=symlink` and are not traversed:
        the listing never descends into a link target, even when `depth` would
        otherwise allow it. For the same reason, when `path` itself resolves to
        a symbolic link the request is rejected with `400`; callers must pass
        the real directory path they want listed.

        Entries are returned in lexical order by entry name within each
        directory. Descendants reported via `depth>1` follow their parent in
        the same lexical order, so a depth-2 listing yields stable, predictable
        output for file-browser style clients.
      operationId: listDirectory
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: Directory path to list
          schema:
            type: string
          example: /workspace/project
        - name: depth
          in: query
          required: false
          description: Maximum child depth to include. `1` lists immediate children only.
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
          example: 2
      responses:
        "200":
          description: Array of directory entries with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
              example:
                - path: /workspace/project/src
                  type: directory
                  size: 0
                  modified_at: 2025-11-16T14:30:45Z
                  created_at: 2025-11-16T14:30:45Z
                  owner: admin
                  group: admin
                  mode: 755
                - path: /workspace/project/README.md
                  type: file
                  size: 2048
                  modified_at: 2025-11-16T14:30:45Z
                  created_at: 2025-11-16T14:30:45Z
                  owner: admin
                  group: admin
                  mode: 644
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /directories:
    post:
      summary: Create directories
      description: |
        Creates one or multiple directories with specified permissions. Creates parent
        directories as needed (similar to mkdir -p). Accepts a map of directory paths
        to permission objects.
      operationId: makeDirs
      tags:
        - Filesystem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
            example:
              "/workspace/project":
                owner: admin
                group: admin
                mode: 755
              "/workspace/logs":
                owner: admin
                group: admin
                mode: 755
      responses:
        "200":
          description: Directories created successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete directories
      description: |
        Recursively deletes one or multiple directories and all their contents.
        Similar to rm -rf. Use with caution as this operation cannot be undone.
      operationId: removeDirs
      tags:
        - Filesystem
      parameters:
        - name: path
          in: query
          required: true
          description: Directory path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["/workspace/temp"]
      responses:
        "200":
          description: Directories deleted successfully
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/info:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    get:
      summary: Get file metadata
      description: |
        Retrieves detailed metadata for one or multiple files including permissions, owner,
        group, size, and modification time. Returns a map of file paths to their corresponding
        FileInfo objects.
      operationId: identityGetFilesInfo
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: File path(s) to get info for (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          examples:
            single:
              summary: Single file
              value: ["/workspace/file.txt"]
            multiple:
              summary: Multiple files
              value: ["/workspace/file1.txt", "/workspace/file2.py"]
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Map of file paths to FileInfo objects
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    delete:
      summary: Delete files
      description: |
        Deletes one or multiple files from the sandbox. Only removes files, not directories.
        Use RemoveDirs for directory removal.
      operationId: identityRemoveFiles
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: File path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["/workspace/temp.txt"]
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Files deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/permissions:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    post:
      summary: Change file permissions
      description: |
        Changes permissions (mode), owner, and group for one or multiple files.
        Accepts a map of file paths to permission settings including octal mode,
        owner username, and group name.
      operationId: identityChmodFiles
      tags:
        - FilesystemIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
            example:
              "/workspace/script.sh":
                owner: admin
                group: admin
                mode: 755
              "/workspace/config.json":
                owner: admin
                group: admin
                mode: 755
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Permissions changed successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/mv:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    post:
      summary: Rename or move files
      description: |
        Renames or moves one or multiple files to new paths. Can be used for both
        renaming within the same directory and moving to different directories.
        Target directory must exist.
      operationId: identityRenameFiles
      tags:
        - FilesystemIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/RenameFileItem"
            example:
              - src: /workspace/old_name.txt
                dest: /workspace/new_name.txt
              - src: /workspace/file.py
                dest: /archive/file.py
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Files renamed/moved successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/search:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    get:
      summary: Search for files
      description: |
        Searches for files matching a glob pattern within a specified directory and
        its subdirectories. Returns file metadata including path, permissions, owner,
        and group. Supports glob patterns like **, *.txt, etc. Default pattern is ** (all files).
      operationId: identitySearchFiles
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: Root directory path to search in
          schema:
            type: string
        - name: pattern
          in: query
          required: false
          description: Glob pattern to match files (default is **)
          schema:
            type: string
            default: "**"
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Array of matching files with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/replace:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    post:
      summary: Replace file content
      description: |
        Performs text replacement in one or multiple files. Replaces all occurrences
        of the old string with the new string (similar to strings.ReplaceAll).
        Preserves file permissions. Useful for batch text substitution across files.

        When `verbose=true` is set, the response includes per-file replacement counts.
        Without this parameter, the response body is empty (backward-compatible behavior).
      operationId: identityReplaceContent
      tags:
        - FilesystemIdentity
      parameters:
        - name: verbose
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, return per-file replacement counts in the response body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/ReplaceFileContentItem"
            example:
              "/workspace/config.yaml":
                old: "localhost:8080"
                new: "0.0.0.0:9090"
              "/workspace/app.py":
                old: "DEBUG = True"
                new: "DEBUG = False"
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: |
            Content replaced successfully. When `verbose=true`, returns per-file
            replacement counts. Otherwise, the response body is empty.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/ReplaceFileContentResult"
              example:
                "/workspace/config.yaml":
                  replacedCount: 1
                "/workspace/app.py":
                  replacedCount: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/upload:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    post:
      summary: Upload files to sandbox
      description: |
        Uploads one or multiple files to specified paths within the sandbox.
        Reads metadata and file content from multipart form parts in sequence.
        Each file upload consists of two parts: a metadata part (JSON) followed
        by the actual file part.
      operationId: identityUploadFile
      tags:
        - FilesystemIdentity
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: JSON-encoded file metadata (FileMetadata object)
                  example: '{"path":"/workspace/file.txt","owner":"admin","group":"admin","mode":755}'
                file:
                  type: string
                  format: binary
                  description: File to upload
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: application/octet-stream
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Files uploaded successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/files/download:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    get:
      summary: Download file from sandbox
      description: |
        Downloads a file from the specified path within the sandbox. Supports HTTP
        range requests for resumable downloads and partial content retrieval.
        Returns file as octet-stream with appropriate headers.

        When offset/limit query parameters are provided, the endpoint performs
        line-based reading and returns text/plain content instead. Line-based
        parameters are mutually exclusive with the Range header.
      operationId: identityDownloadFile
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: Absolute or relative path of the file to download
          schema:
            type: string
          example: /workspace/data.csv
        - name: offset
          in: query
          required: false
          description: >
            Starting line number (1-based) for line-based reading.
            Mutually exclusive with the Range header.
          schema:
            type: integer
            minimum: 1
          example: 100
        - name: limit
          in: query
          required: false
          description: >
            Number of lines to return for line-based reading.
            Mutually exclusive with the Range header.
          schema:
            type: integer
            minimum: 1
          example: 20
        - name: Range
          in: header
          required: false
          description: HTTP Range header for partial content requests. Mutually exclusive with offset/limit.
          schema:
            type: string
          example: "bytes=0-1023"
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: |
            File content. Returns application/octet-stream for full or byte-range
            downloads, or text/plain for line-based reads (when offset/limit are provided).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                description: Line-based content returned when offset/limit parameters are used
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Attachment header with filename (byte-range mode only)
            Content-Length:
              schema:
                type: integer
              description: File size in bytes (byte-range mode only)
        "206":
          description: Partial file content (when Range header is provided)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Range:
              schema:
                type: string
              description: Range of bytes being returned
            Content-Length:
              schema:
                type: integer
              description: Length of the returned range
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "416":
          description: Requested range not satisfiable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/directories/list:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    get:
      summary: List directory contents
      description: |
        Lists entries under a directory with optional depth control. By default,
        only immediate children are returned (`depth=1`). Set `depth` to a larger
        value to include descendants up to that many levels below `path`. The
        root directory itself is not included in the response.

        Symbolic links are reported with `type=symlink` and are not traversed:
        the listing never descends into a link target, even when `depth` would
        otherwise allow it. For the same reason, when `path` itself resolves to
        a symbolic link the request is rejected with `400`; callers must pass
        the real directory path they want listed.

        Entries are returned in lexical order by entry name within each
        directory. Descendants reported via `depth>1` follow their parent in
        the same lexical order, so a depth-2 listing yields stable, predictable
        output for file-browser style clients.
      operationId: identityListDirectory
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: Directory path to list
          schema:
            type: string
          example: /workspace/project
        - name: depth
          in: query
          required: false
          description: Maximum child depth to include. `1` lists immediate children only.
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
          example: 2
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Array of directory entries with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
              example:
                - path: /workspace/project/src
                  type: directory
                  size: 0
                  modified_at: 2025-11-16T14:30:45Z
                  created_at: 2025-11-16T14:30:45Z
                  owner: admin
                  group: admin
                  mode: 755
                - path: /workspace/project/README.md
                  type: file
                  size: 2048
                  modified_at: 2025-11-16T14:30:45Z
                  created_at: 2025-11-16T14:30:45Z
                  owner: admin
                  group: admin
                  mode: 644
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/filesystem/{uid}/{gid}/directories:
    description: |
      Runs this filesystem operation in a separate process as the selected UID/GID.
      Supplementary groups are resolved from the selected system account; an unknown
      UID receives no supplementary groups. Lookup and credential setup errors fail
      closed. Target owner/group/mode metadata never changes the execution identity.
      Keep API credentials in a trusted backend that selects identities. Unsupported
      servers return an unknown route; callers must not retry an unprefixed route.
    parameters:
      - $ref: '#/components/parameters/FilesystemUid'
      - $ref: '#/components/parameters/FilesystemGid'
    post:
      summary: Create directories
      description: |
        Creates one or multiple directories with specified permissions. Creates parent
        directories as needed (similar to mkdir -p). Accepts a map of directory paths
        to permission objects.
      operationId: identityMakeDirs
      tags:
        - FilesystemIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
            example:
              "/workspace/project":
                owner: admin
                group: admin
                mode: 755
              "/workspace/logs":
                owner: admin
                group: admin
                mode: 755
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Directories created successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete directories
      description: |
        Recursively deletes one or multiple directories and all their contents.
        Similar to rm -rf. Use with caution as this operation cannot be undone.
      operationId: identityRemoveDirs
      tags:
        - FilesystemIdentity
      parameters:
        - name: path
          in: query
          required: true
          description: Directory path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["/workspace/temp"]
      responses:
        "501":
          description: Filesystem execution identity requires Linux.
        "503":
          description: The requested identity could not be established or the worker failed; no fallback to Execd identity occurs.
        "200":
          description: Directories deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /metrics:
    get:
      summary: Get system metrics
      description: |
        Retrieves current system resource metrics including CPU usage percentage,
        CPU core count, total memory, used memory, and timestamp. Provides a snapshot
        of system resource utilization at the time of request.
      operationId: getMetrics
      tags:
        - Metric
      responses:
        "200":
          description: Current system metrics including CPU and memory usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metrics"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /metrics/watch:
    get:
      summary: Watch system metrics in real-time
      description: |
        Streams system resource metrics in real-time using Server-Sent Events (SSE).
        Updates are sent every second, providing continuous monitoring of CPU usage,
        memory usage, and other system metrics. The connection remains open until
        the client disconnects.
      operationId: watchMetrics
      tags:
        - Metric
      responses:
        "200":
          description: Stream of system metrics updated every second
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/Metrics"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /v1/isolated/session:
    post:
      summary: Create an isolated bash session
      operationId: createIsolatedSession
      tags:
        - IsolatedExecution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIsolatedSessionRequest"
            examples:
              workspace:
                summary: Single workspace (legacy field)
                value:
                  workspace:
                    path: /workspace
                    mode: overlay
              overlays:
                summary: Root overlay plus separate workspace overlay
                value:
                  overlays:
                    - path: /
                      mode: overlay
                    - path: /workspace
                      mode: overlay
                      persist: true
              ephemeral_overlay:
                summary: Workspace with a discarded ephemeral upper
                value:
                  overlays:
                    - path: /workspace
                      mode: overlay
                      persist: false
      responses:
        "201":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IsolatedCreateSessionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/sessions:
    get:
      summary: List isolated sessions
      operationId: listIsolatedSessions
      tags:
        - IsolatedExecution
      responses:
        "200":
          description: List of active isolated sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListIsolatedSessionsResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/capabilities:
    get:
      summary: Get isolator capabilities
      operationId: isolatedCapabilities
      tags:
        - IsolatedExecution
      responses:
        "200":
          description: Isolator capabilities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CapabilitiesResponse"

  /v1/isolated/session/{sessionId}:
    get:
      summary: Get isolated session state
      description: >-
        Returns runtime status plus the creation parameters of the session.
        A stateless client that only has a session ID (e.g. after a restart)
        can call this endpoint to rebuild a session handle without needing
        to have retained the original create request.
      operationId: getIsolatedSession
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Session state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionState"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete an isolated session
      operationId: deleteIsolatedSession
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Session deleted
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/run:
    post:
      summary: Run code in an isolated session
      description: >-
        Runs code inside an existing isolated session. Foreground mode
        (default) streams output via SSE (200). Background mode
        (`background: true`) starts the command detached and returns a JSON
        run handle with 202 Accepted for polling status and logs via
        `/v1/isolated/session/{sessionId}/runs/{runId}` and
        `.../runs/{runId}/logs`. `timeout_seconds` applies to foreground
        runs only; background runs are not time-limited (idle GC is suspended
        while one is active) and are bounded by the session lifetime.
        Foreground streams emit periodic `ping` keepalive events so idle
        gateway timeouts do not reap the connection while the command
        produces no output; clients must ignore unrecognized event types.
      operationId: runInIsolatedSession
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IsolatedRunRequest"
      responses:
        "200":
          description: SSE stream of execution events (foreground runs only)
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ServerStreamEvent"
        "202":
          description: >-
            JSON run handle for background runs (background: true). The run
            was accepted and started detached; poll status and logs via
            `/v1/isolated/session/{sessionId}/runs/{runId}`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IsolatedBackgroundRunResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/runs/{runId}:
    get:
      summary: Get isolated background run status
      description: |
        Returns the lifecycle state of a background run started with
        `background: true` on the run endpoint. Includes the running flag,
        exit code (when finished), error (if any), and start/finish timestamps.
        Run records live as long as their session; they are removed when the
        session is deleted or garbage-collected.
      operationId: getIsolatedRunStatus
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: runId
          in: path
          required: true
          description: Run ID returned by the background run endpoint
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Background run status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IsolatedRunStatus"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/runs/{runId}/logs:
    get:
      summary: Get isolated background run logs (non-streamed)
      description: |
        Returns the combined stdout/stderr of a background run as plain text.
        Supports incremental reads similar to a file seek: pass a byte offset
        via the `cursor` query parameter to fetch output after that position
        and receive the latest tail cursor via the
        `EXECD-ISOLATED-TAIL-CURSOR` response header for the next poll.
        When no cursor is provided, the log is returned from the start. At
        most 16 MiB are returned per request; use the returned cursor to
        fetch the remainder.
        Per-run log retention is capped at 16 MiB: output beyond the cap is
        discarded when the run completes, so clients that need more than the
        first page should drain incrementally while the run is active.
        Response body is plain text so it can be rendered directly in browsers.
      operationId: getIsolatedRunLogs
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: runId
          in: path
          required: true
          description: Run ID returned by the background run endpoint
          schema:
            type: string
            format: uuid
        - name: cursor
          in: query
          required: false
          description: |
            Optional byte offset (behaves like a file seek). When provided,
            only log bytes after this offset are returned. The response
            includes the latest offset (`EXECD-ISOLATED-TAIL-CURSOR`) so the
            client can request incremental output on subsequent calls.
            At most 16 MiB are returned per request.
            If omitted, the log is returned from the start.
          schema:
            type: integer
            format: int64
            minimum: 0
          example: 120
      responses:
        "200":
          description: Background run log (plain text) and tail cursor via header
          content:
            text/plain:
              schema:
                type: string
              example: |
                line1
                line2
                warn: something on stderr
          headers:
            EXECD-ISOLATED-TAIL-CURSOR:
              description: Highest available byte offset after applying the request cursor (use as the next cursor for incremental reads)
              schema:
                type: integer
                format: int64
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/diff:
    get:
      summary: Download upper directory diff (stub)
      operationId: isolatedSessionDiff
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/commit:
    post:
      summary: Commit upper changes to workspace (stub)
      operationId: isolatedSessionCommit
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/info:
    get:
      summary: Get file information
      operationId: isolatedGetFilesInfo
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          description: File path(s) to get info for (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        "200":
          description: File metadata
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/FileInfo"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/download:
    get:
      summary: Download a file
      operationId: isolatedDownloadFile
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          required: false
          description: Starting line number (1-based) for line-based reading. Mutually exclusive with Range header.
          schema:
            type: integer
            minimum: 1
        - name: limit
          in: query
          required: false
          description: Number of lines to return for line-based reading. Mutually exclusive with Range header.
          schema:
            type: integer
            minimum: 1
        - name: Range
          in: header
          required: false
          description: HTTP Range header for partial content requests. Mutually exclusive with offset/limit.
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                description: Line-based content returned when offset/limit parameters are used
        "206":
          description: Partial file content (when Range header is provided)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/upload:
    post:
      summary: Upload a file
      operationId: isolatedUploadFile
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: JSON-encoded file metadata
                file:
                  type: string
                  format: binary
                  description: File to upload
      responses:
        "200":
          description: File uploaded
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files:
    delete:
      summary: Remove files
      operationId: isolatedRemoveFiles
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          description: File path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        "200":
          description: Files removed
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/mv:
    post:
      summary: Rename or move files
      operationId: isolatedRenameFiles
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/RenameFileItem"
      responses:
        "200":
          description: Files renamed
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/permissions:
    post:
      summary: Change file permissions
      operationId: isolatedChmodFiles
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: Permissions changed
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/replace:
    post:
      summary: Replace file content
      operationId: isolatedReplaceContent
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: verbose
          in: query
          required: false
          schema:
            type: boolean
          description: When true, return per-file replacement counts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/ReplaceFileContentItem"
      responses:
        "200":
          description: Content replaced
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/ReplaceFileContentResult"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/files/search:
    get:
      summary: Search files
      operationId: isolatedSearchFiles
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          description: Root directory path to search in
          schema:
            type: string
        - name: pattern
          in: query
          required: false
          description: Glob pattern to match files (default is **)
          schema:
            type: string
            default: "**"
      responses:
        "200":
          description: Matched files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/directories/list:
    get:
      summary: List directory contents
      operationId: isolatedListDirectory
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          description: Directory path to list
          schema:
            type: string
        - name: depth
          in: query
          required: false
          description: Maximum depth to traverse (default 1)
          schema:
            type: integer
            minimum: 0
            default: 1
      responses:
        "200":
          description: Directory entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /v1/isolated/session/{sessionId}/directories:
    post:
      summary: Create directories
      operationId: isolatedMakeDirs
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: Directories created
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
    delete:
      summary: Remove directories
      operationId: isolatedRemoveDirs
      tags:
        - IsolatedExecution
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          required: true
          description: Directory path(s) to delete (can be specified multiple times)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        "200":
          description: Directories removed
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

components:
  parameters:
    FilesystemUid:
      name: uid
      in: path
      required: true
      description: Linux UID performing the operation, separate from target-file ownership.
      schema:
        type: integer
        format: int64
        minimum: 0
        maximum: 4294967294
    FilesystemGid:
      name: gid
      in: path
      required: true
      description: Primary Linux GID performing the operation.
      schema:
        type: integer
        format: int64
        minimum: 0
        maximum: 4294967294
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: X-EXECD-ACCESS-TOKEN
      description: |
        Access token for API authentication. All requests must include this header
        with a valid token. The token is configured during server initialization.

  schemas:
    CreateSessionRequest:
      type: object
      description: Request to create a bash session (optional body; empty treated as defaults)
      properties:
        cwd:
          type: string
          description: Working directory for the session (optional)
          example: /workspace

    CreateSessionResponse:
      type: object
      description: Response for create_session
      properties:
        session_id:
          type: string
          description: Unique session ID for run_in_session and delete_session
          example: session-abc123
      required:
        - session_id

    RunInSessionRequest:
      type: object
      description: Request to run a command in an existing bash session
      required:
        - command
      properties:
        command:
          type: string
          description: Shell command to execute in the session
          example: echo "Hello"
        cwd:
          type: string
          description: Working directory override for this run (optional)
          example: /workspace
        timeout:
          type: integer
          format: int64
          minimum: 0
          description: Maximum execution time in milliseconds (optional; server may not enforce if omitted)
          example: 30000

    CodeContextRequest:
      type: object
      description: Request to create a code execution context
      properties:
        language:
          type: string
          description: Execution runtime (python, bash, java, etc.)
          example: python

    CodeContext:
      type: object
      description: Code execution context with session identifier
      properties:
        id:
          type: string
          description: Unique session identifier returned by CreateContext
          example: session-abc123
        language:
          type: string
          description: Execution runtime
          example: python
      required:
        - language

    RunCodeRequest:
      type: object
      required:
        - code
      description: Request to execute code in a context
      properties:
        context:
          $ref: "#/components/schemas/CodeContext"
        code:
          type: string
          description: Source code to execute
          example: |
            import numpy as np
            result = np.array([1, 2, 3])
            print(result)

    RunCommandRequest:
      type: object
      # Nest oneOf under allOf so openapi-python-client preserves RunCommandRequest.
      allOf:
        - oneOf:
            - required: [command]
            - required: [argv]
      description: Execute exactly one of command (shell text) or argv (native arguments).
      properties:
        command:
          type: string
          minLength: 1
          description: Shell command to execute. Mutually exclusive with argv.
          example: ls -la /workspace
        argv:
          type: array
          minItems: 1
          items:
            type: string
          description: |
            Executable and literal arguments, mutually exclusive with command. argv[0] must be non-empty; NUL is invalid and arguments are not shell-expanded. Relative paths use cwd; bare names search absolute entries in the child PATH. Windows uses standard argument encoding and adds .exe to extensionless names; batch files require a shell.
          example: [python3, -c, "print('hello')"]
        cwd:
          type: string
          description: |
            Working directory, defaulting to the daemon directory. Expands $NAME and ${NAME} using the command environment, and leading ~ using the daemon user's home. Undefined variables fail validation.
          example: /workspace
        background:
          type: boolean
          description: Whether to run command in detached mode
          default: false
          example: false
        timeout:
          type: integer
          format: int64
          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.
          example: 60000
        uid:
          type: integer
          format: int32
          minimum: 0
          description: |
            Unix user ID used to run the command. If `gid` is provided, `uid` is required.
          example: 1000
        gid:
          type: integer
          format: int32
          minimum: 0
          description: |
            Unix group ID used to run the command. Requires `uid` to be provided.
          example: 1000
        envs:
          type: object
          description: |
            Literal request values overriding EXECD_ENVS and daemon variables, in that order. Names are case-insensitive on Windows.
          additionalProperties:
            type: string
          example:
            PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
            PYTHONUNBUFFERED: "1"

    CommandStatusResponse:
      type: object
      description: Command execution status (foreground or background)
      properties:
        id:
          type: string
          description: Command ID returned by RunCommand
          example: cmd-abc123
        content:
          type: string
          description: Original command content
          example: ls -la
        running:
          type: boolean
          description: Whether the command is still running
          example: false
        exit_code:
          type: integer
          format: int32
          nullable: true
          description: Exit code if the command has finished
          example: 0
        error:
          type: string
          description: Error message if the command failed
          example: permission denied
        started_at:
          type: string
          format: date-time
          description: Start time in RFC3339 format
          example: "2025-12-22T09:08:05Z"
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: Finish time in RFC3339 format (null if still running)
          example: "2025-12-22T09:08:09Z"

    ServerStreamEvent:
      type: object
      description: Server-sent event for streaming execution output
      properties:
        type:
          type: string
          enum:
            - init
            - status
            - error
            - stdout
            - stderr
            - result
            - execution_complete
            - execution_count
            - ping
          description: Event type for client-side handling
          example: stdout
        text:
          type: string
          description: Textual data for status, init, and stream events
          example: "Hello, World!\n"
        execution_count:
          type: integer
          description: Cell execution number in the session
          example: 1
        exit_code:
          type: integer
          description: "Successful foreground POST /command process exit status (0), present only on its execution_complete event after the process has exited. Omitted for background startup acknowledgements, code execution, and other events. Absence does not imply success; older servers omit this field. Non-zero command exits use error.exit_code instead."
          example: 0
        execution_time:
          type: integer
          format: int64
          description: Execution duration in milliseconds
          example: 150
        timestamp:
          type: integer
          format: int64
          description: When the event was generated (Unix milliseconds)
          example: 1700000000000
        results:
          type: object
          additionalProperties: true
          description: Execution output in various MIME types (e.g., "text/plain", "text/html")
          example:
            text/plain: "4"
        error:
          type: object
          description: Execution error details if an error occurred
          properties:
            ename:
              type: string
              description: Error name/type
              example: "NameError"
            evalue:
              type: string
              description: "Error value/message. For `CommandExecError` this is the stringified exit status when the command ran and exited non-zero, and a free-form message when the process could not be started; use `exit_code` to tell the two apart."
              example: "name 'undefined_var' is not defined"
            traceback:
              type: array
              items:
                type: string
              description: Stack trace lines
              example:
                - "Traceback (most recent call last):"
                - '  File "<stdin>", line 1, in <module>'
                - "NameError: name 'undefined_var' is not defined"
            exit_code:
              type: integer
              description: "Exit status of a command that ran and finished with a non-zero status (-1 when it was terminated by a signal). Present only on `CommandExecError` events emitted after the process ran; omitted when the process failed to start and for non-command errors."
              example: 3

    FileInfo:
      type: object
      description: File metadata including path and permissions
      properties:
        path:
          type: string
          description: Absolute file path
          example: /workspace/file.txt
        type:
          type: string
          description: Entry type
          enum: [file, directory, symlink, other]
          example: file
        size:
          type: integer
          format: int64
          description: File size in bytes
          example: 2048
        modified_at:
          type: string
          format: date-time
          description: Last modification time
          example: 2025-11-16T14:30:45Z
        created_at:
          type: string
          format: date-time
          description: File creation time
          example: 2025-11-16T14:30:45Z
        owner:
          type: string
          description: File owner username
          example: admin
        group:
          type: string
          description: File group name
          example: admin
        mode:
          type: integer
          description: File permissions in octal format
          example: 755
      required: [path, size, modified_at, created_at, owner, group, mode]

    Permission:
      type: object
      description: File ownership and mode settings
      properties:
        owner:
          type: string
          description: Owner username
          example: root
        group:
          type: string
          description: Group name
          example: root
        mode:
          type: integer
          description: Permission mode in octal format (e.g., 644, 755)
          default: 755
          example: 755
      required: [mode]

    FileMetadata:
      type: object
      description: File metadata for upload operations
      properties:
        path:
          type: string
          description: Target file path
          example: /workspace/upload.txt
        owner:
          type: string
          description: File owner
          example: admin
        group:
          type: string
          description: File group
          example: admin
        mode:
          type: integer
          description: File permissions in octal
          example: 755

    RenameFileItem:
      type: object
      description: File rename/move operation
      properties:
        src:
          type: string
          description: Source file path
          example: /workspace/old.txt
        dest:
          type: string
          description: Destination file path
          example: /workspace/new.txt
      required: [src, dest]

    ReplaceFileContentItem:
      type: object
      description: Content replacement operation
      properties:
        old:
          type: string
          description: String to be replaced (must not be empty)
          minLength: 1
          example: "localhost"
        new:
          type: string
          description: Replacement string
          example: "0.0.0.0"
      required: [old, new]

    ReplaceFileContentResult:
      type: object
      description: Result of a content replacement operation on a single file
      properties:
        replacedCount:
          type: integer
          description: Number of occurrences replaced. 0 means oldContent was not found in the file.
          example: 1
      required: [replacedCount]

    Metrics:
      type: object
      description: System resource usage metrics
      properties:
        cpu_count:
          type: number
          format: float
          description: Number of CPU cores
          example: 4.0
        cpu_used_pct:
          type: number
          format: float
          description: CPU usage percentage
          example: 45.5
        mem_total_mib:
          type: number
          format: float
          description: Total memory in MiB
          example: 8192.0
        mem_used_mib:
          type: number
          format: float
          description: Used memory in MiB
          example: 4096.0
        timestamp:
          type: integer
          format: int64
          description: Timestamp when metrics were collected (Unix milliseconds)
          example: 1700000000000
      required:
        [cpu_count, cpu_used_pct, mem_total_mib, mem_used_mib, timestamp]

    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: INVALID_REQUEST_BODY
        message:
          type: string
          description: Human-readable error message
          example: "error parsing request, MAYBE invalid body format"
      required: [code, message]

    CreateIsolatedSessionRequest:
      type: object
      description: >-
        Creates an isolated session with one or more overlay mounts. The
        legacy `workspace` field is kept as sugar for a single-element
        `overlays` list: at least one of `workspace` or `overlays` must be
        provided, and when both are present `workspace` is prepended to
        `overlays`. The session files API serves exactly the overlay and
        bind mounts: paths under each mount resolve as the namespace sees
        them, and absolute paths outside every overlay or bind are
        rejected instead of resolving against the workspace (unlike
        binds, extra_writable paths are not served by the files API
        unless an overlay covers them). The strict profile's private
        `/tmp` is a session-owned bind under the upper root and is part
        of that view; a caller bind or overlay on `/tmp` shadows it as
        inside the namespace.
      properties:
        profile:
          type: string
          enum: ["strict", "balanced"]
          description: >-
            Isolation profile. `strict` (default) gives the session a private
            `/tmp` backed by a host directory that the session files API also
            serves; `balanced` shares the sandbox's own `/tmp`, which the
            files API does not serve.
        workspace:
          $ref: "#/components/schemas/IsolatedWorkspaceSpec"
        overlays:
          type: array
          maxItems: 16
          description: >-
            Independent overlay mounts inside one namespace. Each entry gets
            its own copy-on-write upper (or a direct/ro bind for rw/ro
            modes). bubblewrap applies mounts shallow-first, so a nested
            overlay (for example `/workspace` on top of a `/` root overlay)
            shadows its ancestors within its own subtree. Paths must be
            absolute, unique, and clean (no trailing slash, `.` or `..`
            segments); at most 16 mounts per session (including the legacy
            `workspace`).
          items:
            $ref: "#/components/schemas/IsolatedOverlaySpec"
        extra_writable:
          type: array
          items:
            type: string
        binds:
          type: array
          description: >-
            Additional host paths bind-mounted into the namespace with an
            explicit source-to-destination mapping. Unlike extra_writable
            (which mounts source==destination read-write), each entry may map
            a distinct destination path and be mounted read-only. The source
            path of every entry must fall within the configured writable
            allowlist. The session files API also serves paths under each
            dest from the host source directory: reads and writes are live
            in both directions, symlinked entries are followed like the
            namespace view, and writes are rejected for readonly binds.
            Destinations must be unique across entries and must not be a
            strict ancestor of another mount destination (binds, overlays,
            extra_writable) or fall under /run, /dev, or /proc; such
            overlapping configurations are rejected at session creation.
          items:
            $ref: "#/components/schemas/BindMount"
        share_net:
          type: boolean
        env_passthrough:
          $ref: "#/components/schemas/EnvPassthroughSpec"
        uid:
          type: integer
          format: uint32
        gid:
          type: integer
          format: uint32
        uid_mode:
          type: string
          enum: ["setpriv", "userns"]
          description: >-
            Controls how user identity is established inside the namespace.
            "setpriv" (default) uses real setuid via setpriv(1).
            "userns" creates a user namespace via --unshare-user --disable-userns.
        idle_timeout_seconds:
          type: integer

    IsolatedWorkspaceSpec:
      type: object
      required:
        - path
      properties:
        path:
          type: string
        mode:
          type: string
          enum: ["rw", "overlay", "ro"]

    IsolatedOverlaySpec:
      type: object
      description: >-
        One overlay mount inside the isolated namespace. `mode=overlay`
        mounts a copy-on-write view: with `persist=true` (default) writes
        land in a host upper directory tracked and usage-accounted by execd
        (the substrate for the diff/commit endpoints); with
        `persist=false` the upper is an ephemeral tmpfs whose writes are
        discarded when the session ends. `rw` and `ro` bind the host path
        directly; `persist` applies to overlay mode only and must be
        omitted for them (execd rejects the request otherwise). Overlay
        mode is one-directional for the session files API: while the
        session runs, files-API writes land in the host upper directory
        and are not visible to runs inside the namespace (the kernel
        caches overlayfs directory entries at mount time), while the
        run-to-files direction works; use `rw` or `binds` for
        bidirectional file exchange.
      required:
        - path
      properties:
        path:
          type: string
          description: Mount destination inside the namespace (absolute).
          example: /workspace
        mode:
          type: string
          enum: ["rw", "overlay", "ro"]
          description: Mount mode. Defaults to `overlay`.
        persist:
          type: boolean
          description: >-
            Overlay mode only. When true (default; execd treats an omitted
            value as true) the copy-on-write upper is a host directory
            allocated per session; when false it is an ephemeral tmpfs whose
            writes are discarded when the session ends. Must be omitted for
            `rw` and `ro` modes (execd rejects the request otherwise).
            Because an ephemeral upper lives inside the namespace only, the
            filesystem API serves `persist=false` overlays from their
            host-side (lower) content: in-session writes under such an
            overlay are not observable through the files API and files-API
            writes into the overlay are rejected. Overlay mounts with
            `persist=false` also cannot host background-run logs, so
            background runs are rejected unless the first overlay is `rw`
            or `overlay` with `persist=true`.

    BindMount:
      type: object
      required:
        - source
      properties:
        source:
          type: string
          description: Host path to bind-mount into the namespace.
        dest:
          type: string
          description: >-
            Mount destination inside the namespace. Defaults to source when
            omitted.
        readonly:
          type: boolean
          default: false
          description: >-
            When true the mount is read-only (--ro-bind); otherwise it is
            read-write (--bind).

    EnvPassthroughSpec:
      type: object
      properties:
        mode:
          type: string
          enum: ["allow", "deny"]
        keys:
          type: array
          items:
            type: string

    IsolatedCreateSessionResponse:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    IsolatedRunRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: Shell code to execute inside the session
          example: echo hello
        envs:
          type: object
          additionalProperties:
            type: string
          description: Environment variables exported into the shell before the code runs
        timeout_seconds:
          type: integer
          minimum: 0
          description: |
            Foreground-only timeout. The run is interrupted after this many
            seconds. Ignored for background runs: a background run is not
            time-limited, and idle GC is suspended while it is active, so a
            long-running background command keeps the session alive until it
            finishes (then the normal idle window applies) or the session is
            deleted.
          example: 60
        background:
          type: boolean
          description: |
            When true (default false), start the code detached inside the
            session and return a 202 run handle instead of streaming output.
            The run's combined stdout/stderr is captured to a log file that
            can be polled via the run logs endpoint; its lifecycle is tracked
            via the run status endpoint.
            Background runs share the session's process group, so session-
            level signals (for example the SIGINT sent when a foreground run
            times out or is cancelled) also reach them; execd cannot signal
            individual in-namespace processes.
            Background runs require a writable log location under the first
            overlay, so sessions whose first overlay is read-only (`ro`) or
            an ephemeral overlay (`persist: false`) reject them with 400.
            rw overlays and persistent (`persist: true`) overlays are
            supported.
          example: false

    IsolatedBackgroundRunResponse:
      type: object
      description: "Handle returned when a run is started with background: true"
      required:
        - session_id
        - run_id
        - started_at
      properties:
        session_id:
          type: string
          format: uuid
          description: Session the run was started in
        run_id:
          type: string
          format: uuid
          description: Run ID for status and logs polling
        started_at:
          type: string
          format: date-time
          description: Run start time in RFC3339 format

    IsolatedRunStatus:
      type: object
      description: Lifecycle state of an isolated background run
      required:
        - session_id
        - run_id
        - running
        - started_at
      properties:
        session_id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        running:
          type: boolean
          description: Whether the run is still executing
          example: false
        exit_code:
          type: integer
          format: int32
          nullable: true
          description: Exit code of the code if the run has finished
          example: 0
        error:
          type: string
          description: Error message if the run failed (e.g. session terminated)
          example: session terminated
        started_at:
          type: string
          format: date-time
          description: Run start time in RFC3339 format
          example: "2025-12-22T09:08:05Z"
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: Run finish time in RFC3339 format (null if still running)
          example: "2025-12-22T09:08:09Z"

    SessionState:
      type: object
      description: >-
        State of an isolated session. Runtime status fields (status,
        created_at, last_run_at, idle_remaining_seconds) are always present.
        Creation-parameter fields (profile, workspace, overlays, binds,
        share_net, env_passthrough, uid, gid, uid_mode, extra_writable,
        idle_timeout_seconds) echo the parameters used to create the session
        and let a stateless client rebuild a session handle from just a
        session ID (e.g. after a client restart or in serverless workers).
        `overlays` lists the effective mounts; for sessions created via the
        legacy `workspace` field it repeats that workspace as a single
        element, and `workspace` itself is only echoed for such
        single-overlay sessions. Older execd builds may omit the
        creation-parameter fields; clients must tolerate them being absent.
      properties:
        status:
          type: string
          enum: ["active", "dead", "destroyed"]
        created_at:
          type: string
          format: date-time
        last_run_at:
          type: string
          format: date-time
        idle_remaining_seconds:
          type: integer
          nullable: true
        profile:
          type: string
          enum: ["strict", "balanced"]
          description: Profile the session was created with.
        workspace:
          $ref: "#/components/schemas/IsolatedWorkspaceSpec"
        overlays:
          type: array
          description: Effective overlay mounts of the session.
          items:
            $ref: "#/components/schemas/IsolatedOverlaySpec"
        extra_writable:
          type: array
          items:
            type: string
        binds:
          type: array
          items:
            $ref: "#/components/schemas/BindMount"
        share_net:
          type: boolean
        env_passthrough:
          $ref: "#/components/schemas/EnvPassthroughSpec"
        uid:
          type: integer
          format: uint32
        gid:
          type: integer
          format: uint32
        uid_mode:
          type: string
          enum: ["setpriv", "userns"]
        idle_timeout_seconds:
          type: integer

    IsolatedSessionSummary:
      type: object
      required:
        - session_id
        - status
        - created_at
        - last_run_at
      properties:
        session_id:
          type: string
          format: uuid
        status:
          type: string
          enum: ["active", "dead", "destroyed"]
        created_at:
          type: string
          format: date-time
        last_run_at:
          type: string
          format: date-time
        idle_remaining_seconds:
          type: integer
          nullable: true

    ListIsolatedSessionsResponse:
      type: object
      required:
        - sessions
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/IsolatedSessionSummary"

    CapabilitiesResponse:
      type: object
      properties:
        available:
          type: boolean
        isolator:
          type: string
        version:
          type: string
        message:
          type: string
          description: >-
            Diagnostic message when isolation is unavailable or degraded (for
            example, share_net=true sessions work but no uid mode can create
            the private network namespace required by share_net=false)
        setpriv_available:
          type: boolean
          description: >-
            Whether sessions using uid_mode setpriv can be created with execd's
            default UID/GID. Requests that select different UID/GID values may
            still return 503 NOT_SUPPORTED when identity switching is
            unavailable.
        userns_available:
          type: boolean
          description: Whether sessions using uid_mode userns can be created
        setpriv_net_available:
          type: boolean
          description: >-
            Whether sessions using uid_mode setpriv can also create the private
            network namespace required by share_net=false (bwrap --unshare-net;
            its loopback setup needs CAP_NET_ADMIN in the execd container).
            Create rejects share_net=false requests with 503 NOT_SUPPORTED when
            the requested mode's flag is false.
        userns_net_available:
          type: boolean
          description: >-
            Whether sessions using uid_mode userns can also create the private
            network namespace required by share_net=false.
        commit_supported:
          type: boolean
        diff_supported:
          type: boolean
        hardening:
          type: object
          description: >-
            execd init-mode and workload-hardening state (OSEP-0018): whether
            execd is the sandbox init and which of its controls are in effect.
            Not an isolation capability; reported here so operators see
            enforcement state in one place.
          properties:
            init_mode:
              type: string
              enum: [pid1, subreaper, none]
              description: >-
                How execd supervises the sandbox process tree. pid1: execd is
                the kernel init of the container. subreaper: execd reaps
                orphans but lacks the PID 1 kernel signal shield. none: init
                mode is off (default).
            signal_shield:
              type: boolean
              description: >-
                Whether the kernel PID 1 signal shield protects execd from
                in-namespace signals (true only in init_mode pid1).
            cap_drop:
              $ref: "#/components/schemas/HardeningLayerState"
              description: Capability/bounding-set reduction on user code.
            seccomp:
              $ref: "#/components/schemas/HardeningLayerState"
              description: Seccomp floor installed on user code.
            landlock:
              $ref: "#/components/schemas/HardeningLayerState"
              description: Landlock filesystem confinement on user code.
            ebpf:
              $ref: "#/components/schemas/HardeningLayerState"
              description: eBPF exec/connect/privilege observation.

    HardeningLayerState:
      type: object
      description: >-
        Whether one hardening layer is actually enforced. state is "active" |
        "disabled" (not configured) | "degraded" (configured but a
        prerequisite is missing) | "unsupported" (kernel/build cannot provide
        it). message gives the concrete reason whenever state is not active.
      properties:
        state:
          type: string
          enum: [active, disabled, degraded, unsupported]
        message:
          type: string

  responses:
    ServiceUnavailable:
      description: Isolation subsystem is not available
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    BadRequest:
      description: Invalid request body format or missing required fields
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: INVALID_REQUEST_BODY
            message: "error parsing request, MAYBE invalid body format"

    NotFound:
      description: File or resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: FILE_NOT_FOUND
            message: "file not found"

    InternalServerError:
      description: Runtime server error during operation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: RUNTIME_ERROR
            message: "error running code execution"