wehub-resource-sync
e0e362d700
SDK Tests / changes (push) Waiting to run
SDK Tests / Python SDK Tests (sandbox) (push) Blocked by required conditions
SDK Tests / CLI Quality (push) Blocked by required conditions
SDK Tests / CLI Tests (push) Blocked by required conditions
SDK Tests / Python SDK Quality (code-interpreter) (push) Blocked by required conditions
SDK Tests / Python SDK Quality (sandbox) (push) Blocked by required conditions
SDK Tests / Python SDK Tests (code-interpreter) (push) Blocked by required conditions
SDK Tests / JavaScript SDK Quality And Tests (code-interpreter) (push) Blocked by required conditions
SDK Tests / JavaScript SDK Quality And Tests (sandbox) (push) Blocked by required conditions
Deploy Docs Pages / build (push) Waiting to run
Deploy Docs Pages / deploy (push) Blocked by required conditions
Real E2E Tests / changes (push) Waiting to run
Real E2E Tests / Python E2E (docker bridge) (push) Blocked by required conditions
Real E2E Tests / Java E2E (docker bridge) (push) Blocked by required conditions
Real E2E Tests / JavaScript E2E (docker bridge) (push) Blocked by required conditions
Real E2E Tests / C# E2E (docker bridge) (push) Blocked by required conditions
Real E2E Tests / Go E2E (docker bridge) (push) Blocked by required conditions
Real E2E Tests / Real E2E CI (push) Blocked by required conditions
SDK Tests / Kotlin SDK Quality And Tests (sandbox) (push) Blocked by required conditions
SDK Tests / Kotlin SDK Quality And Tests (code-interpreter) (push) Blocked by required conditions
SDK Tests / C# SDK Quality And Tests (code-interpreter) (push) Blocked by required conditions
SDK Tests / C# SDK Quality And Tests (sandbox) (push) Blocked by required conditions
SDK Tests / Go SDK Quality And Tests (push) Blocked by required conditions
SDK Tests / SDK CI (push) Blocked by required conditions
2295 lines
69 KiB
YAML
2295 lines
69 KiB
YAML
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: 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: Session ID of the execution context to interrupt
|
|
schema:
|
|
type: string
|
|
example: session-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).
|
|
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
|
|
description: |
|
|
Executes a shell command and streams the output in real-time using SSE (Server-Sent Events).
|
|
The command can run in foreground or background mode. The response includes stdout, stderr,
|
|
execution status, and completion events.
|
|
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.
|
|
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.
|
|
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"
|
|
|
|
/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"
|
|
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
|
|
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 (SSE streaming)
|
|
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 output
|
|
content:
|
|
text/event-stream:
|
|
schema:
|
|
$ref: "#/components/schemas/ServerStreamEvent"
|
|
"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:
|
|
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
|
|
required:
|
|
- command
|
|
description: Request to execute a shell command
|
|
properties:
|
|
command:
|
|
type: string
|
|
description: Shell command to execute
|
|
example: ls -la /workspace
|
|
cwd:
|
|
type: string
|
|
description: Working directory for command execution
|
|
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: Environment variables injected into the command process.
|
|
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
|
|
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
|
|
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"
|
|
|
|
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
|
|
required:
|
|
- workspace
|
|
properties:
|
|
profile:
|
|
type: string
|
|
enum: ["strict", "balanced"]
|
|
workspace:
|
|
$ref: "#/components/schemas/IsolatedWorkspaceSpec"
|
|
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.
|
|
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"]
|
|
|
|
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
|
|
envs:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
timeout_seconds:
|
|
type: integer
|
|
minimum: 0
|
|
|
|
SessionState:
|
|
type: object
|
|
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
|
|
|
|
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
|
|
commit_supported:
|
|
type: boolean
|
|
diff_supported:
|
|
type: boolean
|
|
|
|
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"
|