From 8edb9b251e7a2507643064e974be25f8c072cd5b Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Mon, 31 Aug 2026 23:28:00 +0300 Subject: [PATCH 1/8] fix(reference): enforce public contract boundaries --- reference/manifest.json | 30 +- reference/openapi/control-plane.yml | 499 ------------------ reference/openapi/envd.yml | 39 -- .../code-interpreter/classes/Sandbox.md | 166 ------ .../commands/interfaces/Commands.md | 6 - .../sdk/javascript/sandbox/classes/Sandbox.md | 126 ----- .../sandbox/interfaces/CreateSnapshotOpts.md | 18 - .../sandbox/interfaces/SandboxApiOpts.md | 18 - .../sandbox/interfaces/SandboxForkOpts.md | 54 -- .../sandbox/interfaces/SandboxListOpts.md | 18 - .../sandbox/interfaces/SandboxMetricsOpts.md | 18 - .../sandbox/interfaces/SandboxOpts.md | 36 -- .../sandbox/interfaces/SandboxPaginator.md | 44 -- .../sandbox/interfaces/SandboxPauseOpts.md | 18 - .../sandbox/interfaces/SnapshotListOpts.md | 18 - .../sandbox/interfaces/SnapshotPaginator.md | 44 -- scripts/generate-reference.py | 3 + scripts/public_openapi.py | 67 +++ scripts/test-reference-contract.py | 60 +++ 19 files changed, 145 insertions(+), 1137 deletions(-) diff --git a/reference/manifest.json b/reference/manifest.json index 7fae5cb3..bc51bf38 100644 --- a/reference/manifest.json +++ b/reference/manifest.json @@ -2,8 +2,8 @@ "files": { "connect/filesystem.md": "1cc1e81386810d3c5c999458e02340e3becb3da8138d943558584094750e5aae", "connect/process.md": "037574455e9e8c5159c391d8c007e7272560f62c4e5ee681f8aec29f9cd24539", - "openapi/control-plane.yml": "f3009ea28f824b61092142caf527a062f59c791bc760a7810a4fb9dec8226a29", - "openapi/envd.yml": "83bc85bf7b4084105ac9ffeec708d04d0e14ab275026d616c30de31caea62589", + "openapi/control-plane.yml": "99e42c340a18ac1f3bda9321d347b01f6bd8326c39373e92797bfb179ee0a0bf", + "openapi/envd.yml": "c8cb85cbdcfb0ae4ed55a3a0cd6f58b17a23b14bfe74be904a160e770c6e91c3", "openapi/markdown/assignTemplateTags.md": "3ec3dc705cbda5780d0a9e78234c7777f014784b2ec193821b6f5bb2ea26ec57", "openapi/markdown/composeFiles.md": "3e5c37b40268689b6e5287a906c75b80f71fefafe94205c6327c976ca0594d5c", "openapi/markdown/connectSandbox.md": "9106d09a6f525aa0bcbd1eed06de62a4d015d1f6fa63496ccb6aebbebb3ad332", @@ -45,7 +45,7 @@ "sdk/cli/sandbox.md": "16b64c5a4e932eca2452e400e0faf154eba1d3c7373513aa7cd9744e02908313", "sdk/cli/template.md": "f270b22b9ee10a9b954a14f24e04c5449b4d5823bb28002ffde3ed682594cfc5", "sdk/javascript/code-interpreter/README.md": "a787206eb86f81fc306b373ce20bc6c91464b0ab3c3ec7650eccbb6be5f676c5", - "sdk/javascript/code-interpreter/classes/Sandbox.md": "0c380df735431ad98397ec32920159e4c6ba103e600603551ded77b2f472839a", + "sdk/javascript/code-interpreter/classes/Sandbox.md": "1f69d878e794b39c0ef2efd0770cb7385efb2795c5ff971622fd93f6e80030f3", "sdk/javascript/code-interpreter/enumerations/ChartType.md": "cf1ba00cd3258cc88814b7215e101b0d775ceb15dd833636d58ae538d8107ec1", "sdk/javascript/code-interpreter/enumerations/ScaleType.md": "8cf4764b2c7844578b492dc0126d4ca13bb11d3c93accb28369ea24b3be8c0a1", "sdk/javascript/code-interpreter/interfaces/CreateCodeContextOpts.md": "dccfd965ed1aaac775e2202db7779526ae5227b17757ab5e69933e7e900140ae", @@ -77,7 +77,7 @@ "sdk/javascript/commands/interfaces/CommandRequestOpts.md": "cafa91c729e7844793dc968f0c253e64f1f6c5b311e41e11b09f9ecb08e2e88b", "sdk/javascript/commands/interfaces/CommandResult.md": "eab8e374efe1042d89052d6535ec148f0fa45b7a42056bbf1f5f37d350910cab", "sdk/javascript/commands/interfaces/CommandStartOpts.md": "94b6b7b977696e8b013d09f545ccac254e46fd6b5ec2001ed5064579afdcc57e", - "sdk/javascript/commands/interfaces/Commands.md": "782a83ddcef47090d0d5dd5b237340c88c664730c3d58b12f79ba0027ca2bdbf", + "sdk/javascript/commands/interfaces/Commands.md": "abf7dee4fc2d5f7b0422d677115a3dd01418d2e29afc34eb22c2cee548de13a8", "sdk/javascript/commands/interfaces/ProcessInfo.md": "f3b3be4d6a94eb18df59ed226e689175e62d92cc4c708013f73799e63985319c", "sdk/javascript/commands/interfaces/Pty.md": "85962c5e714c73d23c38e64ee4936ecc945243d6c77f5fa6d9d790a2aaef56d8", "sdk/javascript/commands/type-aliases/CommandConnectOpts.md": "831b9eaee3a26e90a5d7f9003a66ce334a4ef650928846428b54d0309efa0893", @@ -122,23 +122,23 @@ "sdk/javascript/ready-commands/functions/waitForURL.md": "6d48c23ab42a46435af442d89652554b3972146db19f125ff77c7b03e91b744f", "sdk/javascript/sandbox/README.md": "4835e9b776ae1006374372fdb374e29a3dd46380b610f374f2d88c3e9f495780", "sdk/javascript/sandbox/classes/AgentBox.md": "eda95be473aab89d16d341ec9accf1d9afcae8b28c9cf3bb0783ef22241f0354", - "sdk/javascript/sandbox/classes/Sandbox.md": "3d3a29fb8c861829b0ceede40264ef1a1da8ba94134c6e13e3e4b740d7d11e03", - "sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md": "31969a24a0233a15b29dd5a4a3455d1afa7898c7db8b121ab00889df3b014dc7", + "sdk/javascript/sandbox/classes/Sandbox.md": "fbf027c2ed827cf399f4406516c006f53911ac916c86deb5efdbfaec2db56d40", + "sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md": "0499c857c4836c39450268facfa1c53ffee70dcb4447b15a85edc095a2e69d0d", "sdk/javascript/sandbox/interfaces/McpServer.md": "80c715da37c6508052faed9f6c1ff5c96c92ddcf75dd1855dbf3e98b4217565d", - "sdk/javascript/sandbox/interfaces/SandboxApiOpts.md": "7d848b9c877ffb64855be04a5dcd3e3272186b69bb8d451bd7e37c2c69ae2647", - "sdk/javascript/sandbox/interfaces/SandboxForkOpts.md": "2b7f29dc36c0776fff31ca30bae8dd2da7c26e15e9956993cbf358b439b8d6de", + "sdk/javascript/sandbox/interfaces/SandboxApiOpts.md": "4276fd99536e8545f79fd12bbd479c7aa793a692fb4fe74b4df4f16e1eae0b98", + "sdk/javascript/sandbox/interfaces/SandboxForkOpts.md": "207cd816aa1725ce377ca5a3e56044c087a68aa81921cfdf5168bbad72c3218c", "sdk/javascript/sandbox/interfaces/SandboxIamOpts.md": "b0676dff6384475115b24f890d576020db5437b2539b1d1b34da8991ad85a3da", "sdk/javascript/sandbox/interfaces/SandboxIamToken.md": "8824bf3a069f681e39de27443c097595b3214111b0df3e10be613ee380841119", "sdk/javascript/sandbox/interfaces/SandboxInfo.md": "6512df3dc84cd5cf25122b2238f11c7391ac137faa8ae0cbd353e8d5d14da7b1", - "sdk/javascript/sandbox/interfaces/SandboxListOpts.md": "486f810b0127d72ab47928c487e9d73c9ad60dc41fd48539cfad0edd79edae07", + "sdk/javascript/sandbox/interfaces/SandboxListOpts.md": "887d28b99920a0230b582a35614f37365b3cbd715ee1f19c920d943b806383fe", "sdk/javascript/sandbox/interfaces/SandboxMetrics.md": "4e7b66fee2d60e552c193956efca47cb16fa4696800e0434209517099f83852b", - "sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md": "dbdf9c20c43aa1cfc608e32eb750cb010c637216616456a4109e0e4bbf6f3392", - "sdk/javascript/sandbox/interfaces/SandboxOpts.md": "5f948d29a09cf6a0a9adc92c51a4713ed3ca74edb2c63d8c91ad7891f12c7d1d", - "sdk/javascript/sandbox/interfaces/SandboxPaginator.md": "31e1b349de4638b1eada4a0dd23c3e0f7dbaca6d405b2ff29d00967950e08dba", - "sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md": "6759c87eedd7cb2333636aa8f7c05844aae8a14deb8f82e336aa6b4086e5e4f8", + "sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md": "54491a944b5c270e0648da4f29f48fa7b2b81d03892bd3c3d06d738ae39648ce", + "sdk/javascript/sandbox/interfaces/SandboxOpts.md": "0c5421aa90299319a702fe55323cf46920243c1d52d377a612f3b91b25962534", + "sdk/javascript/sandbox/interfaces/SandboxPaginator.md": "ced3c79f2cf1a52fcbaafea1f874a603dea7c8b3b11d6fea89873dc2e8aec438", + "sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md": "bd9ec9066cb5651041399ba43e5f7b69fa121dab2809807f1ffe572eab9825d1", "sdk/javascript/sandbox/interfaces/SnapshotInfo.md": "d54e8ee99f1fb9e1d43372b35ce42927cd33e9e21086d69f25e2ae1c6b9ec8c3", - "sdk/javascript/sandbox/interfaces/SnapshotListOpts.md": "631e3cf2bc3e9d402f8df4dd592e76d95549726b4dd307677dddfb606ff39dd6", - "sdk/javascript/sandbox/interfaces/SnapshotPaginator.md": "664425f9ee81f71adc63793fffdf505343352bbb1137f7d78271494b46dedfb1", + "sdk/javascript/sandbox/interfaces/SnapshotListOpts.md": "67a3e876779679fa91fb98f5678fc4a6e97c3c6605cef948d3c47ba06e756d91", + "sdk/javascript/sandbox/interfaces/SnapshotPaginator.md": "965ac1e0f6396d346f1a0e814bcf77902cecccd2bba651e08946fd499aa87158", "sdk/javascript/sandbox/type-aliases/AgentBoxClientOpts.md": "64aec729e35ec0814bc3301666d14642f18394a12f4aa238beccbb6315a35895", "sdk/javascript/sandbox/type-aliases/SandboxConnectOpts.md": "ae66e94fd6480eb211aa49bff925d5f9d01fb9536fba3ce6615975906fc4bdf3", "sdk/javascript/sandbox/type-aliases/SandboxIamTokenType.md": "1f575132918286ee1cbca5c0e3a223accd0fe00d28ccf031cf8e736b088d7e5b", diff --git a/reference/openapi/control-plane.yml b/reference/openapi/control-plane.yml index f31a0adb..80481e01 100644 --- a/reference/openapi/control-plane.yml +++ b/reference/openapi/control-plane.yml @@ -6,15 +6,6 @@ servers: - url: https://api.agentbox-runtime.ru components: parameters: - idempotencyKey: - name: Idempotency-Key - in: header - required: true - description: Stable operation identity. Reusing it with different input is rejected. - schema: - type: string - minLength: 1 - maxLength: 255 templateID: name: templateID in: path @@ -39,38 +30,6 @@ components: required: true schema: type: string - nodeID: - name: nodeID - in: path - required: true - schema: - type: string - apiKeyID: - name: apiKeyID - in: path - required: true - schema: - type: string - accessTokenID: - name: accessTokenID - in: path - required: true - schema: - type: string - snapshotID: - name: snapshotID - in: path - required: true - schema: - type: string - description: Identifier of the snapshot (template ID) - tag: - name: tag - in: path - required: true - schema: - type: string - description: Tag name paginationLimit: name: limit in: query @@ -89,12 +48,6 @@ components: required: false schema: type: string - volumeID: - name: volumeID - in: path - required: true - schema: - type: string headers: XNextToken: description: Cursor to fetch the next page of results, if more exist @@ -139,12 +92,6 @@ components: application/json: schema: $ref: '#/components/schemas/Error' - '410': - description: Gone - content: - application/json: - schema: - $ref: '#/components/schemas/Error' '500': description: Server error content: @@ -152,25 +99,6 @@ components: schema: $ref: '#/components/schemas/Error' schemas: - Team: - required: - - teamID - - name - - apiKey - - isDefault - properties: - teamID: - type: string - description: Identifier of the team - name: - type: string - description: Name of the team - apiKey: - type: string - description: API key for the team - isDefault: - type: boolean - description: Whether the team is the default team TeamUser: required: - id @@ -365,19 +293,6 @@ components: description: Whether the sandbox can auto-resume. onTimeout: $ref: '#/components/schemas/SandboxOnTimeout' - SandboxLog: - description: Log entry with timestamp and line - required: - - timestamp - - line - properties: - timestamp: - type: string - format: date-time - description: Timestamp of the log entry - line: - type: string - description: Log line content SandboxLogEntry: required: - timestamp @@ -401,21 +316,6 @@ components: type: object additionalProperties: type: string - SandboxLogs: - required: - - logs - - logEntries - properties: - logs: - description: Logs of the sandbox - type: array - items: - $ref: '#/components/schemas/SandboxLog' - logEntries: - description: Structured logs of the sandbox - type: array - items: - $ref: '#/components/schemas/SandboxLogEntry' SandboxLogsV2Response: required: - logs @@ -667,14 +567,6 @@ components: tokenType: type: string description: Workload token type. - ResumedSandbox: - properties: - timeout: - type: integer - format: int32 - minimum: 0 - default: 15 - description: Time to live for the sandbox in seconds. ConnectSandbox: type: object required: @@ -786,28 +678,6 @@ components: value: type: number description: The maximum value of the requested metric in the given interval - AdminSandboxKillResult: - required: - - killedCount - - failedCount - properties: - killedCount: - type: integer - description: Number of sandboxes successfully killed - failedCount: - type: integer - description: Number of sandboxes that failed to kill - AdminBuildCancelResult: - required: - - cancelledCount - - failedCount - properties: - cancelledCount: - type: integer - description: Number of builds successfully cancelled - failedCount: - type: integer - description: Number of builds that failed to cancel Template: required: - templateID @@ -992,29 +862,6 @@ components: public: type: boolean description: Whether the template is public or only accessible by the team - TemplateBuildRequest: - required: - - dockerfile - properties: - alias: - description: Alias of the template - type: string - dockerfile: - description: Dockerfile for the template - type: string - teamID: - type: string - description: Identifier of the team - startCmd: - description: Start command to execute in the template after the build - type: string - readyCmd: - description: Ready check command to execute in the template after the build - type: string - cpuCount: - $ref: '#/components/schemas/CPUCount' - memoryMB: - $ref: '#/components/schemas/MemoryMB' TemplateStep: description: Step in the template build process required: @@ -1054,17 +901,6 @@ components: $ref: '#/components/schemas/CPUCount' memoryMB: $ref: '#/components/schemas/MemoryMB' - TemplateBuildRequestV2: - required: - - alias - properties: - alias: - description: Alias of the template - type: string - cpuCount: - $ref: '#/components/schemas/CPUCount' - memoryMB: - $ref: '#/components/schemas/MemoryMB' FromImageRegistry: oneOf: - $ref: '#/components/schemas/AWSRegistry' @@ -1280,322 +1116,6 @@ components: enum: - temporary - persistent - NodeStatus: - type: string - description: 'Status of the node. - - - draining: the node is bound to be shut down. It will not accept new sandboxes - and will stop once all existing sandboxes are done. - - - standby: the node is not actively used, but it can return to ready and continue - serving traffic. - - ' - enum: - - ready - - draining - - connecting - - unhealthy - - standby - NodeStatusChange: - required: - - status - properties: - clusterID: - type: string - format: uuid - description: Identifier of the cluster - status: - $ref: '#/components/schemas/NodeStatus' - DiskMetrics: - required: - - mountPoint - - device - - filesystemType - - usedBytes - - totalBytes - properties: - mountPoint: - type: string - description: Mount point of the disk - device: - type: string - description: Device name - filesystemType: - type: string - description: Filesystem type (e.g., ext4, xfs) - usedBytes: - type: integer - format: uint64 - description: Used space in bytes - totalBytes: - type: integer - format: uint64 - description: Total space in bytes - NodeMetrics: - description: Node metrics - required: - - allocatedCPU - - allocatedMemoryBytes - - cpuPercent - - memoryUsedBytes - - cpuCount - - memoryTotalBytes - - disks - - hugePagesTotal - - hugePagesUsed - - hugePagesReserved - - hugePageSizeBytes - properties: - allocatedCPU: - type: integer - format: uint32 - description: Number of allocated CPU cores - cpuPercent: - type: integer - format: uint32 - description: Node CPU usage percentage - cpuCount: - type: integer - format: uint32 - description: Total number of CPU cores on the node - allocatedMemoryBytes: - type: integer - format: uint64 - description: Amount of allocated memory in bytes - memoryUsedBytes: - type: integer - format: uint64 - description: Node memory used in bytes - memoryTotalBytes: - type: integer - format: uint64 - description: Total node memory in bytes - hugePagesTotal: - type: integer - format: uint64 - description: Total number of preallocated hugepages on the node - hugePagesUsed: - type: integer - format: uint64 - description: Number of hugepages in use (total - free) - hugePagesReserved: - type: integer - format: uint64 - description: Number of reserved hugepages (committed but not yet faulted) - hugePageSizeBytes: - type: integer - format: uint64 - description: Size of a single hugepage in bytes - disks: - type: array - description: Detailed metrics for each disk/mount point - items: - $ref: '#/components/schemas/DiskMetrics' - MachineInfo: - required: - - cpuFamily - - cpuModel - - cpuModelName - - cpuArchitecture - properties: - cpuFamily: - type: string - description: CPU family of the node - cpuModel: - type: string - description: CPU model of the node - cpuModelName: - type: string - description: CPU model name of the node - cpuArchitecture: - type: string - description: CPU architecture of the node - Node: - required: - - id - - serviceInstanceID - - clusterID - - status - - statusChangedAt - - sandboxCount - - metrics - - createSuccesses - - createFails - - sandboxStartingCount - - version - - commit - - machineInfo - properties: - version: - type: string - description: Version of the orchestrator - commit: - type: string - description: Commit of the orchestrator - id: - type: string - description: Identifier of the node - serviceInstanceID: - type: string - description: Service instance identifier of the node - clusterID: - type: string - description: Identifier of the cluster - machineInfo: - $ref: '#/components/schemas/MachineInfo' - status: - $ref: '#/components/schemas/NodeStatus' - statusChangedAt: - type: string - format: date-time - description: Time when the node status was last changed - sandboxCount: - type: integer - format: uint32 - description: Number of sandboxes running on the node - metrics: - $ref: '#/components/schemas/NodeMetrics' - createSuccesses: - type: integer - format: uint64 - description: Number of sandbox create successes - createFails: - type: integer - format: uint64 - description: Number of sandbox create fails - sandboxStartingCount: - type: integer - format: int - description: Number of starting Sandboxes - NodeDetail: - required: - - id - - serviceInstanceID - - clusterID - - status - - statusChangedAt - - sandboxCount - - createSuccesses - - createFails - - version - - commit - - metrics - - machineInfo - properties: - clusterID: - type: string - description: Identifier of the cluster - version: - type: string - description: Version of the orchestrator - commit: - type: string - description: Commit of the orchestrator - id: - type: string - description: Identifier of the node - serviceInstanceID: - type: string - description: Service instance identifier of the node - machineInfo: - $ref: '#/components/schemas/MachineInfo' - status: - $ref: '#/components/schemas/NodeStatus' - statusChangedAt: - type: string - format: date-time - description: Time when the node status was last changed - sandboxCount: - type: integer - format: uint32 - description: Number of sandboxes running on the node - metrics: - $ref: '#/components/schemas/NodeMetrics' - createSuccesses: - type: integer - format: uint64 - description: Number of sandbox create successes - createFails: - type: integer - format: uint64 - description: Number of sandbox create fails - TeamAPIKey: - required: - - id - - name - - mask - - createdAt - properties: - id: - type: string - format: uuid - description: Identifier of the API key - name: - type: string - description: Name of the API key - mask: - $ref: '#/components/schemas/IdentifierMaskingDetails' - createdAt: - type: string - format: date-time - description: Timestamp of API key creation - createdBy: - allOf: - - $ref: '#/components/schemas/TeamUser' - nullable: true - lastUsed: - type: string - format: date-time - description: Last time this API key was used - nullable: true - CreatedTeamAPIKey: - required: - - id - - key - - mask - - name - - createdAt - properties: - id: - type: string - format: uuid - description: Identifier of the API key - key: - type: string - description: Raw value of the API key - mask: - $ref: '#/components/schemas/IdentifierMaskingDetails' - name: - type: string - description: Name of the API key - createdAt: - type: string - format: date-time - description: Timestamp of API key creation - createdBy: - allOf: - - $ref: '#/components/schemas/TeamUser' - nullable: true - lastUsed: - type: string - format: date-time - description: Last time this API key was used - nullable: true - NewTeamAPIKey: - required: - - name - properties: - name: - type: string - description: Name of the API key - UpdateTeamAPIKey: - required: - - name - properties: - name: - type: string - description: New name for the API key AssignedTemplateTags: required: - tags @@ -1665,25 +1185,6 @@ components: message: type: string description: Error - IdentifierMaskingDetails: - required: - - prefix - - valueLength - - maskedValuePrefix - - maskedValueSuffix - properties: - prefix: - type: string - description: Prefix that identifies the token or key type - valueLength: - type: integer - description: Length of the token or key - maskedValuePrefix: - type: string - description: Prefix used in masked version of the token or key - maskedValueSuffix: - type: string - description: Suffix used in masked version of the token or key securitySchemes: ApiKeyAuth: type: apiKey diff --git a/reference/openapi/envd.yml b/reference/openapi/envd.yml index ff1ae074..0228214f 100644 --- a/reference/openapi/envd.yml +++ b/reference/openapi/envd.yml @@ -377,31 +377,6 @@ components: disk_total: type: integer description: Total disk space in bytes - CollapseResult: - type: object - description: Per-call statistics from a heap collapse - properties: - regions: - type: integer - description: Anonymous read-write regions scanned - chunks: - type: integer - description: 2 MiB chunks attempted - collapsed: - type: integer - description: Chunks whose base pages were actually migrated into a new hugepage - (real work) - alreadyHuge: - type: integer - description: Chunks MADV_COLLAPSE accepted but were already hugepages (no - work) - skipped: - type: integer - description: Chunks that could not be collapsed (empty or ineligible) - elapsedMs: - type: integer - format: int64 - description: Wall-clock time spent collapsing, in milliseconds ComposeRequest: type: object required: @@ -419,20 +394,6 @@ components: username: type: string description: User for setting ownership and resolving relative paths - VolumeMount: - type: object - description: Volume mount configuration - additionalProperties: false - properties: - nfs_target: - type: string - description: Server target address - path: - type: string - description: Mount path inside the sandbox - required: - - nfs_target - - path securitySchemes: AccessTokenAuth: type: apiKey diff --git a/reference/sdk/javascript/code-interpreter/classes/Sandbox.md b/reference/sdk/javascript/code-interpreter/classes/Sandbox.md index 473d1f87..275ee94e 100644 --- a/reference/sdk/javascript/code-interpreter/classes/Sandbox.md +++ b/reference/sdk/javascript/code-interpreter/classes/Sandbox.md @@ -41,36 +41,6 @@ Module for running commands in the sandbox *** -### connectionConfig - -> `protected` `readonly` **connectionConfig**: `ConnectionConfig` - -#### Inherited from - -`BaseSandbox.connectionConfig` - -*** - -### envdAccessToken? - -> `protected` `readonly` `optional` **envdAccessToken?**: `string` - -#### Inherited from - -`BaseSandbox.envdAccessToken` - -*** - -### envdPort - -> `protected` `readonly` **envdPort**: `49983` = `49983` - -#### Inherited from - -`BaseSandbox.envdPort` - -*** - ### files > `readonly` **files**: `Filesystem` @@ -83,16 +53,6 @@ Module for interacting with the sandbox filesystem *** -### mcpPort - -> `protected` `readonly` **mcpPort**: `50005` = `50005` - -#### Inherited from - -`BaseSandbox.mcpPort` - -*** - ### pty > `readonly` **pty**: `Pty` @@ -139,48 +99,6 @@ Traffic access token for accessing sandbox services with restricted public traff `BaseSandbox.trafficAccessToken` -*** - -### defaultMcpTemplate - -> `protected` `readonly` `static` **defaultMcpTemplate**: `string` = `'mcp-gateway'` - -#### Inherited from - -`BaseSandbox.defaultMcpTemplate` - -*** - -### defaultSandboxTimeoutMs - -> `protected` `readonly` `static` **defaultSandboxTimeoutMs**: `300000` = `DEFAULT_SANDBOX_TIMEOUT_MS` - -#### Inherited from - -`BaseSandbox.defaultSandboxTimeoutMs` - -*** - -### defaultTemplate - -> `protected` `readonly` `static` **defaultTemplate**: `string` = `'code-interpreter-v1'` - -#### Overrides - -`BaseSandbox.defaultTemplate` - -## Accessors - -### jupyterUrl - -#### Get Signature - -> **get** `protected` **jupyterUrl**(): `string` - -##### Returns - -`string` - ## Methods ### connect() @@ -898,30 +816,6 @@ const sameSandbox = await Sandbox.connect(sandboxId) *** -### connectSandbox() - -> `protected` `static` **connectSandbox**(`sandboxId`, `opts?`): `Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Parameters - -##### sandboxId - -`string` - -##### opts? - -`SandboxConnectOpts` - -#### Returns - -`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Inherited from - -`BaseSandbox.connectSandbox` - -*** - ### create() #### Call Signature @@ -1020,34 +914,6 @@ Sandbox *** -### createSandbox() - -> `protected` `static` **createSandbox**(`template`, `timeoutMs`, `opts?`): `Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Parameters - -##### template - -`string` - -##### timeoutMs - -`number` - -##### opts? - -`SandboxOpts` - -#### Returns - -`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Inherited from - -`BaseSandbox.createSandbox` - -*** - ### createSnapshot() > `static` **createSnapshot**(`sandboxId`, `opts?`): `Promise`\<`SnapshotInfo`\> @@ -1180,38 +1046,6 @@ if (fork1 instanceof Sandbox) { *** -### forkSandbox() - -> `protected` `static` **forkSandbox**(`sandboxId`, `timeoutMs`, `count`, `opts?`): `Promise`\<`SandboxForkResponse`[]\> - -#### Parameters - -##### sandboxId - -`string` - -##### timeoutMs - -`number` - -##### count - -`number` - -##### opts? - -`SandboxApiOpts` - -#### Returns - -`Promise`\<`SandboxForkResponse`[]\> - -#### Inherited from - -`BaseSandbox.forkSandbox` - -*** - ### getInfo() > `static` **getInfo**(`sandboxId`, `opts?`): `Promise`\<`SandboxInfo`\> diff --git a/reference/sdk/javascript/commands/interfaces/Commands.md b/reference/sdk/javascript/commands/interfaces/Commands.md index 2a968c97..84802044 100644 --- a/reference/sdk/javascript/commands/interfaces/Commands.md +++ b/reference/sdk/javascript/commands/interfaces/Commands.md @@ -4,12 +4,6 @@ Module for starting and interacting with commands in the sandbox. -## Properties - -### rpc - -> `protected` `readonly` **rpc**: `Client`\<*typeof* `ProcessService`\> - ## Methods ### closeStdin() diff --git a/reference/sdk/javascript/sandbox/classes/Sandbox.md b/reference/sdk/javascript/sandbox/classes/Sandbox.md index cb9c40fe..0d319a19 100644 --- a/reference/sdk/javascript/sandbox/classes/Sandbox.md +++ b/reference/sdk/javascript/sandbox/classes/Sandbox.md @@ -37,24 +37,6 @@ Module for running commands in the sandbox *** -### connectionConfig - -> `protected` `readonly` **connectionConfig**: `ConnectionConfig` - -*** - -### envdAccessToken? - -> `protected` `readonly` `optional` **envdAccessToken?**: `string` - -*** - -### envdPort - -> `protected` `readonly` **envdPort**: `49983` = `49983` - -*** - ### files > `readonly` **files**: `Filesystem` @@ -63,12 +45,6 @@ Module for interacting with the sandbox filesystem *** -### mcpPort - -> `protected` `readonly` **mcpPort**: `50005` = `50005` - -*** - ### pty > `readonly` **pty**: `Pty` @@ -99,24 +75,6 @@ Unique identifier of the sandbox. Traffic access token for accessing sandbox services with restricted public traffic. -*** - -### defaultMcpTemplate - -> `protected` `readonly` `static` **defaultMcpTemplate**: `string` = `'mcp-gateway'` - -*** - -### defaultSandboxTimeoutMs - -> `protected` `readonly` `static` **defaultSandboxTimeoutMs**: `300000` = `DEFAULT_SANDBOX_TIMEOUT_MS` - -*** - -### defaultTemplate - -> `protected` `readonly` `static` **defaultTemplate**: `string` = `'base'` - ## Methods ### connect() @@ -621,30 +579,6 @@ const sameSandbox = await Sandbox.connect(sandboxId) *** -### connectSandbox() - -> `protected` `static` **connectSandbox**(`sandboxId`, `opts?`): `Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Parameters - -##### sandboxId - -`string` - -##### opts? - -[`SandboxConnectOpts`](../type-aliases/SandboxConnectOpts.md) - -#### Returns - -`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Inherited from - -`SandboxApi.connectSandbox` - -*** - ### create() #### Call Signature @@ -735,34 +669,6 @@ Sandbox *** -### createSandbox() - -> `protected` `static` **createSandbox**(`template`, `timeoutMs`, `opts?`): `Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Parameters - -##### template - -`string` - -##### timeoutMs - -`number` - -##### opts? - -[`SandboxOpts`](../interfaces/SandboxOpts.md) - -#### Returns - -`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> - -#### Inherited from - -`SandboxApi.createSandbox` - -*** - ### createSnapshot() > `static` **createSnapshot**(`sandboxId`, `opts?`): `Promise`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md)\> @@ -891,38 +797,6 @@ if (fork1 instanceof Sandbox) { *** -### forkSandbox() - -> `protected` `static` **forkSandbox**(`sandboxId`, `timeoutMs`, `count`, `opts?`): `Promise`\<`SandboxForkResponse`[]\> - -#### Parameters - -##### sandboxId - -`string` - -##### timeoutMs - -`number` - -##### count - -`number` - -##### opts? - -[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) - -#### Returns - -`Promise`\<`SandboxForkResponse`[]\> - -#### Inherited from - -`SandboxApi.forkSandbox` - -*** - ### getInfo() > `static` **getInfo**(`sandboxId`, `opts?`): `Promise`\<[`SandboxInfo`](../interfaces/SandboxInfo.md)\> diff --git a/reference/sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md b/reference/sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md index 83a01be6..e6304161 100644 --- a/reference/sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/CreateSnapshotOpts.md @@ -40,24 +40,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxApiOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxApiOpts.md index cf4e0f95..4888a6e1 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxApiOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxApiOpts.md @@ -46,24 +46,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxForkOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxForkOpts.md index 277433ce..475ebb4b 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxForkOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxForkOpts.md @@ -40,24 +40,6 @@ AGENTBOX_API_KEY // environment variable *** -### apiUrl? - -> `optional` **apiUrl?**: `string` - -**`Internal`** - -API Url to use for the API. - -#### Default - -AGENTBOX_API_URL // environment variable or `https://api.${domain}` - -#### Inherited from - -`ConnectionOpts.apiUrl` - -*** - ### count? > `optional` **count?**: `number` @@ -76,24 +58,6 @@ outcome of each is reported in its entry of the returned array. *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -`ConnectionOpts.debug` - -*** - ### domain? > `optional` **domain?**: `string` @@ -159,24 +123,6 @@ Timeout for requests to the API in **milliseconds**. *** -### sandboxUrl? - -> `optional` **sandboxUrl?**: `string` - -**`Internal`** - -Sandbox Url to use for the API. - -#### Default - -AGENTBOX_SANDBOX_URL // environment variable, `https://sandbox.${domain}` - -#### Inherited from - -`ConnectionOpts.sandboxUrl` - -*** - ### signal? > `optional` **signal?**: `AbortSignal` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxListOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxListOpts.md index b97f2ec1..efadc0e8 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxListOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxListOpts.md @@ -38,24 +38,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md index 96504b41..abe001e6 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxMetricsOpts.md @@ -40,24 +40,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxOpts.md index b16a25af..6566b864 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxOpts.md @@ -54,42 +54,6 @@ AGENTBOX_API_KEY // environment variable *** -### apiUrl? - -> `optional` **apiUrl?**: `string` - -**`Internal`** - -API Url to use for the API. - -#### Default - -AGENTBOX_API_URL // environment variable or `https://api.${domain}` - -#### Inherited from - -`ConnectionOpts.apiUrl` - -*** - -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -`ConnectionOpts.debug` - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxPaginator.md b/reference/sdk/javascript/sandbox/interfaces/SandboxPaginator.md index dd8bb5df..58f7a673 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxPaginator.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxPaginator.md @@ -18,26 +18,6 @@ while (paginator.hasNext) { - `Paginator`\<[`SandboxInfo`](SandboxInfo.md), [`SandboxApiOpts`](SandboxApiOpts.md)\> -## Properties - -### limit? - -> `protected` `readonly` `optional` **limit?**: `number` - -#### Inherited from - -`Paginator.limit` - -*** - -### opts? - -> `protected` `readonly` `optional` **opts?**: [`SandboxApiOpts`](SandboxApiOpts.md) - -#### Inherited from - -`Paginator.opts` - ## Accessors ### hasNext @@ -107,27 +87,3 @@ Error if there are no more items to fetch. Call this method only if `hasNext` is #### Overrides `Paginator.nextItems` - -*** - -### updatePagination() - -> `protected` **updatePagination**(`response`): `void` - -Update the pagination state from a response, reading the `x-next-token` -header. Concrete paginators call this from Paginator.nextItems -after fetching a page. - -#### Parameters - -##### response - -`Response` - -#### Returns - -`void` - -#### Inherited from - -`Paginator.updatePagination` diff --git a/reference/sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md b/reference/sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md index 4508c1a4..eddd045e 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SandboxPauseOpts.md @@ -40,24 +40,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SnapshotListOpts.md b/reference/sdk/javascript/sandbox/interfaces/SnapshotListOpts.md index a0eb4cbe..9e58cceb 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SnapshotListOpts.md +++ b/reference/sdk/javascript/sandbox/interfaces/SnapshotListOpts.md @@ -40,24 +40,6 @@ AGENTBOX_API_KEY // environment variable *** -### debug? - -> `optional` **debug?**: `boolean` - -**`Internal`** - -If true the SDK starts in the debug mode and connects to the local envd API server. - -#### Default - -AGENTBOX_DEBUG // environment variable or `false` - -#### Inherited from - -[`SandboxForkOpts`](SandboxForkOpts.md).[`debug`](SandboxForkOpts.md#debug) - -*** - ### domain? > `optional` **domain?**: `string` diff --git a/reference/sdk/javascript/sandbox/interfaces/SnapshotPaginator.md b/reference/sdk/javascript/sandbox/interfaces/SnapshotPaginator.md index 93e299bd..d202fb7f 100644 --- a/reference/sdk/javascript/sandbox/interfaces/SnapshotPaginator.md +++ b/reference/sdk/javascript/sandbox/interfaces/SnapshotPaginator.md @@ -18,26 +18,6 @@ while (paginator.hasNext) { - `Paginator`\<[`SnapshotInfo`](SnapshotInfo.md), [`SandboxApiOpts`](SandboxApiOpts.md)\> -## Properties - -### limit? - -> `protected` `readonly` `optional` **limit?**: `number` - -#### Inherited from - -`Paginator.limit` - -*** - -### opts? - -> `protected` `readonly` `optional` **opts?**: [`SandboxApiOpts`](SandboxApiOpts.md) - -#### Inherited from - -`Paginator.opts` - ## Accessors ### hasNext @@ -107,27 +87,3 @@ Error if there are no more items to fetch. Call this method only if `hasNext` is #### Overrides `Paginator.nextItems` - -*** - -### updatePagination() - -> `protected` **updatePagination**(`response`): `void` - -Update the pagination state from a response, reading the `x-next-token` -header. Concrete paginators call this from Paginator.nextItems -after fetching a page. - -#### Parameters - -##### response - -`Response` - -#### Returns - -`void` - -#### Inherited from - -`Paginator.updatePagination` diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py index 0e5575f7..97122bf6 100644 --- a/scripts/generate-reference.py +++ b/scripts/generate-reference.py @@ -468,6 +468,9 @@ def run_sdk_generators() -> None: "--readme", "none", "--disableSources", + "--excludeInternal", + "--excludePrivate", + "--excludeProtected", "--hidePageHeader", "--out", str(destination), diff --git a/scripts/public_openapi.py b/scripts/public_openapi.py index c2f42b85..872a65cb 100644 --- a/scripts/public_openapi.py +++ b/scripts/public_openapi.py @@ -91,6 +91,71 @@ def assert_no_removed_refs(value: Any) -> None: assert_no_removed_refs(child) +def component_reference(reference: str) -> tuple[str, str] | None: + prefix = "#/components/" + if not reference.startswith(prefix): + return None + parts = reference[len(prefix) :].split("/") + if len(parts) < 2: + return None + + def decode(value: str) -> str: + return value.replace("~1", "/").replace("~0", "~") + + return decode(parts[0]), decode(parts[1]) + + +def collect_component_references(value: Any) -> set[tuple[str, str]]: + references = set() + if isinstance(value, dict): + reference = value.get("$ref") + if isinstance(reference, str): + component = component_reference(reference) + if component is not None: + references.add(component) + for child in value.values(): + references.update(collect_component_references(child)) + elif isinstance(value, list): + for child in value: + references.update(collect_component_references(child)) + return references + + +def prune_unreferenced_components(document: dict) -> None: + """Keep only components reachable from the published OpenAPI surface.""" + components = document.get("components") + if not isinstance(components, dict): + return + + roots = {key: value for key, value in document.items() if key != "components"} + pending = list(collect_component_references(roots)) + reachable = set() + while pending: + component = pending.pop() + if component in reachable: + continue + section, name = component + definition = components.get(section, {}).get(name) + if definition is None: + raise RuntimeError( + f"public OpenAPI references missing component: {section}/{name}" + ) + reachable.add(component) + pending.extend(collect_component_references(definition) - reachable) + + for section in list(components): + definitions = components[section] + if not isinstance(definitions, dict): + continue + components[section] = { + name: definition + for name, definition in definitions.items() + if (section, name) in reachable + } + if not components[section]: + del components[section] + + def filter_public_openapi(document: dict, *, for_reference: bool = False) -> dict: """Mutate and return a client-safe or stricter documentation-safe contract.""" remove_properties( @@ -106,4 +171,6 @@ def filter_public_openapi(document: dict, *, for_reference: bool = False) -> dic schemas.pop(name, None) assert_no_removed_refs(document) + if for_reference: + prune_unreferenced_components(document) return document diff --git a/scripts/test-reference-contract.py b/scripts/test-reference-contract.py index e675b60d..0d8045fa 100644 --- a/scripts/test-reference-contract.py +++ b/scripts/test-reference-contract.py @@ -30,6 +30,18 @@ "AuthProviderBearerAuth", "AuthProviderTeamAuth", } +FORBIDDEN_COMPONENTS = { + "AdminSandboxKillResult", + "AdminBuildCancelResult", + "TeamAPIKey", + "CreatedTeamAPIKey", + "NewTeamAPIKey", + "UpdateTeamAPIKey", + "apiKeyID", + "accessTokenID", + "volumeID", + "VolumeMount", +} def resolve_local_ref(document: dict, value: dict) -> dict: @@ -97,6 +109,42 @@ def assert_public_schema(value) -> None: assert_public_schema(child) +def component_references(value) -> set[tuple[str, str]]: + references = set() + if isinstance(value, dict): + reference = value.get("$ref") + if isinstance(reference, str) and reference.startswith("#/components/"): + section, name, *_ = reference.removeprefix("#/components/").split("/") + references.add((section, name)) + for child in value.values(): + references.update(component_references(child)) + elif isinstance(value, list): + for child in value: + references.update(component_references(child)) + return references + + +def assert_only_reachable_components(document: dict) -> None: + components = document.get("components", {}) + roots = {key: value for key, value in document.items() if key != "components"} + pending = list(component_references(roots)) + reachable = set() + while pending: + component = pending.pop() + if component in reachable: + continue + reachable.add(component) + section, name = component + pending.extend(component_references(components[section][name]) - reachable) + published = { + (section, name) + for section, definitions in components.items() + if section != "securitySchemes" + for name in definitions + } + assert published == reachable + + def main() -> None: manifest = json.loads((REFERENCE / "manifest.json").read_text()) assert manifest["schemaVersion"] == 1 @@ -192,6 +240,12 @@ def main() -> None: } assert_public_schema(document) assert_local_refs_resolve(document) + assert_only_reachable_components(document) + assert not any( + name in FORBIDDEN_COMPONENTS + for definitions in document.get("components", {}).values() + for name in definitions + ) for operation in operations: document = public_documents[operation["spec"]] @@ -246,6 +300,12 @@ def main() -> None: assert not any("deserializeChart" in path for path in javascript_files) assert not any("parseOutput" in path for path in javascript_files) assert not any("extractError" in path for path in javascript_files) + javascript_markdown = "\n".join( + path.read_text() for path in (REFERENCE / "sdk/javascript").rglob("*.md") + ) + assert "**`Internal`**" not in javascript_markdown + assert "envdAccessToken" not in javascript_markdown + assert "protected static createSandbox" not in javascript_markdown list_sandboxes = (REFERENCE / "openapi/markdown/listSandboxes.md").read_text() assert "Metadata query used to filter the sandboxes" in list_sandboxes From 93b612d3ab098006c302bf34f892439cc91dba41 Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Tue, 1 Sep 2026 02:54:25 +0300 Subject: [PATCH 2/8] Improve public reference completeness --- reference/manifest.json | 36 +++---- reference/openapi/envd.yml | 34 ++++++ reference/openapi/markdown/composeFiles.md | 12 +++ reference/openapi/markdown/createSandbox.md | 60 +++++++++++ reference/openapi/markdown/downloadFile.md | 8 ++ reference/openapi/markdown/forkSandbox.md | 28 +++++ .../openapi/markdown/getEnvironmentHealth.md | 10 ++ .../openapi/markdown/getEnvironmentMetrics.md | 10 ++ .../markdown/getEnvironmentVariables.md | 12 +++ reference/openapi/markdown/getSandbox.md | 44 ++++++++ reference/openapi/markdown/getSandboxLogs.md | 20 ++++ reference/openapi/markdown/getTemplate.md | 36 +++++++ .../openapi/markdown/getTemplateBuildLogs.md | 20 ++++ .../markdown/getTemplateBuildStatus.md | 52 +++++++++ .../openapi/markdown/listSandboxMetrics.md | 36 +++++++ reference/openapi/markdown/listSandboxes.md | 4 + .../openapi/markdown/startTemplateBuild.md | 16 +++ .../openapi/markdown/updateSandboxNetwork.md | 12 +++ reference/openapi/markdown/uploadFile.md | 10 ++ scripts/generate-reference.py | 102 +++++++++++++++--- scripts/test-reference-contract.py | 34 ++++++ 21 files changed, 562 insertions(+), 34 deletions(-) diff --git a/reference/manifest.json b/reference/manifest.json index bc51bf38..bed24a89 100644 --- a/reference/manifest.json +++ b/reference/manifest.json @@ -3,43 +3,43 @@ "connect/filesystem.md": "1cc1e81386810d3c5c999458e02340e3becb3da8138d943558584094750e5aae", "connect/process.md": "037574455e9e8c5159c391d8c007e7272560f62c4e5ee681f8aec29f9cd24539", "openapi/control-plane.yml": "99e42c340a18ac1f3bda9321d347b01f6bd8326c39373e92797bfb179ee0a0bf", - "openapi/envd.yml": "c8cb85cbdcfb0ae4ed55a3a0cd6f58b17a23b14bfe74be904a160e770c6e91c3", + "openapi/envd.yml": "334700432025fcdfd9f95f9e58d90e6290b835015a24f269548eba5500c0df4f", "openapi/markdown/assignTemplateTags.md": "3ec3dc705cbda5780d0a9e78234c7777f014784b2ec193821b6f5bb2ea26ec57", - "openapi/markdown/composeFiles.md": "3e5c37b40268689b6e5287a906c75b80f71fefafe94205c6327c976ca0594d5c", + "openapi/markdown/composeFiles.md": "172894794d346ac42d1357e28aafa5c6daea32f361977d0e8d7ac43b04c61577", "openapi/markdown/connectSandbox.md": "9106d09a6f525aa0bcbd1eed06de62a4d015d1f6fa63496ccb6aebbebb3ad332", - "openapi/markdown/createSandbox.md": "42b8b28e9aac9bcbbacec9dec346d043340f8c94ac497147a80910341572226f", + "openapi/markdown/createSandbox.md": "3bf499af52b01f87e48dfa56c0af227d4d22f755444118e8a8422b216c851f8d", "openapi/markdown/createSnapshot.md": "433724d1260fd60e68268a2984f7ca7ae54a1cad120fb25a026b6a6518af004f", "openapi/markdown/createTemplate.md": "b31935eef9b0c29bcd9402f7401a4159c349bed8b3e5458c4490870574bc2974", "openapi/markdown/deleteTemplate.md": "3f9a6ab1e0ab144f0a68e41938ef23fd07ac2509b16f6b4b9df5478e54a5865c", "openapi/markdown/deleteTemplateTags.md": "1b907ed1b5d9cd55a3b21f46c207217af8a4efe0fe6ccb56a8f988567fc27395", - "openapi/markdown/downloadFile.md": "d687f0fadf42a0c8d40324fbf6a732677dae38ed1cf02a755cf86eb9a5155abc", - "openapi/markdown/forkSandbox.md": "bc7846648216b1104ed1d1661eb08b9881b3fef7616bfae49542eca1d228e76e", - "openapi/markdown/getEnvironmentHealth.md": "640c9435ce216a6fd0e5da7ee646d8527e5de428c946fad219946f5c1de5622a", - "openapi/markdown/getEnvironmentMetrics.md": "fb7ce3264e1500da24b21a07b5b180110fa573fc3fb476c146f4529c16e7c089", - "openapi/markdown/getEnvironmentVariables.md": "12803bbc7e3f2638e16f013ce05b2a688d8085739e38049c1022452fd7881e50", - "openapi/markdown/getSandbox.md": "9e9f1200583b9abb206e7c69e9d4157403297042d2dd1e57e5bd804962073a91", - "openapi/markdown/getSandboxLogs.md": "6641f57b0ef9f7e029b66deb472616ea4abe54f3884b3021bfcf97b37920a598", + "openapi/markdown/downloadFile.md": "828154a446933bd19b1f20ca9170f6e93f2f80872fc08e92e46d339872e8f45c", + "openapi/markdown/forkSandbox.md": "84962addf6f2d49e40aaaca2e27f79e8e98991f703c7374e8852d4e47944dbc4", + "openapi/markdown/getEnvironmentHealth.md": "7595329f0fceb5ba613d73f8c522287f7836651d9a2dc44002a149c3ca8c57bf", + "openapi/markdown/getEnvironmentMetrics.md": "d6ebfaa682e3e2b6489703daf643b887362f5fdca055f9f3b2367143b03a5112", + "openapi/markdown/getEnvironmentVariables.md": "58fe720040afa68bc542c0416378bab9642dbfe73d397b923b220e44bb4c2f54", + "openapi/markdown/getSandbox.md": "fb4a7184f903a8bdd8c3b7ea1d00b10d17d26c6dc56b1e7f1a07f91f99aee09d", + "openapi/markdown/getSandboxLogs.md": "a3055767e82145d9c0cb1953ee1081489c0098200018802292634e4cb3c830c2", "openapi/markdown/getSandboxMetrics.md": "1572d44d0ff539495dadcbb909bb1e640b73375fcb4b0840243e692066162ace", "openapi/markdown/getTeamMetrics.md": "063860650df86f09f1119f441b1410b1e329dd20000cf1b1f8a1f84fdcbdac53", "openapi/markdown/getTeamMetricsMax.md": "5e5e6578470d1710c993ae69a91b34badaaa86e62e141eb91e57c6e0f7594fe6", - "openapi/markdown/getTemplate.md": "fa972635535ecb1b19324216185f75c90fe81520ed79dc7e20a0894306e054b3", - "openapi/markdown/getTemplateBuildLogs.md": "c1dc222e7ab5268897e8fdda893d1264ac9162db146fb89bbe6c9833f350ab7f", - "openapi/markdown/getTemplateBuildStatus.md": "26741b144d7ce26f353173bd0665b30925e6161d914317fb994bae5c2b4d0d3d", + "openapi/markdown/getTemplate.md": "a4747e42b28bb014ae4eb3b5477fe6d58cfda25c00ae829c339cfb7ef5ec6715", + "openapi/markdown/getTemplateBuildLogs.md": "5f696d204a13be42ce9df32b51ac4680b853231595d84e14aca9db7e05b385ff", + "openapi/markdown/getTemplateBuildStatus.md": "7ef1697ca9b6c3d44624df8ca528fdc5e4f81ebd226c748ae2183b2e99e27757", "openapi/markdown/getTemplateByAlias.md": "2a42010266038d50581e3526becf1f35ad3ada6eecd757522b083817fe435301", "openapi/markdown/getTemplateUploadUrl.md": "b06cb4aaed389e75daa8e509e3437a23915aad2b03ef6e69597df67984a48b19", "openapi/markdown/killSandbox.md": "c864528a36849a512be77bf144ef7d41356f01cb0dbbe1d2f5143712a95268f2", - "openapi/markdown/listSandboxMetrics.md": "b945d76f80dc2fef506d2f21183bca49ddb045773b8895b6412e435e5c9d6d7f", - "openapi/markdown/listSandboxes.md": "7744505b60b94d1c8db8c1b7a1a66bcf9bdb8f51a46b13b5a90349e562924f59", + "openapi/markdown/listSandboxMetrics.md": "38cc35b6d1087635efc6fa351da48402a021f12b185e3bbfbafacc64a34b8d87", + "openapi/markdown/listSandboxes.md": "ebb79c21ab83ad61ea2e7c738fa2f77d37c001e2d09142508209e7beab687aeb", "openapi/markdown/listSnapshots.md": "d7f7ae67491c5da2930181b0fe423ef8ad661f5f4e7e88f47ecfb58cb08ac83f", "openapi/markdown/listTemplateTags.md": "df27ed0dc04e6b49a3dc92704842e30365f50e88c8e28e6a5323a16aa10b7c45", "openapi/markdown/listTemplates.md": "e89b7d18efcfa6e16385e6b4e2f227ad2e5c9fa7608426ece673077a35468e12", "openapi/markdown/pauseSandbox.md": "0d1e7dd52ca966d37742e7d34898559dfd03c4ba3ca7f83f1859ddaefa9b0464", "openapi/markdown/refreshSandbox.md": "dea1862241aad45c17b194994722a23941263bb697b885e795ba97cf154469bd", "openapi/markdown/setSandboxTimeout.md": "ee0aaf78e2c0ffcdf4df1bde703fd4442d5436efad290bc235d1acc120adb997", - "openapi/markdown/startTemplateBuild.md": "befd11983028352bd7bf727113deb9bbb7d86d7b02385441111f4de46087173c", - "openapi/markdown/updateSandboxNetwork.md": "3449bd43a4e46c35d3f8ec314a47876ec06f85a8a75e4255212a85cb7a4c3e53", + "openapi/markdown/startTemplateBuild.md": "f987c7627a0170ff2908fd344d76acea3b2d8f7875686ff746ad8a8b2b3922c4", + "openapi/markdown/updateSandboxNetwork.md": "0254acd4dca8299bd7198024660bb1300752c6842f225c604389dd1951333675", "openapi/markdown/updateTemplate.md": "ace7930be4091213fc2e29a7109f489eaaf3a0e1d210aa65d9663a5adbf92250", - "openapi/markdown/uploadFile.md": "fe1dcc1b1eaad25ecd73f8c00a49c94ca7c2686fbdb6f3e2fbbebbfec6928806", + "openapi/markdown/uploadFile.md": "2c3b042f305f2e7234799f0af14979965e76a10ced1a74a464bb6afd96c5c68c", "openapi/operations.json": "f5097d93fb7eb5f6482e632624d5a212e29441ef8c558601ccbe2dae26db050d", "sdk/cli/auth.md": "0b2c75262b0c0670c7bc0f0f3cbed65fbe4a16d6fe4437789a5685b8bf2174a1", "sdk/cli/sandbox.md": "16b64c5a4e932eca2452e400e0faf154eba1d3c7373513aa7cd9744e02908313", diff --git a/reference/openapi/envd.yml b/reference/openapi/envd.yml index 0228214f..c72960ac 100644 --- a/reference/openapi/envd.yml +++ b/reference/openapi/envd.yml @@ -16,6 +16,9 @@ paths: operationId: getEnvironmentHealth tags: - environment + parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' security: [] /metrics: get: @@ -30,6 +33,9 @@ paths: operationId: getEnvironmentMetrics tags: - environment + parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' security: - {} - AccessTokenAuth: [] @@ -46,6 +52,9 @@ paths: operationId: getEnvironmentVariables tags: - environment + parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' security: - {} - AccessTokenAuth: [] @@ -55,6 +64,8 @@ paths: tags: - files parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' - $ref: '#/components/parameters/FilePath' - $ref: '#/components/parameters/User' - $ref: '#/components/parameters/Signature' @@ -122,6 +133,8 @@ paths: tags: - files parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' - $ref: '#/components/parameters/FilePath' - $ref: '#/components/parameters/User' - $ref: '#/components/parameters/Signature' @@ -173,6 +186,9 @@ paths: '507': $ref: '#/components/responses/NotEnoughDiskSpace' operationId: composeFiles + parameters: + - $ref: '#/components/parameters/AgentboxSandboxId' + - $ref: '#/components/parameters/AgentboxSandboxPort' security: - {} - AccessTokenAuth: [] @@ -209,6 +225,21 @@ components: used with the signature parameter. schema: type: integer + AgentboxSandboxId: + name: Agentbox-Sandbox-Id + in: header + required: true + description: Identifier of the sandbox that receives the request. + schema: + type: string + AgentboxSandboxPort: + name: Agentbox-Sandbox-Port + in: header + required: true + description: Internal envd HTTP port exposed through the sandbox proxy. + schema: + type: integer + default: 49983 requestBodies: File: required: true @@ -399,3 +430,6 @@ components: type: apiKey in: header name: X-Access-Token +servers: +- url: https://sandbox.agentbox-runtime.ru + description: AgentBox sandbox proxy. Routing headers are required. diff --git a/reference/openapi/markdown/composeFiles.md b/reference/openapi/markdown/composeFiles.md index 41ea5efd..2340aee4 100644 --- a/reference/openapi/markdown/composeFiles.md +++ b/reference/openapi/markdown/composeFiles.md @@ -2,6 +2,16 @@ Compose multiple files into a single file using zero-copy concatenation. Source files are deleted after successful composition. +## Parameters + +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + ## Request body Required: yes @@ -48,6 +58,8 @@ Schema: `EntryInfo` User-defined metadata stored as extended attributes on the file. +- **`metadata.*`** · `string` · additional property + ### 400 Invalid path diff --git a/reference/openapi/markdown/createSandbox.md b/reference/openapi/markdown/createSandbox.md index ec627b95..d46fb429 100644 --- a/reference/openapi/markdown/createSandbox.md +++ b/reference/openapi/markdown/createSandbox.md @@ -32,6 +32,10 @@ Schema: `NewSandbox` Auto-resume configuration for paused sandboxes. +- **`autoResume.enabled`** · `SandboxAutoResumeEnabled` · required + + Auto-resume enabled flag for paused sandboxes. Default false. + - **`secure`** · `boolean` · optional Secure all system communication with sandbox @@ -42,18 +46,74 @@ Schema: `NewSandbox` - **`network`** · `SandboxNetworkConfig` · optional +- **`network.allowPublicTraffic`** · `boolean` · optional + + Specify if the sandbox URLs should be accessible only with authentication. + +- **`network.allowOut`** · `array` · optional + + List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. + +- **`network.denyOut`** · `array` · optional + + List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules. + +- **`network.maskRequestHost`** · `string` · optional + + Specify host mask which will be used for all sandbox requests + +- **`network.rules`** · `object` · optional + + Per-domain transform rules applied to matching egress HTTP/HTTPS requests. Keys are domains (e.g. "api.example.com", "example.com"). A domain listed here is not automatically allowed - use allowOut to permit the traffic. + +- **`network.rules.*`** · `array` · additional property + +- **`network.rules.*.transform`** · `SandboxNetworkTransform` · optional + + Transformations applied to matching egress requests before forwarding. + +- **`network.rules.*.transform.headers`** · `object` · optional + + HTTP headers to inject or override in matching requests. An existing header with the same name is replaced. Values are plain strings; secret resolution happens client-side before sending to the API. + +- **`network.rules.*.transform.headers.*`** · `string` · additional property + - **`metadata`** · `SandboxMetadata` · optional +- **`metadata.*`** · `string` · additional property + + Metadata of the sandbox + - **`envVars`** · `EnvVars` · optional +- **`envVars.*`** · `string` · additional property + + Environment variables for the sandbox + - **`mcp`** · `Mcp` · optional MCP configuration for the sandbox +- **`mcp.*`** · `object` · additional property + - **`iam`** · `SandboxIam` · optional Sandbox workload identity configuration. A non-empty, valid tokens map enables workload identity for the sandbox. +- **`iam.tokens`** · `SandboxIamTokens` · optional + + Named workload-token definitions, keyed by a caller-chosen token name. + +- **`iam.tokens.*`** · `SandboxIamToken` · additional property + +- **`iam.tokens.*.audience`** · `string` · required + + Audience of the workload token, stored exactly as provided. + +- **`iam.tokens.*.tokenType`** · `string` · required + + Workload token type. + ## Responses ### 201 diff --git a/reference/openapi/markdown/downloadFile.md b/reference/openapi/markdown/downloadFile.md index fb804f78..623bd08c 100644 --- a/reference/openapi/markdown/downloadFile.md +++ b/reference/openapi/markdown/downloadFile.md @@ -4,6 +4,14 @@ Download a file ## Parameters +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + - **`path`** · `string` · query · optional Path to the file, URL encoded. Can be relative to the user's home directory (e.g. "file.txt" resolves to ~/file.txt). diff --git a/reference/openapi/markdown/forkSandbox.md b/reference/openapi/markdown/forkSandbox.md index 930cb006..ac54903d 100644 --- a/reference/openapi/markdown/forkSandbox.md +++ b/reference/openapi/markdown/forkSandbox.md @@ -36,8 +36,36 @@ Schema: `array` - **`sandbox`** · `Sandbox` · optional +- **`sandbox.templateID`** · `string` · required + + Identifier of the template from which is the sandbox created + +- **`sandbox.sandboxID`** · `string` · required + + Identifier of the sandbox + +- **`sandbox.alias`** · `string` · optional + + Alias of the template + +- **`sandbox.envdVersion`** · `EnvdVersion` · required + + Version of the envd running in the sandbox + +- **`sandbox.domain`** · `string` · optional + + Base domain where the sandbox traffic is accessible + - **`error`** · `Error` · optional +- **`error.code`** · `integer` · required + + Error code + +- **`error.message`** · `string` · required + + Error + ### 409 Conflict diff --git a/reference/openapi/markdown/getEnvironmentHealth.md b/reference/openapi/markdown/getEnvironmentHealth.md index 6340668e..77e535de 100644 --- a/reference/openapi/markdown/getEnvironmentHealth.md +++ b/reference/openapi/markdown/getEnvironmentHealth.md @@ -2,6 +2,16 @@ Check the health of the service +## Parameters + +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + ## Responses ### 204 diff --git a/reference/openapi/markdown/getEnvironmentMetrics.md b/reference/openapi/markdown/getEnvironmentMetrics.md index 11fdd6c1..cceaeb96 100644 --- a/reference/openapi/markdown/getEnvironmentMetrics.md +++ b/reference/openapi/markdown/getEnvironmentMetrics.md @@ -2,6 +2,16 @@ Service stats +## Parameters + +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + ## Responses ### 200 diff --git a/reference/openapi/markdown/getEnvironmentVariables.md b/reference/openapi/markdown/getEnvironmentVariables.md index 41b53968..2f59bd84 100644 --- a/reference/openapi/markdown/getEnvironmentVariables.md +++ b/reference/openapi/markdown/getEnvironmentVariables.md @@ -2,6 +2,16 @@ Environment variables +## Parameters + +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + ## Responses ### 200 @@ -11,3 +21,5 @@ Environment variables Content-Type: `application/json` Schema: `EnvVars` + +- **`*`** · `string` · additional property diff --git a/reference/openapi/markdown/getSandbox.md b/reference/openapi/markdown/getSandbox.md index 92440830..f9855300 100644 --- a/reference/openapi/markdown/getSandbox.md +++ b/reference/openapi/markdown/getSandbox.md @@ -64,16 +64,60 @@ Schema: `SandboxDetail` - **`metadata`** · `SandboxMetadata` · optional +- **`metadata.*`** · `string` · additional property + + Metadata of the sandbox + - **`state`** · `SandboxState` · required State of the sandbox - **`network`** · `SandboxNetworkConfig` · optional +- **`network.allowPublicTraffic`** · `boolean` · optional + + Specify if the sandbox URLs should be accessible only with authentication. + +- **`network.allowOut`** · `array` · optional + + List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. + +- **`network.denyOut`** · `array` · optional + + List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules. + +- **`network.maskRequestHost`** · `string` · optional + + Specify host mask which will be used for all sandbox requests + +- **`network.rules`** · `object` · optional + + Per-domain transform rules applied to matching egress HTTP/HTTPS requests. Keys are domains (e.g. "api.example.com", "example.com"). A domain listed here is not automatically allowed - use allowOut to permit the traffic. + +- **`network.rules.*`** · `array` · additional property + +- **`network.rules.*.transform`** · `SandboxNetworkTransform` · optional + + Transformations applied to matching egress requests before forwarding. + +- **`network.rules.*.transform.headers`** · `object` · optional + + HTTP headers to inject or override in matching requests. An existing header with the same name is replaced. Values are plain strings; secret resolution happens client-side before sending to the API. + +- **`network.rules.*.transform.headers.*`** · `string` · additional property + - **`lifecycle`** · `SandboxLifecycle` · optional Sandbox lifecycle policy returned by sandbox info. +- **`lifecycle.autoResume`** · `boolean` · required + + Whether the sandbox can auto-resume. + +- **`lifecycle.onTimeout`** · `SandboxOnTimeout` · required + + Action taken when the sandbox times out. + ### 404 Not found diff --git a/reference/openapi/markdown/getSandboxLogs.md b/reference/openapi/markdown/getSandboxLogs.md index b8128fa8..3ad2b4aa 100644 --- a/reference/openapi/markdown/getSandboxLogs.md +++ b/reference/openapi/markdown/getSandboxLogs.md @@ -46,6 +46,26 @@ Schema: `SandboxLogsV2Response` Sandbox logs structured +- **`logs.id`** · `string` · optional + + Stable identifier used to reconcile overlapping live log pages + +- **`logs.timestamp`** · `string` · required + + Timestamp of the log entry + +- **`logs.message`** · `string` · required + + Log message content + +- **`logs.level`** · `LogLevel` · required + + State of the sandbox + +- **`logs.fields`** · `object` · required + +- **`logs.fields.*`** · `string` · additional property + - **`nextCursor`** · `string` · optional Opaque continuation cursor for the next page diff --git a/reference/openapi/markdown/getTemplate.md b/reference/openapi/markdown/getTemplate.md index 9cc53b83..e08d63fa 100644 --- a/reference/openapi/markdown/getTemplate.md +++ b/reference/openapi/markdown/getTemplate.md @@ -58,6 +58,42 @@ Schema: `TemplateWithBuilds` List of builds for the template +- **`builds.buildID`** · `string` · required + + Identifier of the build + +- **`builds.status`** · `TemplateBuildStatus` · required + + Status of the template build + +- **`builds.createdAt`** · `string` · required + + Time when the build was created + +- **`builds.updatedAt`** · `string` · required + + Time when the build was last updated + +- **`builds.finishedAt`** · `string` · optional + + Time when the build was finished + +- **`builds.cpuCount`** · `CPUCount` · required + + CPU cores for the sandbox + +- **`builds.memoryMB`** · `MemoryMB` · required + + Memory for the sandbox in MiB + +- **`builds.diskSizeMB`** · `DiskSizeMB` · optional + + Disk size for the sandbox in MiB + +- **`builds.envdVersion`** · `EnvdVersion` · optional + + Version of the envd running in the sandbox + ### 401 Authentication error diff --git a/reference/openapi/markdown/getTemplateBuildLogs.md b/reference/openapi/markdown/getTemplateBuildLogs.md index c2e07605..5db43d2c 100644 --- a/reference/openapi/markdown/getTemplateBuildLogs.md +++ b/reference/openapi/markdown/getTemplateBuildLogs.md @@ -44,6 +44,26 @@ Schema: `TemplateBuildLogsResponse` Build logs structured +- **`logs.id`** · `string` · optional + + Stable identifier used to reconcile overlapping live log pages + +- **`logs.timestamp`** · `string` · required + + Timestamp of the log entry + +- **`logs.message`** · `string` · required + + Log message content + +- **`logs.level`** · `LogLevel` · required + + State of the sandbox + +- **`logs.step`** · `string` · optional + + Step in the build process related to the log entry + - **`nextCursor`** · `string` · optional Opaque continuation cursor for the next page diff --git a/reference/openapi/markdown/getTemplateBuildStatus.md b/reference/openapi/markdown/getTemplateBuildStatus.md index e435cbd8..c2316648 100644 --- a/reference/openapi/markdown/getTemplateBuildStatus.md +++ b/reference/openapi/markdown/getTemplateBuildStatus.md @@ -38,6 +38,26 @@ Schema: `TemplateBuildInfo` Build logs structured +- **`logEntries.id`** · `string` · optional + + Stable identifier used to reconcile overlapping live log pages + +- **`logEntries.timestamp`** · `string` · required + + Timestamp of the log entry + +- **`logEntries.message`** · `string` · required + + Log message content + +- **`logEntries.level`** · `LogLevel` · required + + State of the sandbox + +- **`logEntries.step`** · `string` · optional + + Step in the build process related to the log entry + - **`templateID`** · `string` · required Identifier of the template @@ -52,6 +72,38 @@ Schema: `TemplateBuildInfo` - **`reason`** · `BuildStatusReason` · optional +- **`reason.message`** · `string` · required + + Message with the status reason, currently reporting only for error status + +- **`reason.step`** · `string` · optional + + Step that failed + +- **`reason.logEntries`** · `array` · optional + + Log entries related to the status reason + +- **`reason.logEntries.id`** · `string` · optional + + Stable identifier used to reconcile overlapping live log pages + +- **`reason.logEntries.timestamp`** · `string` · required + + Timestamp of the log entry + +- **`reason.logEntries.message`** · `string` · required + + Log message content + +- **`reason.logEntries.level`** · `LogLevel` · required + + State of the sandbox + +- **`reason.logEntries.step`** · `string` · optional + + Step in the build process related to the log entry + ### 401 Authentication error diff --git a/reference/openapi/markdown/listSandboxMetrics.md b/reference/openapi/markdown/listSandboxMetrics.md index 50bb1609..77dfd3ab 100644 --- a/reference/openapi/markdown/listSandboxMetrics.md +++ b/reference/openapi/markdown/listSandboxMetrics.md @@ -22,6 +22,42 @@ Schema: `SandboxesWithMetrics` - **`sandboxes`** · `object` · required +- **`sandboxes.*`** · `SandboxMetric` · additional property + + Metric entry with timestamp and line + +- **`sandboxes.*.timestampUnix`** · `integer` · required + + Timestamp of the metric entry in Unix time (seconds since epoch) + +- **`sandboxes.*.cpuCount`** · `integer` · required + + Number of CPU cores + +- **`sandboxes.*.cpuUsedPct`** · `number` · required + + CPU usage percentage + +- **`sandboxes.*.memUsed`** · `integer` · required + + Memory used in bytes + +- **`sandboxes.*.memTotal`** · `integer` · required + + Total memory in bytes + +- **`sandboxes.*.memCache`** · `integer` · required + + Cached memory (page cache) in bytes + +- **`sandboxes.*.diskUsed`** · `integer` · required + + Disk used in bytes + +- **`sandboxes.*.diskTotal`** · `integer` · required + + Total disk space in bytes + ### 401 Authentication error diff --git a/reference/openapi/markdown/listSandboxes.md b/reference/openapi/markdown/listSandboxes.md index 31b7ee59..1160874b 100644 --- a/reference/openapi/markdown/listSandboxes.md +++ b/reference/openapi/markdown/listSandboxes.md @@ -66,6 +66,10 @@ Schema: `array` - **`metadata`** · `SandboxMetadata` · optional +- **`metadata.*`** · `string` · additional property + + Metadata of the sandbox + - **`state`** · `SandboxState` · required State of the sandbox diff --git a/reference/openapi/markdown/startTemplateBuild.md b/reference/openapi/markdown/startTemplateBuild.md index 2249f043..38e3c466 100644 --- a/reference/openapi/markdown/startTemplateBuild.md +++ b/reference/openapi/markdown/startTemplateBuild.md @@ -36,6 +36,22 @@ Schema: `TemplateBuildStartV2` List of steps to execute in the template build +- **`steps.type`** · `string` · required + + Type of the step + +- **`steps.args`** · `array` · optional + + Arguments for the step + +- **`steps.filesHash`** · `string` · optional + + Hash of the files used in the step + +- **`steps.force`** · `boolean` · optional + + Whether the step should be forced to run regardless of the cache + - **`startCmd`** · `string` · optional Start command to execute in the template after the build diff --git a/reference/openapi/markdown/updateSandboxNetwork.md b/reference/openapi/markdown/updateSandboxNetwork.md index 08e2281c..195342bd 100644 --- a/reference/openapi/markdown/updateSandboxNetwork.md +++ b/reference/openapi/markdown/updateSandboxNetwork.md @@ -28,6 +28,18 @@ Schema: `SandboxNetworkUpdateConfig` Per-domain transform rules. Replaces all existing rules when provided. +- **`rules.*`** · `array` · additional property + +- **`rules.*.transform`** · `SandboxNetworkTransform` · optional + + Transformations applied to matching egress requests before forwarding. + +- **`rules.*.transform.headers`** · `object` · optional + + HTTP headers to inject or override in matching requests. An existing header with the same name is replaced. Values are plain strings; secret resolution happens client-side before sending to the API. + +- **`rules.*.transform.headers.*`** · `string` · additional property + - **`allow_internet_access`** · `boolean` · optional Allow sandbox to access the internet. When set to false, it behaves the same as specifying denyOut to 0.0.0.0/0 in the network config. diff --git a/reference/openapi/markdown/uploadFile.md b/reference/openapi/markdown/uploadFile.md index b186adec..147e0653 100644 --- a/reference/openapi/markdown/uploadFile.md +++ b/reference/openapi/markdown/uploadFile.md @@ -25,6 +25,14 @@ value is used. ## Parameters +- **`Agentbox-Sandbox-Id`** · `string` · header · required + + Identifier of the sandbox that receives the request. + +- **`Agentbox-Sandbox-Port`** · `integer` · header · required + + Internal envd HTTP port exposed through the sandbox proxy. + - **`path`** · `string` · query · optional Path to the file, URL encoded. Can be relative to the user's home directory (e.g. "file.txt" resolves to ~/file.txt). @@ -81,6 +89,8 @@ Schema: `array` User-defined metadata stored as extended attributes on the file. +- **`metadata.*`** · `string` · additional property + ### 400 Invalid path diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py index 97122bf6..c2fad8bf 100644 --- a/scripts/generate-reference.py +++ b/scripts/generate-reference.py @@ -89,40 +89,74 @@ def render_named_item( return lines -def schema_fields(document: dict, schema: dict) -> dict: - """Return the object schema whose fields describe a response value.""" - resolved, _ = resolve_ref(document, schema) +def schema_fields(document: dict, schema: dict) -> tuple[dict, str | None]: + """Return the object schema whose fields describe a value.""" + resolved, reference_name = resolve_ref(document, schema) visited = set() while isinstance(resolved, dict) and resolved.get("type") == "array": marker = id(resolved) if marker in visited: - return {} + return {}, reference_name visited.add(marker) items = resolved.get("items") if not isinstance(items, dict): - return {} - resolved, _ = resolve_ref(document, items) - return resolved if isinstance(resolved, dict) else {} + return {}, reference_name + resolved, item_reference = resolve_ref(document, items) + reference_name = item_reference or reference_name + return (resolved if isinstance(resolved, dict) else {}), reference_name -def render_schema(document: dict, schema: dict) -> list[str]: - resolved, reference_name = resolve_ref(document, schema) - lines = [f"Schema: `{reference_name or schema_type(document, resolved)}`", ""] - fields = schema_fields(document, resolved) - properties = fields.get("properties", {}) - if not properties: - return lines +def render_schema_fields( + document: dict, + schema: dict, + prefix: str = "", + ancestors: frozenset[tuple[str, object]] = frozenset(), +) -> list[str]: + """Render public fields recursively with cycle-safe dotted paths.""" + fields, reference_name = schema_fields(document, schema) + marker = ("reference", reference_name) if reference_name else ("schema", id(fields)) + if marker in ancestors: + return [] + descendants = ancestors | {marker} + lines = [] required = set(fields.get("required", [])) - for name, property_schema in properties.items(): + for name, property_schema in fields.get("properties", {}).items(): + field_name = f"{prefix}.{name}" if prefix else name property_value, _ = resolve_ref(document, property_schema) lines.extend( render_named_item( - name, + field_name, schema_type(document, property_schema), ["required" if name in required else "optional"], property_value.get("description", ""), ) ) + lines.extend( + render_schema_fields(document, property_schema, field_name, descendants) + ) + + additional = fields.get("additionalProperties") + if isinstance(additional, dict): + field_name = f"{prefix}.*" if prefix else "*" + additional_value, _ = resolve_ref(document, additional) + lines.extend( + render_named_item( + field_name, + schema_type(document, additional), + ["additional property"], + additional_value.get("description", ""), + ) + ) + lines.extend( + render_schema_fields(document, additional, field_name, descendants) + ) + return lines + + +def render_schema(document: dict, schema: dict) -> list[str]: + resolved, reference_name = resolve_ref(document, schema) + lines = [f"Schema: `{reference_name or schema_type(document, resolved)}`", ""] + lines.extend(render_schema_fields(document, resolved)) return lines @@ -273,6 +307,40 @@ def apply_public_operation_security( operation["security"] = [requirement] if auth["required"] else [{}, requirement] +def apply_envd_routing(public: dict, records: list[dict]) -> None: + """Publish the stable sandbox proxy contract required by envd operations.""" + public["servers"] = [ + { + "url": "https://sandbox.agentbox-runtime.ru", + "description": "AgentBox sandbox proxy. Routing headers are required.", + } + ] + parameters = { + "AgentboxSandboxId": { + "name": "Agentbox-Sandbox-Id", + "in": "header", + "required": True, + "description": "Identifier of the sandbox that receives the request.", + "schema": {"type": "string"}, + }, + "AgentboxSandboxPort": { + "name": "Agentbox-Sandbox-Port", + "in": "header", + "required": True, + "description": "Internal envd HTTP port exposed through the sandbox proxy.", + "schema": {"type": "integer", "default": 49983}, + }, + } + public.setdefault("components", {}).setdefault("parameters", {}).update(parameters) + for record in records: + operation = public["paths"][record["path"]][record["method"].lower()] + operation["parameters"] = [ + {"$ref": "#/components/parameters/AgentboxSandboxId"}, + {"$ref": "#/components/parameters/AgentboxSandboxPort"}, + *operation.get("parameters", []), + ] + + def build_openapi(name: str, config: dict) -> list[dict]: source = ROOT / config["source"] document = yaml.safe_load(source.read_text()) @@ -367,6 +435,8 @@ def build_openapi(name: str, config: dict) -> list[dict]: {"name": group} for group in sorted({record["group"] for record in records}) ] filter_public_openapi(public, for_reference=True) + if name == "envd": + apply_envd_routing(public, records) apply_public_operation_security(document, public, records, public_auth_schemes) destination = ( OUT diff --git a/scripts/test-reference-contract.py b/scripts/test-reference-contract.py index 0d8045fa..7c809faa 100644 --- a/scripts/test-reference-contract.py +++ b/scripts/test-reference-contract.py @@ -238,6 +238,32 @@ def main() -> None: "in": "header", "name": expected_header, } + if spec_name == "envd": + assert document["servers"] == [ + { + "url": "https://sandbox.agentbox-runtime.ru", + "description": ( + "AgentBox sandbox proxy. Routing headers are required." + ), + } + ] + for path_item in document["paths"].values(): + for method, operation in path_item.items(): + if method not in {"get", "post", "put", "patch", "delete"}: + continue + headers = { + parameter["name"]: parameter + for parameter in ( + resolve_local_ref(document, value) + for value in operation.get("parameters", []) + ) + if parameter.get("in") == "header" + } + assert headers["Agentbox-Sandbox-Id"]["required"] is True + assert headers["Agentbox-Sandbox-Port"]["required"] is True + assert ( + headers["Agentbox-Sandbox-Port"]["schema"]["default"] == 49983 + ) assert_public_schema(document) assert_local_refs_resolve(document) assert_only_reachable_components(document) @@ -315,6 +341,14 @@ def main() -> None: assert "- **`metadata`** · `string` · query · optional" in list_sandboxes create_sandbox = (REFERENCE / "openapi/markdown/createSandbox.md").read_text() assert "Schema: `NewSandbox`" in create_sandbox + for field in ( + "autoResume.enabled", + "network.allowPublicTraffic", + "network.maskRequestHost", + "iam.tokens", + "iam.tokens.*.audience", + ): + assert f"- **`{field}`** ·" in create_sandbox if __name__ == "__main__": From 0c3c9ac5bd32cb94123a9d5a1d54fbc4fb3b01a5 Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Tue, 1 Sep 2026 03:26:39 +0300 Subject: [PATCH 3/8] Preserve OpenAPI schema details in reference --- reference/manifest.json | 72 +++++++------- .../openapi/markdown/assignTemplateTags.md | 10 ++ reference/openapi/markdown/composeFiles.md | 4 + reference/openapi/markdown/connectSandbox.md | 12 +++ reference/openapi/markdown/createSandbox.md | 20 ++++ reference/openapi/markdown/createSnapshot.md | 8 ++ reference/openapi/markdown/createTemplate.md | 18 ++++ reference/openapi/markdown/deleteTemplate.md | 4 + .../openapi/markdown/deleteTemplateTags.md | 8 ++ reference/openapi/markdown/downloadFile.md | 6 ++ reference/openapi/markdown/forkSandbox.md | 24 +++++ .../openapi/markdown/getEnvironmentHealth.md | 2 + .../openapi/markdown/getEnvironmentMetrics.md | 8 ++ .../markdown/getEnvironmentVariables.md | 4 + reference/openapi/markdown/getSandbox.md | 28 ++++++ reference/openapi/markdown/getSandboxLogs.md | 30 ++++++ .../openapi/markdown/getSandboxMetrics.md | 32 +++++++ reference/openapi/markdown/getTeamMetrics.md | 22 +++++ .../openapi/markdown/getTeamMetricsMax.md | 22 +++++ reference/openapi/markdown/getTemplate.md | 48 ++++++++++ .../openapi/markdown/getTemplateBuildLogs.md | 32 +++++++ .../markdown/getTemplateBuildStatus.md | 32 +++++++ .../openapi/markdown/getTemplateByAlias.md | 8 ++ .../openapi/markdown/getTemplateUploadUrl.md | 8 ++ reference/openapi/markdown/killSandbox.md | 6 ++ .../openapi/markdown/listSandboxMetrics.md | 22 +++++ reference/openapi/markdown/listSandboxes.md | 46 +++++++++ reference/openapi/markdown/listSnapshots.md | 18 ++++ .../openapi/markdown/listTemplateTags.md | 12 +++ reference/openapi/markdown/listTemplates.md | 46 +++++++++ reference/openapi/markdown/pauseSandbox.md | 10 ++ reference/openapi/markdown/refreshSandbox.md | 8 ++ .../openapi/markdown/setSandboxTimeout.md | 10 ++ .../openapi/markdown/startTemplateBuild.md | 56 +++++++++++ .../openapi/markdown/updateSandboxNetwork.md | 10 ++ reference/openapi/markdown/updateTemplate.md | 6 ++ reference/openapi/markdown/uploadFile.md | 10 ++ scripts/generate-reference.py | 93 ++++++++++++++++++- scripts/test-reference-contract.py | 37 ++++++++ 39 files changed, 815 insertions(+), 37 deletions(-) diff --git a/reference/manifest.json b/reference/manifest.json index bed24a89..bde6fe09 100644 --- a/reference/manifest.json +++ b/reference/manifest.json @@ -4,42 +4,42 @@ "connect/process.md": "037574455e9e8c5159c391d8c007e7272560f62c4e5ee681f8aec29f9cd24539", "openapi/control-plane.yml": "99e42c340a18ac1f3bda9321d347b01f6bd8326c39373e92797bfb179ee0a0bf", "openapi/envd.yml": "334700432025fcdfd9f95f9e58d90e6290b835015a24f269548eba5500c0df4f", - "openapi/markdown/assignTemplateTags.md": "3ec3dc705cbda5780d0a9e78234c7777f014784b2ec193821b6f5bb2ea26ec57", - "openapi/markdown/composeFiles.md": "172894794d346ac42d1357e28aafa5c6daea32f361977d0e8d7ac43b04c61577", - "openapi/markdown/connectSandbox.md": "9106d09a6f525aa0bcbd1eed06de62a4d015d1f6fa63496ccb6aebbebb3ad332", - "openapi/markdown/createSandbox.md": "3bf499af52b01f87e48dfa56c0af227d4d22f755444118e8a8422b216c851f8d", - "openapi/markdown/createSnapshot.md": "433724d1260fd60e68268a2984f7ca7ae54a1cad120fb25a026b6a6518af004f", - "openapi/markdown/createTemplate.md": "b31935eef9b0c29bcd9402f7401a4159c349bed8b3e5458c4490870574bc2974", - "openapi/markdown/deleteTemplate.md": "3f9a6ab1e0ab144f0a68e41938ef23fd07ac2509b16f6b4b9df5478e54a5865c", - "openapi/markdown/deleteTemplateTags.md": "1b907ed1b5d9cd55a3b21f46c207217af8a4efe0fe6ccb56a8f988567fc27395", - "openapi/markdown/downloadFile.md": "828154a446933bd19b1f20ca9170f6e93f2f80872fc08e92e46d339872e8f45c", - "openapi/markdown/forkSandbox.md": "84962addf6f2d49e40aaaca2e27f79e8e98991f703c7374e8852d4e47944dbc4", - "openapi/markdown/getEnvironmentHealth.md": "7595329f0fceb5ba613d73f8c522287f7836651d9a2dc44002a149c3ca8c57bf", - "openapi/markdown/getEnvironmentMetrics.md": "d6ebfaa682e3e2b6489703daf643b887362f5fdca055f9f3b2367143b03a5112", - "openapi/markdown/getEnvironmentVariables.md": "58fe720040afa68bc542c0416378bab9642dbfe73d397b923b220e44bb4c2f54", - "openapi/markdown/getSandbox.md": "fb4a7184f903a8bdd8c3b7ea1d00b10d17d26c6dc56b1e7f1a07f91f99aee09d", - "openapi/markdown/getSandboxLogs.md": "a3055767e82145d9c0cb1953ee1081489c0098200018802292634e4cb3c830c2", - "openapi/markdown/getSandboxMetrics.md": "1572d44d0ff539495dadcbb909bb1e640b73375fcb4b0840243e692066162ace", - "openapi/markdown/getTeamMetrics.md": "063860650df86f09f1119f441b1410b1e329dd20000cf1b1f8a1f84fdcbdac53", - "openapi/markdown/getTeamMetricsMax.md": "5e5e6578470d1710c993ae69a91b34badaaa86e62e141eb91e57c6e0f7594fe6", - "openapi/markdown/getTemplate.md": "a4747e42b28bb014ae4eb3b5477fe6d58cfda25c00ae829c339cfb7ef5ec6715", - "openapi/markdown/getTemplateBuildLogs.md": "5f696d204a13be42ce9df32b51ac4680b853231595d84e14aca9db7e05b385ff", - "openapi/markdown/getTemplateBuildStatus.md": "7ef1697ca9b6c3d44624df8ca528fdc5e4f81ebd226c748ae2183b2e99e27757", - "openapi/markdown/getTemplateByAlias.md": "2a42010266038d50581e3526becf1f35ad3ada6eecd757522b083817fe435301", - "openapi/markdown/getTemplateUploadUrl.md": "b06cb4aaed389e75daa8e509e3437a23915aad2b03ef6e69597df67984a48b19", - "openapi/markdown/killSandbox.md": "c864528a36849a512be77bf144ef7d41356f01cb0dbbe1d2f5143712a95268f2", - "openapi/markdown/listSandboxMetrics.md": "38cc35b6d1087635efc6fa351da48402a021f12b185e3bbfbafacc64a34b8d87", - "openapi/markdown/listSandboxes.md": "ebb79c21ab83ad61ea2e7c738fa2f77d37c001e2d09142508209e7beab687aeb", - "openapi/markdown/listSnapshots.md": "d7f7ae67491c5da2930181b0fe423ef8ad661f5f4e7e88f47ecfb58cb08ac83f", - "openapi/markdown/listTemplateTags.md": "df27ed0dc04e6b49a3dc92704842e30365f50e88c8e28e6a5323a16aa10b7c45", - "openapi/markdown/listTemplates.md": "e89b7d18efcfa6e16385e6b4e2f227ad2e5c9fa7608426ece673077a35468e12", - "openapi/markdown/pauseSandbox.md": "0d1e7dd52ca966d37742e7d34898559dfd03c4ba3ca7f83f1859ddaefa9b0464", - "openapi/markdown/refreshSandbox.md": "dea1862241aad45c17b194994722a23941263bb697b885e795ba97cf154469bd", - "openapi/markdown/setSandboxTimeout.md": "ee0aaf78e2c0ffcdf4df1bde703fd4442d5436efad290bc235d1acc120adb997", - "openapi/markdown/startTemplateBuild.md": "f987c7627a0170ff2908fd344d76acea3b2d8f7875686ff746ad8a8b2b3922c4", - "openapi/markdown/updateSandboxNetwork.md": "0254acd4dca8299bd7198024660bb1300752c6842f225c604389dd1951333675", - "openapi/markdown/updateTemplate.md": "ace7930be4091213fc2e29a7109f489eaaf3a0e1d210aa65d9663a5adbf92250", - "openapi/markdown/uploadFile.md": "2c3b042f305f2e7234799f0af14979965e76a10ced1a74a464bb6afd96c5c68c", + "openapi/markdown/assignTemplateTags.md": "d537a5123d8d2f6a6e5bc533db96d530e372b8aa4a6dbad3808904ca59e232fb", + "openapi/markdown/composeFiles.md": "208ca29c5143720389bc82db267aa8aaa2e8e7780e8a6cd5c9e11717bb44c84a", + "openapi/markdown/connectSandbox.md": "a49c231cbfaeba9f6363c3d053e2aacd6fa55b19543251394c88f234a9f992e9", + "openapi/markdown/createSandbox.md": "2c318c95e7c97747d968ce7a764f833f4632e9b0cea00a13bceb3d579356e418", + "openapi/markdown/createSnapshot.md": "1af5dcb96e3217dfc98a54eb43cc721cdd58f875f88bd77cde0b4fe34df0cb0d", + "openapi/markdown/createTemplate.md": "1a8b379df9e0e03c7b1c1fe0308d693dc09e589c3d474ee521d71fe556a96db2", + "openapi/markdown/deleteTemplate.md": "c0dff20f19cb6d8958f8ee859154f9a2508bb0da6c6a4f8bdb517fd275974e83", + "openapi/markdown/deleteTemplateTags.md": "468d6c2299f22c0be084edbc0f248fcf28cdd671a8551a30433ad28081e22f8d", + "openapi/markdown/downloadFile.md": "b116ab967ca2d42bcadf8e2c2db90d90686126b58fe7275efc6e2df09fa45745", + "openapi/markdown/forkSandbox.md": "4af6d08cb5897c424118b043ab0b6bb8e176926cf3a8f2e94ede685915086592", + "openapi/markdown/getEnvironmentHealth.md": "e340276ca13456d2feee70f7d68f2b9b58a8efaac792c0845cf328988674e500", + "openapi/markdown/getEnvironmentMetrics.md": "5a86cbd31c9fcdd2aa468a708527e8935d276ca2af4a33cb7d431f347b972a3a", + "openapi/markdown/getEnvironmentVariables.md": "e9f9dba427ff7cb37aad0a7fd248e57e68d0f09235755689fb4f0f3bd0898171", + "openapi/markdown/getSandbox.md": "b4114feed35bac9cf566e9031e4393b6b74a8b0295cb991334c84e24cb24212b", + "openapi/markdown/getSandboxLogs.md": "92b387304e1635507fb734ea2381442b02692788cc5bcaef029501517459823a", + "openapi/markdown/getSandboxMetrics.md": "7dfe5a9f4349cf4721870190dc4dfb709f1abea827c48c421b252db37842e059", + "openapi/markdown/getTeamMetrics.md": "43c9ea28cf683e7cb90ba3ba73b2295d412ac571ad3969fe207c284eaedb9f5b", + "openapi/markdown/getTeamMetricsMax.md": "f1fb70b4b96926d15b6b2da15a3a3385e3ce6d3625739690e3ac261522b7a66b", + "openapi/markdown/getTemplate.md": "2b9860253eea9a9c70efc7b09afe4bb46a77b47d615e37ebe816fb30443277b3", + "openapi/markdown/getTemplateBuildLogs.md": "9ac9b52688a7c2b18e2cb1463ffaace332f3912675a7418e948aa03114ef1282", + "openapi/markdown/getTemplateBuildStatus.md": "7c49468fd4dc545151785d74b7bf3d7a4f81cd3652f2a94ea4bdca34d2f1a030", + "openapi/markdown/getTemplateByAlias.md": "2a45d21244f6416182a4b4c44df7e912c63531bf191a52f92ca72579ef889bca", + "openapi/markdown/getTemplateUploadUrl.md": "2913bbd4444042dae3e0fc3bdb8b93619499885c9037021b1d025d149d0eaa14", + "openapi/markdown/killSandbox.md": "8d552c09878a176f3337456fa1506c8c8ce494e49cd66fc550210ed4d56b3876", + "openapi/markdown/listSandboxMetrics.md": "12aa00b1ab43fd7d3ed305484d1cf0e8abe2b76fe8198eb43082b1c9b56bf95c", + "openapi/markdown/listSandboxes.md": "f6d2112f7e80864cbca32b55e10ad64ac4744854e6e55fa7df88820e6e89958d", + "openapi/markdown/listSnapshots.md": "a0b9150b60a0d392bf928c72202d5c1283a0d7f110b8a569771b89807129c894", + "openapi/markdown/listTemplateTags.md": "2fe73787ba32d2049a425377462dacbca9b80b36ec6551815eec3e987d135413", + "openapi/markdown/listTemplates.md": "0b3f649933c0f2fdfd3f1edec3dc3995053edc3e4f9babb902bd9c591b1b640a", + "openapi/markdown/pauseSandbox.md": "d33a86ed2c8c48c9a1c81ac5e80dfa244fb92b1ff8ef2cdddfefc2f8270949d7", + "openapi/markdown/refreshSandbox.md": "9f8580277cd6ffd79c2313f8688ed796916c2d457a19355094efcce72fa4207d", + "openapi/markdown/setSandboxTimeout.md": "3474378751522f5ad93035aafcc0b74221ebdd3e76c04a7c0a2d9c8f241fa228", + "openapi/markdown/startTemplateBuild.md": "bd1d7c7347453247d6a14e871c5697333fc47b8369d7c9edace518083cb41917", + "openapi/markdown/updateSandboxNetwork.md": "20e9cd1722fbf1e0af5f1a925ef8e64b27ce98a26afba6fc1d6cdafd96f0e444", + "openapi/markdown/updateTemplate.md": "f067cc266d8eddeab02fb70f548703ec44f187ca9c3b79c9a908d71a14e067f9", + "openapi/markdown/uploadFile.md": "3a3b5ebadf3282a18f90d58a220152aea0eba9eb5ad455ac89483a0acc44e8c7", "openapi/operations.json": "f5097d93fb7eb5f6482e632624d5a212e29441ef8c558601ccbe2dae26db050d", "sdk/cli/auth.md": "0b2c75262b0c0670c7bc0f0f3cbed65fbe4a16d6fe4437789a5685b8bf2174a1", "sdk/cli/sandbox.md": "16b64c5a4e932eca2452e400e0faf154eba1d3c7373513aa7cd9744e02908313", diff --git a/reference/openapi/markdown/assignTemplateTags.md b/reference/openapi/markdown/assignTemplateTags.md index 6dbc575f..0368007b 100644 --- a/reference/openapi/markdown/assignTemplateTags.md +++ b/reference/openapi/markdown/assignTemplateTags.md @@ -38,6 +38,8 @@ Schema: `AssignedTemplateTags` Identifier of the build associated with these tags + Format: `uuid` + ### 400 Bad request @@ -50,6 +52,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -66,6 +70,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -82,6 +88,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -98,6 +106,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/composeFiles.md b/reference/openapi/markdown/composeFiles.md index 2340aee4..d199fb3a 100644 --- a/reference/openapi/markdown/composeFiles.md +++ b/reference/openapi/markdown/composeFiles.md @@ -12,6 +12,8 @@ Compose multiple files into a single file using zero-copy concatenation. Source Internal envd HTTP port exposed through the sandbox proxy. + Default: `49983` + ## Request body Required: yes @@ -54,6 +56,8 @@ Schema: `EntryInfo` Type of the file + Allowed values: `file` + - **`metadata`** · `object` · optional User-defined metadata stored as extended attributes on the file. diff --git a/reference/openapi/markdown/connectSandbox.md b/reference/openapi/markdown/connectSandbox.md index b71e7204..45b5a2a2 100644 --- a/reference/openapi/markdown/connectSandbox.md +++ b/reference/openapi/markdown/connectSandbox.md @@ -20,6 +20,10 @@ Schema: `ConnectSandbox` Timeout in seconds from the current time after which the sandbox should expire + Format: `int32` + + Minimum: `0` + ## Responses ### 200 @@ -90,6 +94,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -106,6 +112,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -122,6 +130,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -138,6 +148,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/createSandbox.md b/reference/openapi/markdown/createSandbox.md index d46fb429..f5f60c24 100644 --- a/reference/openapi/markdown/createSandbox.md +++ b/reference/openapi/markdown/createSandbox.md @@ -20,14 +20,24 @@ Schema: `NewSandbox` Time to live for the sandbox in seconds. + Format: `int32` + + Default: `15` + + Minimum: `0` + - **`autoPause`** · `boolean` · optional Automatically pauses the sandbox after the timeout + Default: `false` + - **`autoPauseMemory`** · `boolean` · optional Controls the snapshot kind taken when the sandbox auto-pauses on timeout (only relevant when autoPause is true). When false, the auto-pause drops the in-memory state and persists only the filesystem (a filesystem-only snapshot); resuming it cold-boots (reboots) the sandbox from disk. Such a snapshot cannot be auto-resumed by traffic and must be resumed explicitly, so it cannot be combined with autoResume. Defaults to true (full memory snapshot). + Default: `true` + - **`autoResume`** · `SandboxAutoResumeConfig` · optional Auto-resume configuration for paused sandboxes. @@ -36,6 +46,8 @@ Schema: `NewSandbox` Auto-resume enabled flag for paused sandboxes. Default false. + Default: `false` + - **`secure`** · `boolean` · optional Secure all system communication with sandbox @@ -50,6 +62,8 @@ Schema: `NewSandbox` Specify if the sandbox URLs should be accessible only with authentication. + Default: `true` + - **`network.allowOut`** · `array` · optional List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. @@ -156,6 +170,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -172,6 +188,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -188,6 +206,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/createSnapshot.md b/reference/openapi/markdown/createSnapshot.md index 988c1b8f..b41c5841 100644 --- a/reference/openapi/markdown/createSnapshot.md +++ b/reference/openapi/markdown/createSnapshot.md @@ -50,6 +50,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -66,6 +68,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -82,6 +86,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -98,6 +104,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/createTemplate.md b/reference/openapi/markdown/createTemplate.md index a8c4c5c0..916b99e0 100644 --- a/reference/openapi/markdown/createTemplate.md +++ b/reference/openapi/markdown/createTemplate.md @@ -16,6 +16,8 @@ Schema: `TemplateBuildRequestV3` Name of the template. Can include a tag with colon separator (e.g. "my-template" or "my-template:v1"). If tag is included, it will be treated as if the tag was provided in the tags array. + Maximum length: `128` + - **`tags`** · `array` · optional Tags to assign to the template build @@ -24,10 +26,18 @@ Schema: `TemplateBuildRequestV3` CPU cores for the sandbox + Format: `int32` + + Minimum: `1` + - **`memoryMB`** · `MemoryMB` · optional Memory for the sandbox in MiB + Format: `int32` + + Minimum: `128` + ## Responses ### 202 @@ -70,6 +80,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -86,6 +98,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -102,6 +116,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -118,6 +134,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/deleteTemplate.md b/reference/openapi/markdown/deleteTemplate.md index 8b623956..61f98ffb 100644 --- a/reference/openapi/markdown/deleteTemplate.md +++ b/reference/openapi/markdown/deleteTemplate.md @@ -26,6 +26,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -42,6 +44,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/deleteTemplateTags.md b/reference/openapi/markdown/deleteTemplateTags.md index 4f8cba8b..c412a253 100644 --- a/reference/openapi/markdown/deleteTemplateTags.md +++ b/reference/openapi/markdown/deleteTemplateTags.md @@ -38,6 +38,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -54,6 +56,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -70,6 +74,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -86,6 +92,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/downloadFile.md b/reference/openapi/markdown/downloadFile.md index 623bd08c..f38448de 100644 --- a/reference/openapi/markdown/downloadFile.md +++ b/reference/openapi/markdown/downloadFile.md @@ -12,6 +12,8 @@ Download a file Internal envd HTTP port exposed through the sandbox proxy. + Default: `49983` + - **`path`** · `string` · query · optional Path to the file, URL encoded. Can be relative to the user's home directory (e.g. "file.txt" resolves to ~/file.txt). @@ -38,6 +40,10 @@ Content-Type: `application/octet-stream` Schema: `string` +The raw file content + +Format: `binary` + ### 400 Invalid path diff --git a/reference/openapi/markdown/forkSandbox.md b/reference/openapi/markdown/forkSandbox.md index ac54903d..7ccf3a9a 100644 --- a/reference/openapi/markdown/forkSandbox.md +++ b/reference/openapi/markdown/forkSandbox.md @@ -20,10 +20,24 @@ Schema: `SandboxForkRequest` Time to live for the new forked sandboxes in seconds. + Format: `int32` + + Default: `15` + + Minimum: `0` + - **`count`** · `integer` · optional Number of forked sandboxes to create. All forks boot from the same snapshot, so the snapshot is captured once regardless of count. Each fork succeeds or fails independently; the outcome of each is reported in its entry of the response list. + Format: `int32` + + Default: `1` + + Minimum: `1` + + Maximum: `100` + ## Responses ### 201 @@ -62,6 +76,8 @@ Schema: `array` Error code + Format: `int32` + - **`error.message`** · `string` · required Error @@ -78,6 +94,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -94,6 +112,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -110,6 +130,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -126,6 +148,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getEnvironmentHealth.md b/reference/openapi/markdown/getEnvironmentHealth.md index 77e535de..d2fcc5f2 100644 --- a/reference/openapi/markdown/getEnvironmentHealth.md +++ b/reference/openapi/markdown/getEnvironmentHealth.md @@ -12,6 +12,8 @@ Check the health of the service Internal envd HTTP port exposed through the sandbox proxy. + Default: `49983` + ## Responses ### 204 diff --git a/reference/openapi/markdown/getEnvironmentMetrics.md b/reference/openapi/markdown/getEnvironmentMetrics.md index cceaeb96..7526597a 100644 --- a/reference/openapi/markdown/getEnvironmentMetrics.md +++ b/reference/openapi/markdown/getEnvironmentMetrics.md @@ -12,6 +12,8 @@ Service stats Internal envd HTTP port exposed through the sandbox proxy. + Default: `49983` + ## Responses ### 200 @@ -22,10 +24,14 @@ Content-Type: `application/json` Schema: `Metrics` +Resource usage metrics + - **`ts`** · `integer` · optional Unix timestamp in UTC for current sandbox time + Format: `int64` + - **`cpu_count`** · `integer` · optional Number of CPU cores @@ -34,6 +40,8 @@ Schema: `Metrics` CPU usage percentage + Format: `float` + - **`mem_total`** · `integer` · optional Total virtual memory in bytes diff --git a/reference/openapi/markdown/getEnvironmentVariables.md b/reference/openapi/markdown/getEnvironmentVariables.md index 2f59bd84..e5801669 100644 --- a/reference/openapi/markdown/getEnvironmentVariables.md +++ b/reference/openapi/markdown/getEnvironmentVariables.md @@ -12,6 +12,8 @@ Environment variables Internal envd HTTP port exposed through the sandbox proxy. + Default: `49983` + ## Responses ### 200 @@ -22,4 +24,6 @@ Content-Type: `application/json` Schema: `EnvVars` +Environment variables to set + - **`*`** · `string` · additional property diff --git a/reference/openapi/markdown/getSandbox.md b/reference/openapi/markdown/getSandbox.md index f9855300..8f641069 100644 --- a/reference/openapi/markdown/getSandbox.md +++ b/reference/openapi/markdown/getSandbox.md @@ -34,10 +34,14 @@ Schema: `SandboxDetail` Time when the sandbox was started + Format: `date-time` + - **`endAt`** · `string` · required Time when the sandbox will expire + Format: `date-time` + - **`envdVersion`** · `EnvdVersion` · required Version of the envd running in the sandbox @@ -54,14 +58,26 @@ Schema: `SandboxDetail` CPU cores for the sandbox + Format: `int32` + + Minimum: `1` + - **`memoryMB`** · `MemoryMB` · required Memory for the sandbox in MiB + Format: `int32` + + Minimum: `128` + - **`diskSizeMB`** · `DiskSizeMB` · required Disk size for the sandbox in MiB + Format: `int32` + + Minimum: `0` + - **`metadata`** · `SandboxMetadata` · optional - **`metadata.*`** · `string` · additional property @@ -72,12 +88,16 @@ Schema: `SandboxDetail` State of the sandbox + Allowed values for `SandboxState`: `running` | `paused` + - **`network`** · `SandboxNetworkConfig` · optional - **`network.allowPublicTraffic`** · `boolean` · optional Specify if the sandbox URLs should be accessible only with authentication. + Default: `true` + - **`network.allowOut`** · `array` · optional List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. @@ -118,6 +138,8 @@ Schema: `SandboxDetail` Action taken when the sandbox times out. + Allowed values for `SandboxOnTimeout`: `kill` | `pause` + ### 404 Not found @@ -130,6 +152,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -146,6 +170,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -162,6 +188,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getSandboxLogs.md b/reference/openapi/markdown/getSandboxLogs.md index 3ad2b4aa..a26fe7ec 100644 --- a/reference/openapi/markdown/getSandboxLogs.md +++ b/reference/openapi/markdown/getSandboxLogs.md @@ -12,26 +12,46 @@ Get sandbox logs Opaque continuation cursor returned as nextCursor by the previous page + Maximum length: `512` + - **`cursor`** · `integer` · query · optional Starting timestamp of the logs that should be returned in milliseconds + Format: `int64` + + Minimum: `0` + - **`limit`** · `integer` · query · optional Maximum number of logs that should be returned + Format: `int32` + + Default: `1000` + + Minimum: `0` + + Maximum: `1000` + - **`direction`** · `LogsDirection` · query · optional Direction of the logs that should be returned + Allowed values for `LogsDirection`: `forward` | `backward` + - **`level`** · `LogLevel` · query · optional Minimum log level to return. Logs below this level are excluded + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`search`** · `string` · query · optional Case-sensitive substring match on log message content + Maximum length: `256` + ## Responses ### 200 @@ -54,6 +74,8 @@ Schema: `SandboxLogsV2Response` Timestamp of the log entry + Format: `date-time` + - **`logs.message`** · `string` · required Log message content @@ -62,6 +84,8 @@ Schema: `SandboxLogsV2Response` State of the sandbox + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`logs.fields`** · `object` · required - **`logs.fields.*`** · `string` · additional property @@ -82,6 +106,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -98,6 +124,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -114,6 +142,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getSandboxMetrics.md b/reference/openapi/markdown/getSandboxMetrics.md index 602a6f1c..96cdec23 100644 --- a/reference/openapi/markdown/getSandboxMetrics.md +++ b/reference/openapi/markdown/getSandboxMetrics.md @@ -12,8 +12,16 @@ Get sandbox metrics Unix timestamp for the start of the interval, in seconds, for which the metrics + Format: `int64` + + Minimum: `0` + - **`end`** · `integer` · query · optional + Format: `int64` + + Minimum: `0` + ## Responses ### 200 @@ -28,34 +36,50 @@ Schema: `array` Timestamp of the metric entry in Unix time (seconds since epoch) + Format: `int64` + - **`cpuCount`** · `integer` · required Number of CPU cores + Format: `int32` + - **`cpuUsedPct`** · `number` · required CPU usage percentage + Format: `float` + - **`memUsed`** · `integer` · required Memory used in bytes + Format: `int64` + - **`memTotal`** · `integer` · required Total memory in bytes + Format: `int64` + - **`memCache`** · `integer` · required Cached memory (page cache) in bytes + Format: `int64` + - **`diskUsed`** · `integer` · required Disk used in bytes + Format: `int64` + - **`diskTotal`** · `integer` · required Total disk space in bytes + Format: `int64` + ### 400 Bad request @@ -68,6 +92,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -84,6 +110,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -100,6 +128,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -116,6 +146,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTeamMetrics.md b/reference/openapi/markdown/getTeamMetrics.md index a18919cc..8355f49b 100644 --- a/reference/openapi/markdown/getTeamMetrics.md +++ b/reference/openapi/markdown/getTeamMetrics.md @@ -12,8 +12,16 @@ Get metrics for the team Unix timestamp for the start of the interval, in seconds, for which the metrics + Format: `int64` + + Minimum: `0` + - **`end`** · `integer` · query · optional + Format: `int64` + + Minimum: `0` + ## Responses ### 200 @@ -28,14 +36,20 @@ Schema: `array` Timestamp of the metric entry in Unix time (seconds since epoch) + Format: `int64` + - **`concurrentSandboxes`** · `integer` · required The number of concurrent sandboxes for the team + Format: `int32` + - **`sandboxStartRate`** · `number` · required Number of sandboxes started per second + Format: `float` + ### 400 Bad request @@ -48,6 +62,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -64,6 +80,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -80,6 +98,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -96,6 +116,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTeamMetricsMax.md b/reference/openapi/markdown/getTeamMetricsMax.md index cfe44d32..27df2b87 100644 --- a/reference/openapi/markdown/getTeamMetricsMax.md +++ b/reference/openapi/markdown/getTeamMetricsMax.md @@ -12,12 +12,22 @@ Get the maximum metrics for the team in the given interval Unix timestamp for the start of the interval, in seconds, for which the metrics + Format: `int64` + + Minimum: `0` + - **`end`** · `integer` · query · optional + Format: `int64` + + Minimum: `0` + - **`metric`** · `concurrent_sandboxes | sandbox_start_rate` · query · required Metric to retrieve the maximum value for + Allowed values: `concurrent_sandboxes` | `sandbox_start_rate` + ## Responses ### 200 @@ -28,10 +38,14 @@ Content-Type: `application/json` Schema: `MaxTeamMetric` +Team metric with timestamp + - **`timestampUnix`** · `integer` · required Timestamp of the metric entry in Unix time (seconds since epoch) + Format: `int64` + - **`value`** · `number` · required The maximum value of the requested metric in the given interval @@ -48,6 +62,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -64,6 +80,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -80,6 +98,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -96,6 +116,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTemplate.md b/reference/openapi/markdown/getTemplate.md index e08d63fa..a6e07357 100644 --- a/reference/openapi/markdown/getTemplate.md +++ b/reference/openapi/markdown/getTemplate.md @@ -16,12 +16,26 @@ List all builds for a template Maximum number of items to return per page + Format: `int32` + + Default: `100` + + Minimum: `1` + + Maximum: `100` + ## Responses ### 200 Successfully returned the template with its builds +#### Response headers + +- **`X-Next-Token`** · `string` · response header + + Cursor to fetch the next page of results, if more exist + Content-Type: `application/json` Schema: `TemplateWithBuilds` @@ -42,18 +56,26 @@ Schema: `TemplateWithBuilds` Time when the template was created + Format: `date-time` + - **`updatedAt`** · `string` · required Time when the template was last updated + Format: `date-time` + - **`lastSpawnedAt`** · `string` · required Time when the template was last used + Format: `date-time` + - **`spawnCount`** · `integer` · required Number of times the template was used + Format: `int64` + - **`builds`** · `array` · required List of builds for the template @@ -62,34 +84,56 @@ Schema: `TemplateWithBuilds` Identifier of the build + Format: `uuid` + - **`builds.status`** · `TemplateBuildStatus` · required Status of the template build + Allowed values for `TemplateBuildStatus`: `building` | `waiting` | `ready` | `error` + - **`builds.createdAt`** · `string` · required Time when the build was created + Format: `date-time` + - **`builds.updatedAt`** · `string` · required Time when the build was last updated + Format: `date-time` + - **`builds.finishedAt`** · `string` · optional Time when the build was finished + Format: `date-time` + - **`builds.cpuCount`** · `CPUCount` · required CPU cores for the sandbox + Format: `int32` + + Minimum: `1` + - **`builds.memoryMB`** · `MemoryMB` · required Memory for the sandbox in MiB + Format: `int32` + + Minimum: `128` + - **`builds.diskSizeMB`** · `DiskSizeMB` · optional Disk size for the sandbox in MiB + Format: `int32` + + Minimum: `0` + - **`builds.envdVersion`** · `EnvdVersion` · optional Version of the envd running in the sandbox @@ -106,6 +150,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -122,6 +168,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTemplateBuildLogs.md b/reference/openapi/markdown/getTemplateBuildLogs.md index 5db43d2c..47b18d60 100644 --- a/reference/openapi/markdown/getTemplateBuildLogs.md +++ b/reference/openapi/markdown/getTemplateBuildLogs.md @@ -14,22 +14,42 @@ Get template build logs Opaque continuation cursor returned as nextCursor by the previous page + Maximum length: `512` + - **`cursor`** · `integer` · query · optional Starting timestamp of the logs that should be returned in milliseconds + Format: `int64` + + Minimum: `0` + - **`limit`** · `integer` · query · optional Maximum number of logs that should be returned + Format: `int32` + + Default: `100` + + Minimum: `0` + + Maximum: `100` + - **`direction`** · `LogsDirection` · query · optional + Allowed values for `LogsDirection`: `forward` | `backward` + - **`level`** · `LogLevel` · query · optional + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`source`** · `LogsSource` · query · optional Source of the logs that should be returned from + Allowed values for `LogsSource`: `temporary` | `persistent` + ## Responses ### 200 @@ -52,6 +72,8 @@ Schema: `TemplateBuildLogsResponse` Timestamp of the log entry + Format: `date-time` + - **`logs.message`** · `string` · required Log message content @@ -60,6 +82,8 @@ Schema: `TemplateBuildLogsResponse` State of the sandbox + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`logs.step`** · `string` · optional Step in the build process related to the log entry @@ -72,6 +96,8 @@ Schema: `TemplateBuildLogsResponse` Source of the logs that should be returned + Allowed values for `LogsSource`: `temporary` | `persistent` + ### 401 Authentication error @@ -84,6 +110,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -100,6 +128,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -116,6 +146,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTemplateBuildStatus.md b/reference/openapi/markdown/getTemplateBuildStatus.md index c2316648..29bbdedc 100644 --- a/reference/openapi/markdown/getTemplateBuildStatus.md +++ b/reference/openapi/markdown/getTemplateBuildStatus.md @@ -14,12 +14,28 @@ Get template build info Index of the starting build log that should be returned with the template + Format: `int32` + + Default: `0` + + Minimum: `0` + - **`limit`** · `integer` · query · optional Maximum number of logs that should be returned + Format: `int32` + + Default: `100` + + Minimum: `0` + + Maximum: `100` + - **`level`** · `LogLevel` · query · optional + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + ## Responses ### 200 @@ -46,6 +62,8 @@ Schema: `TemplateBuildInfo` Timestamp of the log entry + Format: `date-time` + - **`logEntries.message`** · `string` · required Log message content @@ -54,6 +72,8 @@ Schema: `TemplateBuildInfo` State of the sandbox + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`logEntries.step`** · `string` · optional Step in the build process related to the log entry @@ -70,6 +90,8 @@ Schema: `TemplateBuildInfo` Status of the template build + Allowed values for `TemplateBuildStatus`: `building` | `waiting` | `ready` | `error` + - **`reason`** · `BuildStatusReason` · optional - **`reason.message`** · `string` · required @@ -92,6 +114,8 @@ Schema: `TemplateBuildInfo` Timestamp of the log entry + Format: `date-time` + - **`reason.logEntries.message`** · `string` · required Log message content @@ -100,6 +124,8 @@ Schema: `TemplateBuildInfo` State of the sandbox + Allowed values for `LogLevel`: `debug` | `info` | `warn` | `error` + - **`reason.logEntries.step`** · `string` · optional Step in the build process related to the log entry @@ -116,6 +142,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -132,6 +160,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -148,6 +178,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTemplateByAlias.md b/reference/openapi/markdown/getTemplateByAlias.md index 1999b7bf..4a6675ba 100644 --- a/reference/openapi/markdown/getTemplateByAlias.md +++ b/reference/openapi/markdown/getTemplateByAlias.md @@ -38,6 +38,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -54,6 +56,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -70,6 +74,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -86,6 +92,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/getTemplateUploadUrl.md b/reference/openapi/markdown/getTemplateUploadUrl.md index 84cb6f66..23b4e8cd 100644 --- a/reference/openapi/markdown/getTemplateUploadUrl.md +++ b/reference/openapi/markdown/getTemplateUploadUrl.md @@ -40,6 +40,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -56,6 +58,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -72,6 +76,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -88,6 +94,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/killSandbox.md b/reference/openapi/markdown/killSandbox.md index 01401f83..73abee4d 100644 --- a/reference/openapi/markdown/killSandbox.md +++ b/reference/openapi/markdown/killSandbox.md @@ -26,6 +26,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -42,6 +44,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -58,6 +62,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/listSandboxMetrics.md b/reference/openapi/markdown/listSandboxMetrics.md index 77dfd3ab..fde59439 100644 --- a/reference/openapi/markdown/listSandboxMetrics.md +++ b/reference/openapi/markdown/listSandboxMetrics.md @@ -30,34 +30,50 @@ Schema: `SandboxesWithMetrics` Timestamp of the metric entry in Unix time (seconds since epoch) + Format: `int64` + - **`sandboxes.*.cpuCount`** · `integer` · required Number of CPU cores + Format: `int32` + - **`sandboxes.*.cpuUsedPct`** · `number` · required CPU usage percentage + Format: `float` + - **`sandboxes.*.memUsed`** · `integer` · required Memory used in bytes + Format: `int64` + - **`sandboxes.*.memTotal`** · `integer` · required Total memory in bytes + Format: `int64` + - **`sandboxes.*.memCache`** · `integer` · required Cached memory (page cache) in bytes + Format: `int64` + - **`sandboxes.*.diskUsed`** · `integer` · required Disk used in bytes + Format: `int64` + - **`sandboxes.*.diskTotal`** · `integer` · required Total disk space in bytes + Format: `int64` + ### 401 Authentication error @@ -70,6 +86,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -86,6 +104,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -102,6 +122,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/listSandboxes.md b/reference/openapi/markdown/listSandboxes.md index 1160874b..a6b4dda6 100644 --- a/reference/openapi/markdown/listSandboxes.md +++ b/reference/openapi/markdown/listSandboxes.md @@ -14,6 +14,8 @@ List all sandboxes Filter sandboxes by one or more states + Allowed values for `SandboxState`: `running` | `paused` + - **`nextToken`** · `string` · query · optional Cursor to start the list from @@ -22,12 +24,32 @@ List all sandboxes Maximum number of items to return per page + Format: `int32` + + Default: `100` + + Minimum: `1` + + Maximum: `100` + ## Responses ### 200 Successfully returned all running sandboxes +#### Response headers + +- **`X-Next-Token`** · `string` · response header + + Cursor to fetch the next page of results, if more exist + +- **`X-Total-Running`** · `integer` · response header + + Number of running sandboxes matching the filters, before pagination is applied. Only present when running sandboxes were requested. + + Format: `int32` + Content-Type: `application/json` Schema: `array` @@ -48,22 +70,38 @@ Schema: `array` Time when the sandbox was started + Format: `date-time` + - **`endAt`** · `string` · required Time when the sandbox will expire + Format: `date-time` + - **`cpuCount`** · `CPUCount` · required CPU cores for the sandbox + Format: `int32` + + Minimum: `1` + - **`memoryMB`** · `MemoryMB` · required Memory for the sandbox in MiB + Format: `int32` + + Minimum: `128` + - **`diskSizeMB`** · `DiskSizeMB` · required Disk size for the sandbox in MiB + Format: `int32` + + Minimum: `0` + - **`metadata`** · `SandboxMetadata` · optional - **`metadata.*`** · `string` · additional property @@ -74,6 +112,8 @@ Schema: `array` State of the sandbox + Allowed values for `SandboxState`: `running` | `paused` + - **`envdVersion`** · `EnvdVersion` · required Version of the envd running in the sandbox @@ -90,6 +130,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -106,6 +148,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -122,6 +166,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/listSnapshots.md b/reference/openapi/markdown/listSnapshots.md index 5fddbcf0..8643df1f 100644 --- a/reference/openapi/markdown/listSnapshots.md +++ b/reference/openapi/markdown/listSnapshots.md @@ -16,6 +16,14 @@ List all snapshots for the team Maximum number of items to return per page + Format: `int32` + + Default: `100` + + Minimum: `1` + + Maximum: `100` + - **`nextToken`** · `string` · query · optional Cursor to start the list from @@ -26,6 +34,12 @@ List all snapshots for the team Successfully returned snapshots +#### Response headers + +- **`X-Next-Token`** · `string` · response header + + Cursor to fetch the next page of results, if more exist + Content-Type: `application/json` Schema: `array` @@ -50,6 +64,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -66,6 +82,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/listTemplateTags.md b/reference/openapi/markdown/listTemplateTags.md index c4440abb..3ad49f58 100644 --- a/reference/openapi/markdown/listTemplateTags.md +++ b/reference/openapi/markdown/listTemplateTags.md @@ -26,10 +26,14 @@ Schema: `array` Identifier of the build associated with this tag + Format: `uuid` + - **`createdAt`** · `string` · required Time when the tag was assigned + Format: `date-time` + ### 401 Authentication error @@ -42,6 +46,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -58,6 +64,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -74,6 +82,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error @@ -90,6 +100,8 @@ Schema: `Error` Error code + Format: `int32` + - **`message`** · `string` · required Error diff --git a/reference/openapi/markdown/listTemplates.md b/reference/openapi/markdown/listTemplates.md index cfa70e70..d9e643f8 100644 --- a/reference/openapi/markdown/listTemplates.md +++ b/reference/openapi/markdown/listTemplates.md @@ -16,12 +16,26 @@ List all templates Maximum number of items to return per page + Format: `int32` + + Default: `100` + + Minimum: `1` + + Maximum: `100` + ## Responses ### 200 Successfully returned all templates +#### Response headers + +- **`X-Next-Token`** · `string` · response header + + Cursor to fetch the next page of results, if more exist + Content-Type: `application/json` Schema: `array