{ "openapi": "3.0.3", "info": { "title": "sandbox-agent", "description": "Universal API for automatic coding agents in sandboxes. Supports Claude Code, Codex, OpenCode, and Amp.", "contact": { "name": "Rivet Gaming, LLC", "email": "developer@rivet.gg" }, "license": { "name": "Apache-2.0" }, "version": "0.4.2" }, "servers": [ { "url": "http://localhost:2468" } ], "paths": { "/v1/acp": { "get": { "tags": ["v1"], "operationId": "get_v1_acp_servers", "responses": { "200": { "description": "Active ACP server instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpServerListResponse" } } } } } } }, "/v1/acp/{server_id}": { "get": { "tags": ["v1"], "operationId": "get_v1_acp", "parameters": [ { "name": "server_id", "in": "path", "description": "Client-defined ACP server id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream of ACP envelopes" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown ACP server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Client does not accept SSE responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": ["v1"], "operationId": "post_v1_acp", "parameters": [ { "name": "server_id", "in": "path", "description": "Client-defined ACP server id", "required": true, "schema": { "type": "string" } }, { "name": "agent", "in": "query", "description": "Agent id required for first POST", "required": false, "schema": { "type": "string", "nullable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpEnvelope" } } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpEnvelope" } } } }, "202": { "description": "JSON-RPC notification accepted" }, "400": { "description": "Invalid ACP envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown ACP server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Client does not accept JSON responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "ACP server bound to different agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "ACP agent process response timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": ["v1"], "operationId": "delete_v1_acp", "parameters": [ { "name": "server_id", "in": "path", "description": "Client-defined ACP server id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "ACP server closed" } } } }, "/v1/agents": { "get": { "tags": ["v1"], "operationId": "get_v1_agents", "parameters": [ { "name": "config", "in": "query", "description": "When true, include version/path/configOptions (slower)", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "no_cache", "in": "query", "description": "When true, bypass version cache", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "List of v1 agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/{agent}": { "get": { "tags": ["v1"], "operationId": "get_v1_agent", "parameters": [ { "name": "agent", "in": "path", "description": "Agent id", "required": true, "schema": { "type": "string" } }, { "name": "config", "in": "query", "description": "When true, include version/path/configOptions (slower)", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "no_cache", "in": "query", "description": "When true, bypass version cache", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Agent info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "400": { "description": "Unknown agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/{agent}/install": { "post": { "tags": ["v1"], "operationId": "post_v1_agent_install", "parameters": [ { "name": "agent", "in": "path", "description": "Agent id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInstallRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent install result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInstallResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Install failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/config/mcp": { "get": { "tags": ["v1"], "operationId": "get_v1_config_mcp", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "mcpName", "in": "query", "description": "MCP entry name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConfig" } } } }, "404": { "description": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": ["v1"], "operationId": "put_v1_config_mcp", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "mcpName", "in": "query", "description": "MCP entry name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConfig" } } }, "required": true }, "responses": { "204": { "description": "Stored" } } }, "delete": { "tags": ["v1"], "operationId": "delete_v1_config_mcp", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "mcpName", "in": "query", "description": "MCP entry name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/config/skills": { "get": { "tags": ["v1"], "operationId": "get_v1_config_skills", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "skillName", "in": "query", "description": "Skill entry name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skills entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillsConfig" } } } }, "404": { "description": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": ["v1"], "operationId": "put_v1_config_skills", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "skillName", "in": "query", "description": "Skill entry name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillsConfig" } } }, "required": true }, "responses": { "204": { "description": "Stored" } } }, "delete": { "tags": ["v1"], "operationId": "delete_v1_config_skills", "parameters": [ { "name": "directory", "in": "query", "description": "Target directory", "required": true, "schema": { "type": "string" } }, { "name": "skillName", "in": "query", "description": "Skill entry name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/desktop/clipboard": { "get": { "tags": ["v1"], "summary": "Read the desktop clipboard.", "description": "Returns the current text content of the X11 clipboard.", "operationId": "get_v1_desktop_clipboard", "parameters": [ { "name": "selection", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Clipboard contents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopClipboardResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Clipboard read failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": ["v1"], "summary": "Write to the desktop clipboard.", "description": "Sets the text content of the X11 clipboard.", "operationId": "post_v1_desktop_clipboard", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopClipboardWriteRequest" } } }, "required": true }, "responses": { "200": { "description": "Clipboard updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopActionResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Clipboard write failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/display/info": { "get": { "tags": ["v1"], "summary": "Get desktop display information.", "description": "Performs a health-gated display query against the managed desktop and\nreturns the current display identifier and resolution.", "operationId": "get_v1_desktop_display_info", "responses": { "200": { "description": "Desktop display information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopDisplayInfoResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Desktop runtime health or display query failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/keyboard/down": { "post": { "tags": ["v1"], "summary": "Press and hold a desktop keyboard key.", "description": "Performs a health-gated `xdotool keydown` operation against the managed\ndesktop.", "operationId": "post_v1_desktop_keyboard_down", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopKeyboardDownRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop keyboard action result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopActionResponse" } } } }, "400": { "description": "Invalid keyboard down request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/keyboard/press": { "post": { "tags": ["v1"], "summary": "Press a desktop keyboard shortcut.", "description": "Performs a health-gated `xdotool key` operation against the managed\ndesktop.", "operationId": "post_v1_desktop_keyboard_press", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopKeyboardPressRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop keyboard action result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopActionResponse" } } } }, "400": { "description": "Invalid keyboard press request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/keyboard/type": { "post": { "tags": ["v1"], "summary": "Type desktop keyboard text.", "description": "Performs a health-gated `xdotool type` operation against the managed\ndesktop.", "operationId": "post_v1_desktop_keyboard_type", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopKeyboardTypeRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop keyboard action result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopActionResponse" } } } }, "400": { "description": "Invalid keyboard type request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/keyboard/up": { "post": { "tags": ["v1"], "summary": "Release a desktop keyboard key.", "description": "Performs a health-gated `xdotool keyup` operation against the managed\ndesktop.", "operationId": "post_v1_desktop_keyboard_up", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopKeyboardUpRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop keyboard action result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopActionResponse" } } } }, "400": { "description": "Invalid keyboard up request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/launch": { "post": { "tags": ["v1"], "summary": "Launch a desktop application.", "description": "Launches an application by name on the managed desktop, optionally waiting\nfor its window to appear.", "operationId": "post_v1_desktop_launch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopLaunchRequest" } } }, "required": true }, "responses": { "200": { "description": "Application launched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopLaunchResponse" } } } }, "404": { "description": "Application not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/click": { "post": { "tags": ["v1"], "summary": "Click on the desktop.", "description": "Performs a health-gated pointer move and click against the managed desktop\nand returns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_click", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseClickRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after click", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse click request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/down": { "post": { "tags": ["v1"], "summary": "Press and hold a desktop mouse button.", "description": "Performs a health-gated optional pointer move followed by `xdotool mousedown`\nand returns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_down", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseDownRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after button press", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse down request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/drag": { "post": { "tags": ["v1"], "summary": "Drag the desktop mouse.", "description": "Performs a health-gated drag gesture against the managed desktop and\nreturns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_drag", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseDragRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after drag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse drag request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/move": { "post": { "tags": ["v1"], "summary": "Move the desktop mouse.", "description": "Performs a health-gated absolute pointer move on the managed desktop and\nreturns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_move", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after move", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse move request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/position": { "get": { "tags": ["v1"], "summary": "Get the current desktop mouse position.", "description": "Performs a health-gated mouse position query against the managed desktop.", "operationId": "get_v1_desktop_mouse_position", "responses": { "200": { "description": "Desktop mouse position", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/scroll": { "post": { "tags": ["v1"], "summary": "Scroll the desktop mouse wheel.", "description": "Performs a health-gated scroll gesture at the requested coordinates and\nreturns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_scroll", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseScrollRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after scroll", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse scroll request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/mouse/up": { "post": { "tags": ["v1"], "summary": "Release a desktop mouse button.", "description": "Performs a health-gated optional pointer move followed by `xdotool mouseup`\nand returns the resulting mouse position.", "operationId": "post_v1_desktop_mouse_up", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMouseUpRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop mouse position after button release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopMousePositionResponse" } } } }, "400": { "description": "Invalid mouse up request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or input failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/open": { "post": { "tags": ["v1"], "summary": "Open a file or URL with the default handler.", "description": "Opens a file path or URL using xdg-open on the managed desktop.", "operationId": "post_v1_desktop_open", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopOpenRequest" } } }, "required": true }, "responses": { "200": { "description": "Target opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopOpenResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/recording/start": { "post": { "tags": ["v1"], "summary": "Start desktop recording.", "description": "Starts an ffmpeg x11grab recording against the managed desktop and returns\nthe created recording metadata.", "operationId": "post_v1_desktop_recording_start", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopRecordingStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop recording started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopRecordingInfo" } } } }, "409": { "description": "Desktop runtime is not ready or a recording is already active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop recording failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/recording/stop": { "post": { "tags": ["v1"], "summary": "Stop desktop recording.", "description": "Stops the active desktop recording and returns the finalized recording\nmetadata.", "operationId": "post_v1_desktop_recording_stop", "responses": { "200": { "description": "Desktop recording stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopRecordingInfo" } } } }, "409": { "description": "No active desktop recording", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop recording stop failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/recordings": { "get": { "tags": ["v1"], "summary": "List desktop recordings.", "description": "Returns the current desktop recording catalog.", "operationId": "get_v1_desktop_recordings", "responses": { "200": { "description": "Desktop recordings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopRecordingListResponse" } } } }, "502": { "description": "Desktop recordings query failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/recordings/{id}": { "get": { "tags": ["v1"], "summary": "Get desktop recording metadata.", "description": "Returns metadata for a single desktop recording.", "operationId": "get_v1_desktop_recording", "parameters": [ { "name": "id", "in": "path", "description": "Desktop recording ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Desktop recording metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopRecordingInfo" } } } }, "404": { "description": "Unknown desktop recording", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": ["v1"], "summary": "Delete a desktop recording.", "description": "Removes a completed desktop recording and its file from disk.", "operationId": "delete_v1_desktop_recording", "parameters": [ { "name": "id", "in": "path", "description": "Desktop recording ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Desktop recording deleted" }, "404": { "description": "Unknown desktop recording", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop recording is still active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/recordings/{id}/download": { "get": { "tags": ["v1"], "summary": "Download a desktop recording.", "description": "Serves the recorded MP4 bytes for a completed desktop recording.", "operationId": "get_v1_desktop_recording_download", "parameters": [ { "name": "id", "in": "path", "description": "Desktop recording ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Desktop recording as MP4 bytes" }, "404": { "description": "Unknown desktop recording", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/screenshot": { "get": { "tags": ["v1"], "summary": "Capture a full desktop screenshot.", "description": "Performs a health-gated full-frame screenshot of the managed desktop and\nreturns the requested image bytes.", "operationId": "get_v1_desktop_screenshot", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/DesktopScreenshotFormat" } ], "nullable": true } }, { "name": "quality", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "scale", "in": "query", "required": false, "schema": { "type": "number", "format": "float", "nullable": true } }, { "name": "showCursor", "in": "query", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Desktop screenshot as image bytes" }, "400": { "description": "Invalid screenshot query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or screenshot capture failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/screenshot/region": { "get": { "tags": ["v1"], "summary": "Capture a desktop screenshot region.", "description": "Performs a health-gated screenshot crop against the managed desktop and\nreturns the requested region image bytes.", "operationId": "get_v1_desktop_screenshot_region", "parameters": [ { "name": "x", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "y", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "width", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "height", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/DesktopScreenshotFormat" } ], "nullable": true } }, { "name": "quality", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } }, { "name": "scale", "in": "query", "required": false, "schema": { "type": "number", "format": "float", "nullable": true } }, { "name": "showCursor", "in": "query", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Desktop screenshot region as image bytes" }, "400": { "description": "Invalid screenshot region", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop runtime health or screenshot capture failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/start": { "post": { "tags": ["v1"], "summary": "Start the private desktop runtime.", "description": "Lazily launches the managed Xvfb/openbox stack, validates display health,\nand returns the resulting desktop status snapshot.", "operationId": "post_v1_desktop_start", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Desktop runtime status after start", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStatusResponse" } } } }, "400": { "description": "Invalid desktop start request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is already transitioning", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Desktop API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Desktop runtime could not be started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/status": { "get": { "tags": ["v1"], "summary": "Get desktop runtime status.", "description": "Returns the current desktop runtime state, dependency status, active\ndisplay metadata, and supervised process information.", "operationId": "get_v1_desktop_status", "responses": { "200": { "description": "Desktop runtime status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStatusResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/stop": { "post": { "tags": ["v1"], "summary": "Stop the private desktop runtime.", "description": "Terminates the managed openbox/Xvfb/dbus processes owned by the desktop\nruntime and returns the resulting status snapshot.", "operationId": "post_v1_desktop_stop", "responses": { "200": { "description": "Desktop runtime status after stop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStatusResponse" } } } }, "409": { "description": "Desktop runtime is already transitioning", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/stream/signaling": { "get": { "tags": ["v1"], "summary": "Open a desktop WebRTC signaling session.", "description": "Upgrades the connection to a WebSocket used for WebRTC signaling between\nthe browser client and the desktop streaming process. Also accepts mouse\nand keyboard input frames as a fallback transport.", "operationId": "get_v1_desktop_stream_ws", "parameters": [ { "name": "access_token", "in": "query", "description": "Bearer token alternative for WS auth", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "101": { "description": "WebSocket upgraded" }, "409": { "description": "Desktop runtime or streaming session is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Desktop stream failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/stream/start": { "post": { "tags": ["v1"], "summary": "Start desktop streaming.", "description": "Enables desktop websocket streaming for the managed desktop.", "operationId": "post_v1_desktop_stream_start", "responses": { "200": { "description": "Desktop streaming started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStreamStatusResponse" } } } } } } }, "/v1/desktop/stream/status": { "get": { "tags": ["v1"], "summary": "Get desktop stream status.", "description": "Returns the current state of the desktop WebRTC streaming session.", "operationId": "get_v1_desktop_stream_status", "responses": { "200": { "description": "Desktop stream status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStreamStatusResponse" } } } } } } }, "/v1/desktop/stream/stop": { "post": { "tags": ["v1"], "summary": "Stop desktop streaming.", "description": "Disables desktop websocket streaming for the managed desktop.", "operationId": "post_v1_desktop_stream_stop", "responses": { "200": { "description": "Desktop streaming stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopStreamStatusResponse" } } } } } } }, "/v1/desktop/windows": { "get": { "tags": ["v1"], "summary": "List visible desktop windows.", "description": "Performs a health-gated visible-window enumeration against the managed\ndesktop and returns the current window metadata.", "operationId": "get_v1_desktop_windows", "responses": { "200": { "description": "Visible desktop windows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowListResponse" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Desktop runtime health or window query failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/windows/focused": { "get": { "tags": ["v1"], "summary": "Get the currently focused desktop window.", "description": "Returns information about the window that currently has input focus.", "operationId": "get_v1_desktop_windows_focused", "responses": { "200": { "description": "Focused window info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowInfo" } } } }, "404": { "description": "No window is focused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/windows/{id}/focus": { "post": { "tags": ["v1"], "summary": "Focus a desktop window.", "description": "Brings the specified window to the foreground and gives it input focus.", "operationId": "post_v1_desktop_window_focus", "parameters": [ { "name": "id", "in": "path", "description": "X11 window ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Window info after focus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowInfo" } } } }, "404": { "description": "Window not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/windows/{id}/move": { "post": { "tags": ["v1"], "summary": "Move a desktop window.", "description": "Moves the specified window to the given position.", "operationId": "post_v1_desktop_window_move", "parameters": [ { "name": "id", "in": "path", "description": "X11 window ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Window info after move", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowInfo" } } } }, "404": { "description": "Window not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/desktop/windows/{id}/resize": { "post": { "tags": ["v1"], "summary": "Resize a desktop window.", "description": "Resizes the specified window to the given dimensions.", "operationId": "post_v1_desktop_window_resize", "parameters": [ { "name": "id", "in": "path", "description": "X11 window ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowResizeRequest" } } }, "required": true }, "responses": { "200": { "description": "Window info after resize", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopWindowInfo" } } } }, "404": { "description": "Window not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Desktop runtime is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/fs/entries": { "get": { "tags": ["v1"], "operationId": "get_v1_fs_entries", "parameters": [ { "name": "path", "in": "query", "description": "Directory path", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Directory entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FsEntry" } } } } } } } }, "/v1/fs/entry": { "delete": { "tags": ["v1"], "operationId": "delete_v1_fs_entry", "parameters": [ { "name": "path", "in": "query", "description": "File or directory path", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Delete directory recursively", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsActionResponse" } } } } } } }, "/v1/fs/file": { "get": { "tags": ["v1"], "operationId": "get_v1_fs_file", "parameters": [ { "name": "path", "in": "query", "description": "File path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content" } } }, "put": { "tags": ["v1"], "operationId": "put_v1_fs_file", "parameters": [ { "name": "path", "in": "query", "description": "File path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Raw file bytes", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Write result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsWriteResponse" } } } } } } }, "/v1/fs/mkdir": { "post": { "tags": ["v1"], "operationId": "post_v1_fs_mkdir", "parameters": [ { "name": "path", "in": "query", "description": "Directory path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Directory created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsActionResponse" } } } } } } }, "/v1/fs/move": { "post": { "tags": ["v1"], "operationId": "post_v1_fs_move", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Move result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsMoveResponse" } } } } } } }, "/v1/fs/stat": { "get": { "tags": ["v1"], "operationId": "get_v1_fs_stat", "parameters": [ { "name": "path", "in": "query", "description": "Path to stat", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Path metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsStat" } } } } } } }, "/v1/fs/upload-batch": { "post": { "tags": ["v1"], "operationId": "post_v1_fs_upload_batch", "parameters": [ { "name": "path", "in": "query", "description": "Destination path", "required": false, "schema": { "type": "string", "nullable": true } } ], "requestBody": { "description": "tar archive body", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Upload/extract result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsUploadBatchResponse" } } } } } } }, "/v1/health": { "get": { "tags": ["v1"], "operationId": "get_v1_health", "responses": { "200": { "description": "Service health response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/processes": { "get": { "tags": ["v1"], "summary": "List all managed processes.", "description": "Returns a list of all processes (running and exited) currently tracked\nby the runtime, sorted by process ID.", "operationId": "get_v1_processes", "parameters": [ { "name": "owner", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ProcessOwner" } ], "nullable": true } } ], "responses": { "200": { "description": "List processes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessListResponse" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": ["v1"], "summary": "Create a long-lived managed process.", "description": "Spawns a new process with the given command and arguments. Supports both\npipe-based and PTY (tty) modes. Returns the process descriptor on success.", "operationId": "post_v1_processes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Started process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInfo" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Process limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/config": { "get": { "tags": ["v1"], "summary": "Get process runtime configuration.", "description": "Returns the current runtime configuration for the process management API,\nincluding limits for concurrency, timeouts, and buffer sizes.", "operationId": "get_v1_processes_config", "responses": { "200": { "description": "Current runtime process config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessConfig" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": ["v1"], "summary": "Update process runtime configuration.", "description": "Replaces the runtime configuration for the process management API.\nValidates that all values are non-zero and clamps default timeout to max.", "operationId": "post_v1_processes_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessConfig" } } }, "required": true }, "responses": { "200": { "description": "Updated runtime process config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessConfig" } } } }, "400": { "description": "Invalid config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/run": { "post": { "tags": ["v1"], "summary": "Run a one-shot command.", "description": "Executes a command to completion and returns its stdout, stderr, exit code,\nand duration. Supports configurable timeout and output size limits.", "operationId": "post_v1_processes_run", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessRunRequest" } } }, "required": true }, "responses": { "200": { "description": "One-off command result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessRunResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}": { "get": { "tags": ["v1"], "summary": "Get a single process by ID.", "description": "Returns the current state of a managed process including its status,\nPID, exit code, and creation/exit timestamps.", "operationId": "get_v1_process", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Process details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInfo" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": ["v1"], "summary": "Delete a process record.", "description": "Removes a stopped process from the runtime. Returns 409 if the process\nis still running; stop or kill it first.", "operationId": "delete_v1_process", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Process deleted" }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Process is still running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/input": { "post": { "tags": ["v1"], "summary": "Write input to a process.", "description": "Sends data to a process's stdin (pipe mode) or PTY writer (tty mode).\nData can be encoded as base64, utf8, or text. Returns 413 if the decoded\npayload exceeds the configured `maxInputBytesPerRequest` limit.", "operationId": "post_v1_process_input", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInputRequest" } } }, "required": true }, "responses": { "200": { "description": "Input accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInputResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Process not writable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Input exceeds configured limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/kill": { "post": { "tags": ["v1"], "summary": "Send SIGKILL to a process.", "description": "Sends SIGKILL to the process and optionally waits up to `waitMs`\nmilliseconds for the process to exit before returning.", "operationId": "post_v1_process_kill", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } }, { "name": "waitMs", "in": "query", "description": "Wait up to N ms for process to exit", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Kill signal sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInfo" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/logs": { "get": { "tags": ["v1"], "summary": "Fetch process logs.", "description": "Returns buffered log entries for a process. Supports filtering by stream\ntype, tail count, and sequence-based resumption. When `follow=true`,\nreturns an SSE stream that replays buffered entries then streams live output.", "operationId": "get_v1_process_logs", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } }, { "name": "stream", "in": "query", "description": "stdout|stderr|combined|pty", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ProcessLogsStream" } ], "nullable": true } }, { "name": "tail", "in": "query", "description": "Tail N entries", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "follow", "in": "query", "description": "Follow via SSE", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "since", "in": "query", "description": "Only entries with sequence greater than this", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Process logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessLogsResponse" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/stop": { "post": { "tags": ["v1"], "summary": "Send SIGTERM to a process.", "description": "Sends SIGTERM to the process and optionally waits up to `waitMs`\nmilliseconds for the process to exit before returning.", "operationId": "post_v1_process_stop", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } }, { "name": "waitMs", "in": "query", "description": "Wait up to N ms for process to exit", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Stop signal sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessInfo" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/terminal/resize": { "post": { "tags": ["v1"], "summary": "Resize a process terminal.", "description": "Sets the PTY window size (columns and rows) for a tty-mode process and\nsends SIGWINCH so the child process can adapt.", "operationId": "post_v1_process_terminal_resize", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessTerminalResizeRequest" } } }, "required": true }, "responses": { "200": { "description": "Resize accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessTerminalResizeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Not a terminal process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/processes/{id}/terminal/ws": { "get": { "tags": ["v1"], "summary": "Open an interactive WebSocket terminal session.", "description": "Upgrades the connection to a WebSocket for bidirectional PTY I/O. Accepts\n`access_token` query param for browser-based auth (WebSocket API cannot\nsend custom headers). Streams raw PTY output as binary frames and accepts\nJSON control frames for input, resize, and close.", "operationId": "get_v1_process_terminal_ws", "parameters": [ { "name": "id", "in": "path", "description": "Process ID", "required": true, "schema": { "type": "string" } }, { "name": "access_token", "in": "query", "description": "Bearer token alternative for WS auth", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "101": { "description": "WebSocket upgraded" }, "400": { "description": "Invalid websocket frame or upgrade request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Not a terminal process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Process API unsupported on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "AcpEnvelope": { "type": "object", "required": ["jsonrpc"], "properties": { "error": { "nullable": true }, "id": { "nullable": true }, "jsonrpc": { "type": "string" }, "method": { "type": "string", "nullable": true }, "params": { "nullable": true }, "result": { "nullable": true } } }, "AcpPostQuery": { "type": "object", "properties": { "agent": { "type": "string", "nullable": true } } }, "AcpServerInfo": { "type": "object", "required": ["serverId", "agent", "createdAtMs"], "properties": { "agent": { "type": "string" }, "createdAtMs": { "type": "integer", "format": "int64" }, "serverId": { "type": "string" } } }, "AcpServerListResponse": { "type": "object", "required": ["servers"], "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/AcpServerInfo" } } } }, "AgentCapabilities": { "type": "object", "required": [ "planMode", "permissions", "questions", "toolCalls", "toolResults", "textMessages", "images", "fileAttachments", "sessionLifecycle", "errorEvents", "reasoning", "status", "commandExecution", "fileChanges", "mcpTools", "streamingDeltas", "itemStarted", "sharedProcess" ], "properties": { "commandExecution": { "type": "boolean" }, "errorEvents": { "type": "boolean" }, "fileAttachments": { "type": "boolean" }, "fileChanges": { "type": "boolean" }, "images": { "type": "boolean" }, "itemStarted": { "type": "boolean" }, "mcpTools": { "type": "boolean" }, "permissions": { "type": "boolean" }, "planMode": { "type": "boolean" }, "questions": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "sessionLifecycle": { "type": "boolean" }, "sharedProcess": { "type": "boolean" }, "status": { "type": "boolean" }, "streamingDeltas": { "type": "boolean" }, "textMessages": { "type": "boolean" }, "toolCalls": { "type": "boolean" }, "toolResults": { "type": "boolean" } } }, "AgentInfo": { "type": "object", "required": ["id", "installed", "credentialsAvailable", "capabilities"], "properties": { "capabilities": { "$ref": "#/components/schemas/AgentCapabilities" }, "configError": { "type": "string", "nullable": true }, "configOptions": { "type": "array", "items": {}, "nullable": true }, "credentialsAvailable": { "type": "boolean" }, "id": { "type": "string" }, "installed": { "type": "boolean" }, "path": { "type": "string", "nullable": true }, "serverStatus": { "allOf": [ { "$ref": "#/components/schemas/ServerStatusInfo" } ], "nullable": true }, "version": { "type": "string", "nullable": true } } }, "AgentInstallArtifact": { "type": "object", "required": ["kind", "path", "source"], "properties": { "kind": { "type": "string" }, "path": { "type": "string" }, "source": { "type": "string" }, "version": { "type": "string", "nullable": true } } }, "AgentInstallRequest": { "type": "object", "properties": { "agentProcessVersion": { "type": "string", "nullable": true }, "agentVersion": { "type": "string", "nullable": true }, "reinstall": { "type": "boolean", "nullable": true } } }, "AgentInstallResponse": { "type": "object", "required": ["already_installed", "artifacts"], "properties": { "already_installed": { "type": "boolean" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstallArtifact" } } } }, "AgentListResponse": { "type": "object", "required": ["agents"], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInfo" } } } }, "DesktopActionResponse": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } } }, "DesktopClipboardQuery": { "type": "object", "properties": { "selection": { "type": "string", "nullable": true } } }, "DesktopClipboardResponse": { "type": "object", "required": ["text", "selection"], "properties": { "selection": { "type": "string" }, "text": { "type": "string" } } }, "DesktopClipboardWriteRequest": { "type": "object", "required": ["text"], "properties": { "selection": { "type": "string", "nullable": true }, "text": { "type": "string" } } }, "DesktopDisplayInfoResponse": { "type": "object", "required": ["display", "resolution"], "properties": { "display": { "type": "string" }, "resolution": { "$ref": "#/components/schemas/DesktopResolution" } } }, "DesktopErrorInfo": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "DesktopKeyModifiers": { "type": "object", "properties": { "alt": { "type": "boolean", "nullable": true }, "cmd": { "type": "boolean", "nullable": true }, "ctrl": { "type": "boolean", "nullable": true }, "shift": { "type": "boolean", "nullable": true } } }, "DesktopKeyboardDownRequest": { "type": "object", "required": ["key"], "properties": { "key": { "type": "string" } } }, "DesktopKeyboardPressRequest": { "type": "object", "required": ["key"], "properties": { "key": { "type": "string" }, "modifiers": { "allOf": [ { "$ref": "#/components/schemas/DesktopKeyModifiers" } ], "nullable": true } } }, "DesktopKeyboardTypeRequest": { "type": "object", "required": ["text"], "properties": { "delayMs": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "text": { "type": "string" } } }, "DesktopKeyboardUpRequest": { "type": "object", "required": ["key"], "properties": { "key": { "type": "string" } } }, "DesktopLaunchRequest": { "type": "object", "required": ["app"], "properties": { "app": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" }, "nullable": true }, "wait": { "type": "boolean", "nullable": true } } }, "DesktopLaunchResponse": { "type": "object", "required": ["processId"], "properties": { "pid": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "processId": { "type": "string" }, "windowId": { "type": "string", "nullable": true } } }, "DesktopMouseButton": { "type": "string", "enum": ["left", "middle", "right"] }, "DesktopMouseClickRequest": { "type": "object", "required": ["x", "y"], "properties": { "button": { "allOf": [ { "$ref": "#/components/schemas/DesktopMouseButton" } ], "nullable": true }, "clickCount": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopMouseDownRequest": { "type": "object", "properties": { "button": { "allOf": [ { "$ref": "#/components/schemas/DesktopMouseButton" } ], "nullable": true }, "x": { "type": "integer", "format": "int32", "nullable": true }, "y": { "type": "integer", "format": "int32", "nullable": true } } }, "DesktopMouseDragRequest": { "type": "object", "required": ["startX", "startY", "endX", "endY"], "properties": { "button": { "allOf": [ { "$ref": "#/components/schemas/DesktopMouseButton" } ], "nullable": true }, "endX": { "type": "integer", "format": "int32" }, "endY": { "type": "integer", "format": "int32" }, "startX": { "type": "integer", "format": "int32" }, "startY": { "type": "integer", "format": "int32" } } }, "DesktopMouseMoveRequest": { "type": "object", "required": ["x", "y"], "properties": { "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopMousePositionResponse": { "type": "object", "required": ["x", "y"], "properties": { "screen": { "type": "integer", "format": "int32", "nullable": true }, "window": { "type": "string", "nullable": true }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopMouseScrollRequest": { "type": "object", "required": ["x", "y"], "properties": { "deltaX": { "type": "integer", "format": "int32", "nullable": true }, "deltaY": { "type": "integer", "format": "int32", "nullable": true }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopMouseUpRequest": { "type": "object", "properties": { "button": { "allOf": [ { "$ref": "#/components/schemas/DesktopMouseButton" } ], "nullable": true }, "x": { "type": "integer", "format": "int32", "nullable": true }, "y": { "type": "integer", "format": "int32", "nullable": true } } }, "DesktopOpenRequest": { "type": "object", "required": ["target"], "properties": { "target": { "type": "string" } } }, "DesktopOpenResponse": { "type": "object", "required": ["processId"], "properties": { "pid": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "processId": { "type": "string" } } }, "DesktopProcessInfo": { "type": "object", "required": ["name", "running"], "properties": { "logPath": { "type": "string", "nullable": true }, "name": { "type": "string" }, "pid": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "running": { "type": "boolean" } } }, "DesktopRecordingInfo": { "type": "object", "required": ["id", "status", "fileName", "bytes", "startedAt"], "properties": { "bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "endedAt": { "type": "string", "nullable": true }, "fileName": { "type": "string" }, "id": { "type": "string" }, "processId": { "type": "string", "nullable": true }, "startedAt": { "type": "string" }, "status": { "$ref": "#/components/schemas/DesktopRecordingStatus" } } }, "DesktopRecordingListResponse": { "type": "object", "required": ["recordings"], "properties": { "recordings": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopRecordingInfo" } } } }, "DesktopRecordingStartRequest": { "type": "object", "properties": { "fps": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } }, "DesktopRecordingStatus": { "type": "string", "enum": ["recording", "completed", "failed"] }, "DesktopRegionScreenshotQuery": { "type": "object", "required": ["x", "y", "width", "height"], "properties": { "format": { "allOf": [ { "$ref": "#/components/schemas/DesktopScreenshotFormat" } ], "nullable": true }, "height": { "type": "integer", "format": "int32", "minimum": 0 }, "quality": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "scale": { "type": "number", "format": "float", "nullable": true }, "showCursor": { "type": "boolean", "nullable": true }, "width": { "type": "integer", "format": "int32", "minimum": 0 }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopResolution": { "type": "object", "required": ["width", "height"], "properties": { "dpi": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "height": { "type": "integer", "format": "int32", "minimum": 0 }, "width": { "type": "integer", "format": "int32", "minimum": 0 } } }, "DesktopScreenshotFormat": { "type": "string", "enum": ["png", "jpeg", "webp"] }, "DesktopScreenshotQuery": { "type": "object", "properties": { "format": { "allOf": [ { "$ref": "#/components/schemas/DesktopScreenshotFormat" } ], "nullable": true }, "quality": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "scale": { "type": "number", "format": "float", "nullable": true }, "showCursor": { "type": "boolean", "nullable": true } } }, "DesktopStartRequest": { "type": "object", "properties": { "displayNum": { "type": "integer", "format": "int32", "nullable": true }, "dpi": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "height": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "recordingFps": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "stateDir": { "type": "string", "nullable": true }, "streamAudioCodec": { "type": "string", "nullable": true }, "streamFrameRate": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "streamVideoCodec": { "type": "string", "nullable": true }, "webrtcPortRange": { "type": "string", "nullable": true }, "width": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } }, "DesktopState": { "type": "string", "enum": ["inactive", "install_required", "starting", "active", "stopping", "failed"] }, "DesktopStatusResponse": { "type": "object", "required": ["state"], "properties": { "display": { "type": "string", "nullable": true }, "installCommand": { "type": "string", "nullable": true }, "lastError": { "allOf": [ { "$ref": "#/components/schemas/DesktopErrorInfo" } ], "nullable": true }, "missingDependencies": { "type": "array", "items": { "type": "string" } }, "processes": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopProcessInfo" } }, "resolution": { "allOf": [ { "$ref": "#/components/schemas/DesktopResolution" } ], "nullable": true }, "runtimeLogPath": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "nullable": true }, "state": { "$ref": "#/components/schemas/DesktopState" }, "windows": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopWindowInfo" }, "description": "Current visible windows (included when the desktop is active)." } } }, "DesktopStreamStatusResponse": { "type": "object", "required": ["active"], "properties": { "active": { "type": "boolean" }, "processId": { "type": "string", "nullable": true }, "windowId": { "type": "string", "nullable": true } } }, "DesktopWindowInfo": { "type": "object", "required": ["id", "title", "x", "y", "width", "height", "isActive"], "properties": { "height": { "type": "integer", "format": "int32", "minimum": 0 }, "id": { "type": "string" }, "isActive": { "type": "boolean" }, "title": { "type": "string" }, "width": { "type": "integer", "format": "int32", "minimum": 0 }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopWindowListResponse": { "type": "object", "required": ["windows"], "properties": { "windows": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopWindowInfo" } } } }, "DesktopWindowMoveRequest": { "type": "object", "required": ["x", "y"], "properties": { "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" } } }, "DesktopWindowResizeRequest": { "type": "object", "required": ["width", "height"], "properties": { "height": { "type": "integer", "format": "int32", "minimum": 0 }, "width": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ErrorType": { "type": "string", "enum": [ "invalid_request", "conflict", "unsupported_agent", "agent_not_installed", "install_failed", "agent_process_exited", "token_invalid", "permission_denied", "not_acceptable", "unsupported_media_type", "not_found", "session_not_found", "session_already_exists", "mode_not_supported", "stream_error", "timeout" ] }, "FsActionResponse": { "type": "object", "required": ["path"], "properties": { "path": { "type": "string" } } }, "FsDeleteQuery": { "type": "object", "required": ["path"], "properties": { "path": { "type": "string" }, "recursive": { "type": "boolean", "nullable": true } } }, "FsEntriesQuery": { "type": "object", "properties": { "path": { "type": "string", "nullable": true } } }, "FsEntry": { "type": "object", "required": ["name", "path", "entryType", "size"], "properties": { "entryType": { "$ref": "#/components/schemas/FsEntryType" }, "modified": { "type": "string", "nullable": true }, "name": { "type": "string" }, "path": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "FsEntryType": { "type": "string", "enum": ["file", "directory"] }, "FsMoveRequest": { "type": "object", "required": ["from", "to"], "properties": { "from": { "type": "string" }, "overwrite": { "type": "boolean", "nullable": true }, "to": { "type": "string" } } }, "FsMoveResponse": { "type": "object", "required": ["from", "to"], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "FsPathQuery": { "type": "object", "required": ["path"], "properties": { "path": { "type": "string" } } }, "FsStat": { "type": "object", "required": ["path", "entryType", "size"], "properties": { "entryType": { "$ref": "#/components/schemas/FsEntryType" }, "modified": { "type": "string", "nullable": true }, "path": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "FsUploadBatchQuery": { "type": "object", "properties": { "path": { "type": "string", "nullable": true } } }, "FsUploadBatchResponse": { "type": "object", "required": ["paths", "truncated"], "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } } }, "FsWriteResponse": { "type": "object", "required": ["path", "bytesWritten"], "properties": { "bytesWritten": { "type": "integer", "format": "int64", "minimum": 0 }, "path": { "type": "string" } } }, "HealthResponse": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string" } } }, "McpConfigQuery": { "type": "object", "required": ["directory", "mcpName"], "properties": { "directory": { "type": "string" }, "mcpName": { "type": "string" } } }, "McpServerConfig": { "oneOf": [ { "type": "object", "required": ["command", "type"], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "$ref": "#/components/schemas/McpCommand" }, "cwd": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "nullable": true }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "timeoutMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "type": { "type": "string", "enum": ["local"] } } }, { "type": "object", "required": ["url", "type"], "properties": { "bearerTokenEnvVar": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "nullable": true }, "envHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "oauth": { "allOf": [ { "$ref": "#/components/schemas/McpOAuthConfigOrDisabled" } ], "nullable": true }, "timeoutMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "transport": { "allOf": [ { "$ref": "#/components/schemas/McpRemoteTransport" } ], "nullable": true }, "type": { "type": "string", "enum": ["remote"] }, "url": { "type": "string" } } } ], "discriminator": { "propertyName": "type" } }, "ProblemDetails": { "type": "object", "required": ["type", "title", "status"], "properties": { "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "minimum": 0 }, "title": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": {} }, "ProcessConfig": { "type": "object", "required": ["maxConcurrentProcesses", "defaultRunTimeoutMs", "maxRunTimeoutMs", "maxOutputBytes", "maxLogBytesPerProcess", "maxInputBytesPerRequest"], "properties": { "defaultRunTimeoutMs": { "type": "integer", "format": "int64", "minimum": 0 }, "maxConcurrentProcesses": { "type": "integer", "minimum": 0 }, "maxInputBytesPerRequest": { "type": "integer", "minimum": 0 }, "maxLogBytesPerProcess": { "type": "integer", "minimum": 0 }, "maxOutputBytes": { "type": "integer", "minimum": 0 }, "maxRunTimeoutMs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ProcessCreateRequest": { "type": "object", "required": ["command"], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "cwd": { "type": "string", "nullable": true }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "interactive": { "type": "boolean" }, "tty": { "type": "boolean" } } }, "ProcessInfo": { "type": "object", "required": ["id", "command", "args", "tty", "interactive", "owner", "status", "createdAtMs"], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "createdAtMs": { "type": "integer", "format": "int64" }, "cwd": { "type": "string", "nullable": true }, "exitCode": { "type": "integer", "format": "int32", "nullable": true }, "exitedAtMs": { "type": "integer", "format": "int64", "nullable": true }, "id": { "type": "string" }, "interactive": { "type": "boolean" }, "owner": { "$ref": "#/components/schemas/ProcessOwner" }, "pid": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "status": { "$ref": "#/components/schemas/ProcessState" }, "tty": { "type": "boolean" } } }, "ProcessInputRequest": { "type": "object", "required": ["data"], "properties": { "data": { "type": "string" }, "encoding": { "type": "string", "nullable": true } } }, "ProcessInputResponse": { "type": "object", "required": ["bytesWritten"], "properties": { "bytesWritten": { "type": "integer", "minimum": 0 } } }, "ProcessListQuery": { "type": "object", "properties": { "owner": { "allOf": [ { "$ref": "#/components/schemas/ProcessOwner" } ], "nullable": true } } }, "ProcessListResponse": { "type": "object", "required": ["processes"], "properties": { "processes": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessInfo" } } } }, "ProcessLogEntry": { "type": "object", "required": ["sequence", "stream", "timestampMs", "data", "encoding"], "properties": { "data": { "type": "string" }, "encoding": { "type": "string" }, "sequence": { "type": "integer", "format": "int64", "minimum": 0 }, "stream": { "$ref": "#/components/schemas/ProcessLogsStream" }, "timestampMs": { "type": "integer", "format": "int64" } } }, "ProcessLogsQuery": { "type": "object", "properties": { "follow": { "type": "boolean", "nullable": true }, "since": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "stream": { "allOf": [ { "$ref": "#/components/schemas/ProcessLogsStream" } ], "nullable": true }, "tail": { "type": "integer", "nullable": true, "minimum": 0 } } }, "ProcessLogsResponse": { "type": "object", "required": ["processId", "stream", "entries"], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessLogEntry" } }, "processId": { "type": "string" }, "stream": { "$ref": "#/components/schemas/ProcessLogsStream" } } }, "ProcessLogsStream": { "type": "string", "enum": ["stdout", "stderr", "combined", "pty"] }, "ProcessOwner": { "type": "string", "enum": ["user", "desktop", "system"] }, "ProcessRunRequest": { "type": "object", "required": ["command"], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "cwd": { "type": "string", "nullable": true }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "maxOutputBytes": { "type": "integer", "nullable": true, "minimum": 0 }, "timeoutMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } }, "ProcessRunResponse": { "type": "object", "required": ["timedOut", "stdout", "stderr", "stdoutTruncated", "stderrTruncated", "durationMs"], "properties": { "durationMs": { "type": "integer", "format": "int64", "minimum": 0 }, "exitCode": { "type": "integer", "format": "int32", "nullable": true }, "stderr": { "type": "string" }, "stderrTruncated": { "type": "boolean" }, "stdout": { "type": "string" }, "stdoutTruncated": { "type": "boolean" }, "timedOut": { "type": "boolean" } } }, "ProcessSignalQuery": { "type": "object", "properties": { "waitMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } }, "ProcessState": { "type": "string", "enum": ["running", "exited"] }, "ProcessTerminalResizeRequest": { "type": "object", "required": ["cols", "rows"], "properties": { "cols": { "type": "integer", "format": "int32", "minimum": 0 }, "rows": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ProcessTerminalResizeResponse": { "type": "object", "required": ["cols", "rows"], "properties": { "cols": { "type": "integer", "format": "int32", "minimum": 0 }, "rows": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ServerStatus": { "type": "string", "enum": ["running", "stopped"] }, "ServerStatusInfo": { "type": "object", "required": ["status"], "properties": { "status": { "$ref": "#/components/schemas/ServerStatus" }, "uptimeMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } }, "SkillSource": { "type": "object", "required": ["type", "source"], "properties": { "ref": { "type": "string", "nullable": true }, "skills": { "type": "array", "items": { "type": "string" }, "nullable": true }, "source": { "type": "string" }, "subpath": { "type": "string", "nullable": true }, "type": { "type": "string" } } }, "SkillsConfig": { "type": "object", "required": ["sources"], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSource" } } } }, "SkillsConfigQuery": { "type": "object", "required": ["directory", "skillName"], "properties": { "directory": { "type": "string" }, "skillName": { "type": "string" } } }, "McpCommand": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "McpRemoteTransport": { "type": "string", "enum": ["http", "sse"] }, "McpOAuthConfig": { "type": "object", "properties": { "clientId": { "type": "string", "nullable": true }, "clientSecret": { "type": "string", "nullable": true }, "scope": { "type": "string", "nullable": true } } }, "McpOAuthConfigOrDisabled": { "oneOf": [ { "$ref": "#/components/schemas/McpOAuthConfig" }, { "type": "boolean" } ] } } }, "tags": [ { "name": "v1", "description": "ACP proxy v1 API" } ] }