{ "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.2.1" }, "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/fs/download-batch": { "get": { "tags": [ "v1" ], "summary": "Download a tar archive of a file or directory.", "description": "Returns `application/x-tar` bytes containing the requested path. If the path is a directory,\nthe archive contains its contents (similar to `tar -C .`).", "operationId": "get_v1_fs_download_batch", "parameters": [ { "name": "path", "in": "query", "description": "Source path (file or directory)", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "tar archive bytes" } } } }, "/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" } } } } } } } }, "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" } } } }, "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", "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 } } }, "FsDownloadBatchQuery": { "type": "object", "properties": { "path": { "type": "string", "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": {} }, "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" } } } } }, "tags": [ { "name": "v1", "description": "ACP proxy v1 API" } ] }