From b6eaee0031009eb7bbea3af324f1008e9ce1fb6a Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Mon, 31 Aug 2026 14:27:42 +0300 Subject: [PATCH 1/3] docs: generate public SDK reference contract --- .dockerignore | 2 + Makefile | 2 + README.md | 2 +- codegen.Dockerfile | 4 + package.json | 3 + packages/cli/package.json | 5 +- packages/cli/src/index.ts | 11 - packages/cli/src/reference.ts | 11 + packages/cli/src/utils/commands2md.ts | 138 +- packages/code-interpreter-js/README.md | 2 +- packages/code-interpreter-python/README.md | 2 +- .../code-interpreter-python/pyproject.toml | 2 +- packages/js-sdk/README.md | 2 +- packages/python-sdk/README.md | 2 +- packages/python-sdk/pyproject.toml | 2 +- pnpm-lock.yaml | 358 +- reference-config/operations.yaml | 50 + reference-config/sdk-groups.json | 34 + reference/connect/filesystem.md | 205 ++ reference/connect/process.md | 244 ++ reference/manifest.json | 163 + reference/openapi/control-plane.yml | 3126 +++++++++++++++++ reference/openapi/envd.yml | 435 +++ reference/openapi/operations.json | 290 ++ reference/sdk/cli/auth.md | 16 + reference/sdk/cli/sandbox.md | 214 ++ reference/sdk/cli/template.md | 63 + .../sdk/javascript/code-interpreter/README.md | 7 + .../code-interpreter/charts/README.md | 27 + .../charts/enumerations/ChartType.md | 47 + .../charts/enumerations/ScaleType.md | 59 + .../charts/functions/deserializeChart.md | 15 + .../charts/type-aliases/BarChart.md | 15 + .../charts/type-aliases/BarData.md | 23 + .../charts/type-aliases/BoxAndWhiskerChart.md | 15 + .../charts/type-aliases/BoxAndWhiskerData.md | 47 + .../charts/type-aliases/Chart.md | 25 + .../charts/type-aliases/ChartTypes.md | 5 + .../charts/type-aliases/LineChart.md | 11 + .../charts/type-aliases/PieChart.md | 15 + .../charts/type-aliases/PieData.md | 23 + .../charts/type-aliases/PointData.md | 17 + .../charts/type-aliases/ScatterChart.md | 11 + .../charts/type-aliases/SuperChart.md | 15 + .../code-interpreter/messaging/README.md | 21 + .../messaging/classes/Execution.md | 111 + .../messaging/classes/ExecutionError.md | 60 + .../messaging/classes/OutputMessage.md | 69 + .../messaging/classes/Result.md | 216 ++ .../messaging/functions/extractError.md | 15 + .../messaging/functions/parseOutput.md | 35 + .../messaging/type-aliases/Logs.md | 23 + .../messaging/type-aliases/MIMEType.md | 7 + .../messaging/type-aliases/RawData.md | 7 + .../code-interpreter/sandbox/README.md | 17 + .../sandbox/classes/Sandbox.md | 1478 ++++++++ .../interfaces/CreateCodeContextOpts.md | 47 + .../sandbox/interfaces/RunCodeOpts.md | 119 + .../sandbox/type-aliases/Context.md | 31 + .../sandbox/type-aliases/RunCodeLanguage.md | 7 + reference/sdk/javascript/commands/README.md | 16 + .../javascript/commands/classes/Commands.md | 260 ++ .../sdk/javascript/commands/classes/Pty.md | 179 + .../commands/interfaces/CommandRequestOpts.md | 45 + .../commands/interfaces/CommandStartOpts.md | 154 + .../commands/interfaces/ProcessInfo.md | 53 + .../type-aliases/CommandConnectOpts.md | 7 + reference/sdk/javascript/errors/README.md | 19 + .../errors/classes/AuthenticationError.md | 185 + .../javascript/errors/classes/BuildError.md | 193 + .../errors/classes/FileNotFoundError.md | 185 + .../errors/classes/FileUploadError.md | 189 + .../errors/classes/InvalidArgumentError.md | 189 + .../errors/classes/NotEnoughSpaceError.md | 185 + .../errors/classes/RateLimitError.md | 185 + .../javascript/errors/classes/SandboxError.md | 197 ++ .../errors/classes/SandboxNotFoundError.md | 185 + .../errors/classes/TemplateError.md | 189 + .../javascript/errors/classes/TimeoutError.md | 193 + .../functions/formatSandboxTimeoutError.md | 15 + reference/sdk/javascript/filesystem/README.md | 27 + .../filesystem/classes/Filesystem.md | 462 +++ .../filesystem/enumerations/FileType.md | 29 + .../filesystem/functions/mapEntryInfo.md | 17 + .../filesystem/interfaces/EntryInfo.md | 116 + .../interfaces/FilesystemListOpts.md | 62 + .../interfaces/FilesystemReadOpts.md | 74 + .../interfaces/FilesystemRequestOpts.md | 57 + .../interfaces/FilesystemWriteOpts.md | 95 + .../filesystem/interfaces/WatchOpts.md | 122 + .../filesystem/interfaces/WriteInfo.md | 44 + .../filesystem/type-aliases/WriteEntry.md | 17 + reference/sdk/javascript/logger/README.md | 15 + .../sdk/javascript/logger/classes/LogEntry.md | 62 + .../javascript/logger/classes/LogEntryEnd.md | 77 + .../logger/classes/LogEntryStart.md | 77 + .../logger/functions/defaultBuildLogger.md | 38 + .../logger/type-aliases/LogEntryLevel.md | 7 + .../sdk/javascript/ready-commands/README.md | 13 + .../ready-commands/classes/ReadyCmd.md | 31 + .../ready-commands/functions/waitForFile.md | 32 + .../ready-commands/functions/waitForPort.md | 32 + .../functions/waitForProcess.md | 32 + .../functions/waitForTimeout.md | 32 + .../ready-commands/functions/waitForURL.md | 38 + reference/sdk/javascript/sandbox/README.md | 6 + .../sdk/javascript/sandbox/index/README.md | 11 + .../sandbox/index/classes/Sandbox.md | 1185 +++++++ .../index/interfaces/SandboxUrlOpts.md | 22 + .../javascript/sandbox/sandboxApi/README.md | 47 + .../sandbox/sandboxApi/classes/SandboxApi.md | 363 ++ .../sandboxApi/classes/SandboxPaginator.md | 153 + .../sandboxApi/classes/SnapshotPaginator.md | 153 + .../interfaces/CreateSnapshotOpts.md | 115 + .../sandboxApi/interfaces/SandboxApiOpts.md | 111 + .../sandboxApi/interfaces/SandboxForkOpts.md | 205 ++ .../sandboxApi/interfaces/SandboxIamOpts.md | 19 + .../sandboxApi/interfaces/SandboxIamToken.md | 21 + .../sandboxApi/interfaces/SandboxInfo.md | 121 + .../sandboxApi/interfaces/SandboxListOpts.md | 135 + .../sandboxApi/interfaces/SandboxMetrics.md | 69 + .../interfaces/SandboxMetricsOpts.md | 121 + .../sandboxApi/interfaces/SandboxOpts.md | 310 ++ .../sandboxApi/interfaces/SandboxPauseOpts.md | 123 + .../sandboxApi/interfaces/SnapshotInfo.md | 22 + .../sandboxApi/interfaces/SnapshotListOpts.md | 130 + .../type-aliases/GitHubMcpServer.md | 9 + .../sandboxApi/type-aliases/McpServer.md | 8 + .../type-aliases/SandboxConnectOpts.md | 23 + .../type-aliases/SandboxIamTokenType.md | 9 + .../type-aliases/SandboxInfoLifecycle.md | 21 + .../type-aliases/SandboxLifecycle.md | 30 + .../type-aliases/SandboxNetworkInfo.md | 39 + .../type-aliases/SandboxNetworkOpts.md | 108 + .../type-aliases/SandboxNetworkRule.md | 29 + .../type-aliases/SandboxNetworkRuleInfo.md | 15 + .../type-aliases/SandboxNetworkRules.md | 10 + .../type-aliases/SandboxNetworkSelector.md | 9 + .../SandboxNetworkSelectorContext.md | 24 + .../type-aliases/SandboxNetworkTransform.md | 16 + .../SandboxNetworkTransformContext.md | 33 + .../SandboxNetworkTransformResolver.md | 18 + .../type-aliases/SandboxNetworkUpdate.md | 45 + .../type-aliases/SandboxOnTimeout.md | 66 + .../sandboxApi/type-aliases/SandboxState.md | 7 + reference/sdk/javascript/templates/README.md | 27 + .../templates/classes/TemplateBase.md | 1746 +++++++++ .../templates/interfaces/TemplateBuilder.md | 850 +++++ .../templates/type-aliases/BuildInfo.md | 39 + .../templates/type-aliases/BuildOptions.md | 7 + .../type-aliases/BuildStatusReason.md | 31 + .../templates/type-aliases/CopyItem.md | 49 + .../type-aliases/GetBuildStatusOptions.md | 13 + .../templates/type-aliases/McpServerName.md | 7 + .../type-aliases/TemplateBuildStatus.md | 7 + .../TemplateBuildStatusResponse.md | 47 + .../templates/type-aliases/TemplateClass.md | 7 + .../templates/type-aliases/TemplateTag.md | 31 + .../templates/type-aliases/TemplateTagInfo.md | 23 + .../templates/variables/Template.md | 36 + .../sdk/python/code-interpreter-async.md | 421 +++ reference/sdk/python/code-interpreter-sync.md | 422 +++ reference/sdk/python/exceptions.md | 109 + reference/sdk/python/logger.md | 249 ++ reference/sdk/python/ready-commands.md | 158 + reference/sdk/python/sandbox-async.md | 351 ++ reference/sdk/python/sandbox-sync.md | 351 ++ reference/sdk/python/templates-async.md | 540 +++ reference/sdk/python/templates-sync.md | 540 +++ scripts/generate-reference.py | 325 ++ scripts/test-reference-contract.py | 73 + 171 files changed, 22732 insertions(+), 147 deletions(-) create mode 100644 .dockerignore create mode 100644 packages/cli/src/reference.ts create mode 100644 reference-config/operations.yaml create mode 100644 reference-config/sdk-groups.json create mode 100644 reference/connect/filesystem.md create mode 100644 reference/connect/process.md create mode 100644 reference/manifest.json create mode 100644 reference/openapi/control-plane.yml create mode 100644 reference/openapi/envd.yml create mode 100644 reference/openapi/operations.json create mode 100644 reference/sdk/cli/auth.md create mode 100644 reference/sdk/cli/sandbox.md create mode 100644 reference/sdk/cli/template.md create mode 100644 reference/sdk/javascript/code-interpreter/README.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/README.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/enumerations/ChartType.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/enumerations/ScaleType.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/functions/deserializeChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/BarChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/BarData.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerData.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/Chart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/ChartTypes.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/LineChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/PieChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/PieData.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/PointData.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/ScatterChart.md create mode 100644 reference/sdk/javascript/code-interpreter/charts/type-aliases/SuperChart.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/README.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/classes/Execution.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/classes/ExecutionError.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/classes/OutputMessage.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/classes/Result.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/functions/extractError.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/functions/parseOutput.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/type-aliases/Logs.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md create mode 100644 reference/sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/README.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md create mode 100644 reference/sdk/javascript/code-interpreter/sandbox/type-aliases/RunCodeLanguage.md create mode 100644 reference/sdk/javascript/commands/README.md create mode 100644 reference/sdk/javascript/commands/classes/Commands.md create mode 100644 reference/sdk/javascript/commands/classes/Pty.md create mode 100644 reference/sdk/javascript/commands/interfaces/CommandRequestOpts.md create mode 100644 reference/sdk/javascript/commands/interfaces/CommandStartOpts.md create mode 100644 reference/sdk/javascript/commands/interfaces/ProcessInfo.md create mode 100644 reference/sdk/javascript/commands/type-aliases/CommandConnectOpts.md create mode 100644 reference/sdk/javascript/errors/README.md create mode 100644 reference/sdk/javascript/errors/classes/AuthenticationError.md create mode 100644 reference/sdk/javascript/errors/classes/BuildError.md create mode 100644 reference/sdk/javascript/errors/classes/FileNotFoundError.md create mode 100644 reference/sdk/javascript/errors/classes/FileUploadError.md create mode 100644 reference/sdk/javascript/errors/classes/InvalidArgumentError.md create mode 100644 reference/sdk/javascript/errors/classes/NotEnoughSpaceError.md create mode 100644 reference/sdk/javascript/errors/classes/RateLimitError.md create mode 100644 reference/sdk/javascript/errors/classes/SandboxError.md create mode 100644 reference/sdk/javascript/errors/classes/SandboxNotFoundError.md create mode 100644 reference/sdk/javascript/errors/classes/TemplateError.md create mode 100644 reference/sdk/javascript/errors/classes/TimeoutError.md create mode 100644 reference/sdk/javascript/errors/functions/formatSandboxTimeoutError.md create mode 100644 reference/sdk/javascript/filesystem/README.md create mode 100644 reference/sdk/javascript/filesystem/classes/Filesystem.md create mode 100644 reference/sdk/javascript/filesystem/enumerations/FileType.md create mode 100644 reference/sdk/javascript/filesystem/functions/mapEntryInfo.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/EntryInfo.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/FilesystemListOpts.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/FilesystemReadOpts.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/FilesystemRequestOpts.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/FilesystemWriteOpts.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/WatchOpts.md create mode 100644 reference/sdk/javascript/filesystem/interfaces/WriteInfo.md create mode 100644 reference/sdk/javascript/filesystem/type-aliases/WriteEntry.md create mode 100644 reference/sdk/javascript/logger/README.md create mode 100644 reference/sdk/javascript/logger/classes/LogEntry.md create mode 100644 reference/sdk/javascript/logger/classes/LogEntryEnd.md create mode 100644 reference/sdk/javascript/logger/classes/LogEntryStart.md create mode 100644 reference/sdk/javascript/logger/functions/defaultBuildLogger.md create mode 100644 reference/sdk/javascript/logger/type-aliases/LogEntryLevel.md create mode 100644 reference/sdk/javascript/ready-commands/README.md create mode 100644 reference/sdk/javascript/ready-commands/classes/ReadyCmd.md create mode 100644 reference/sdk/javascript/ready-commands/functions/waitForFile.md create mode 100644 reference/sdk/javascript/ready-commands/functions/waitForPort.md create mode 100644 reference/sdk/javascript/ready-commands/functions/waitForProcess.md create mode 100644 reference/sdk/javascript/ready-commands/functions/waitForTimeout.md create mode 100644 reference/sdk/javascript/ready-commands/functions/waitForURL.md create mode 100644 reference/sdk/javascript/sandbox/README.md create mode 100644 reference/sdk/javascript/sandbox/index/README.md create mode 100644 reference/sdk/javascript/sandbox/index/classes/Sandbox.md create mode 100644 reference/sdk/javascript/sandbox/index/interfaces/SandboxUrlOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/README.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxApi.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxPaginator.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/classes/SnapshotPaginator.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/CreateSnapshotOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxApiOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxForkOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamToken.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxInfo.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxListOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetrics.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetricsOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxPauseOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotInfo.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotListOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/GitHubMcpServer.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/McpServer.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxConnectOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxIamTokenType.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxInfoLifecycle.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxLifecycle.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkInfo.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkOpts.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRule.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRuleInfo.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRules.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelector.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelectorContext.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransform.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformContext.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformResolver.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkUpdate.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxOnTimeout.md create mode 100644 reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxState.md create mode 100644 reference/sdk/javascript/templates/README.md create mode 100644 reference/sdk/javascript/templates/classes/TemplateBase.md create mode 100644 reference/sdk/javascript/templates/interfaces/TemplateBuilder.md create mode 100644 reference/sdk/javascript/templates/type-aliases/BuildInfo.md create mode 100644 reference/sdk/javascript/templates/type-aliases/BuildOptions.md create mode 100644 reference/sdk/javascript/templates/type-aliases/BuildStatusReason.md create mode 100644 reference/sdk/javascript/templates/type-aliases/CopyItem.md create mode 100644 reference/sdk/javascript/templates/type-aliases/GetBuildStatusOptions.md create mode 100644 reference/sdk/javascript/templates/type-aliases/McpServerName.md create mode 100644 reference/sdk/javascript/templates/type-aliases/TemplateBuildStatus.md create mode 100644 reference/sdk/javascript/templates/type-aliases/TemplateBuildStatusResponse.md create mode 100644 reference/sdk/javascript/templates/type-aliases/TemplateClass.md create mode 100644 reference/sdk/javascript/templates/type-aliases/TemplateTag.md create mode 100644 reference/sdk/javascript/templates/type-aliases/TemplateTagInfo.md create mode 100644 reference/sdk/javascript/templates/variables/Template.md create mode 100644 reference/sdk/python/code-interpreter-async.md create mode 100644 reference/sdk/python/code-interpreter-sync.md create mode 100644 reference/sdk/python/exceptions.md create mode 100644 reference/sdk/python/logger.md create mode 100644 reference/sdk/python/ready-commands.md create mode 100644 reference/sdk/python/sandbox-async.md create mode 100644 reference/sdk/python/sandbox-sync.md create mode 100644 reference/sdk/python/templates-async.md create mode 100644 reference/sdk/python/templates-sync.md create mode 100644 scripts/generate-reference.py create mode 100644 scripts/test-reference-contract.py diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..a9195f87 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,2 @@ +* +!codegen.Dockerfile diff --git a/Makefile b/Makefile index c0c8b55b..1d8dde0d 100644 --- a/Makefile +++ b/Makefile @@ -12,6 +12,8 @@ codegen-image: generate-in-container: cd packages/js-sdk && pnpm generate cd packages/python-sdk && make generate + python scripts/generate-reference.py + python scripts/test-reference-contract.py # Maintainer-only update from a local mono checkout. sync-specs: diff --git a/README.md b/README.md index 7409ff46..ddba8de3 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ The CLI stores local configuration in `~/.agentbox/config.json`; environment var - [Templates and builds](https://docs.agentbox.ru/en/sdk/templates/) - [Code Interpreter](https://docs.agentbox.ru/en/sdk/code-interpreter/) - [CLI](https://docs.agentbox.ru/en/cli/) -- [API reference](https://docs.agentbox.ru/en/sdk/api-reference/) +- [API reference](https://docs.agentbox.ru/en/api-reference/) - [Examples](https://docs.agentbox.ru/en/examples/) ## Development diff --git a/codegen.Dockerfile b/codegen.Dockerfile index fd7c7159..16b1f0e1 100644 --- a/codegen.Dockerfile +++ b/codegen.Dockerfile @@ -45,4 +45,8 @@ RUN npm install -g \ @bufbuild/protoc-gen-es@2.6.2 \ @redocly/cli@2.46.1 +RUN pip install griffe2md==1.5.0 + +RUN npm install -g tsx@4.20.6 + CMD ["make", "generate"] diff --git a/package.json b/package.json index 84cee4f7..86256b26 100644 --- a/package.json +++ b/package.json @@ -24,6 +24,9 @@ "oxlint": "^1.78.0", "prettier": "^3.6.2", "tsdown": "catalog:", + "tsx": "4.20.6", + "typedoc": "0.28.20", + "typedoc-plugin-markdown": "4.13.0", "typescript": "catalog:", "vitest": "catalog:" }, diff --git a/packages/cli/package.json b/packages/cli/package.json index c7820613..b58a6aa1 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -45,16 +45,15 @@ "test": "vitest run", "test:watch": "vitest watch", "test:coverage": "vitest run --coverage", + "reference": "tsx src/reference.ts", "check-deps": "knip" }, "devDependencies": { "@types/inquirer": "^9.0.10", - "@types/json2md": "^1.5.4", "@types/node": "catalog:", "@types/statuses": "^2.0.6", "@typescript/native": "catalog:", "@vitest/coverage-v8": "catalog:", - "json2md": "^2.0.3", "knip": "^5.43.6", "tsdown": "catalog:", "typescript": "catalog:", @@ -71,12 +70,12 @@ "agentbox": "dist/index.js" }, "dependencies": { + "@abox-dev/sdk": "workspace:^", "@inquirer/prompts": "^7.9.0", "boxen": "^7.1.1", "chalk": "^5.3.0", "cli-highlight": "^2.1.11", "commander": "^11.1.0", - "@abox-dev/sdk": "workspace:^", "inquirer": "^12.10.0", "simple-update-notifier": "^2.0.0", "simple-wcswidth": "^1.1.2", diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 0f977102..39a0fb0e 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -1,10 +1,8 @@ #!/usr/bin/env -S node --enable-source-maps import simpleUpdateNotifier from 'simple-update-notifier' -import * as commander from 'commander' import * as packageJSON from '../package.json' import { program } from './commands' -import { commands2md } from './utils/commands2md' export const pkg = packageJSON @@ -23,15 +21,6 @@ const prog = program.version( 'display AgentBox CLI version' ) -if (process.env.NODE_ENV === 'development') { - prog - .addOption(new commander.Option('-cmd2md').hideHelp()) - .on('option:-cmd2md', () => { - commands2md(program.commands as any) - process.exit(0) - }) -} - async function main() { await prog.parseAsync() await updateCheck diff --git a/packages/cli/src/reference.ts b/packages/cli/src/reference.ts new file mode 100644 index 00000000..489060db --- /dev/null +++ b/packages/cli/src/reference.ts @@ -0,0 +1,11 @@ +import path from 'node:path' + +import { program } from './commands' +import { commands2md } from './utils/commands2md' + +const destination = process.argv[2] +if (!destination) { + throw new Error('Usage: pnpm reference OUTPUT_DIR') +} + +commands2md(program.commands, path.resolve(destination)) diff --git a/packages/cli/src/utils/commands2md.ts b/packages/cli/src/utils/commands2md.ts index ac100573..98c3b445 100644 --- a/packages/cli/src/utils/commands2md.ts +++ b/packages/cli/src/utils/commands2md.ts @@ -1,85 +1,73 @@ -import { Command } from 'commander' -import fs from 'fs' -import json2md from 'json2md' -import path from 'path' +import { Command, Option } from 'commander' +import fs from 'node:fs' +import path from 'node:path' -/** - * Converts command objects to Markdown documentation. - * This function takes an array of command objects and generates a structured - * Markdown document describing each command, its usage, options, and subcommands. - * @returns A string containing the entire markdown documentation for all commands. - */ -export function commands2md(commands: Command[]): void { - const outputDir = 'sdk_ref' - if (!fs.existsSync(outputDir)) { - fs.mkdirSync(outputDir, { recursive: true }) - } +function escapeHtml(value: string): string { + return value + .replaceAll('&', '&') + .replaceAll('<', '<') + .replaceAll('>', '>') +} - function commandToMd( - command: any, - parentName: string = '' - ): [string, string] { - const commandName = command.name() as string - const fullName = parentName ? `${parentName} ${commandName}` : commandName +function renderOption(option: Option): string { + const fallback = + option.defaultValue === undefined + ? '' + : ` Default: \`${String(option.defaultValue)}\`.` + return `- \`${escapeHtml(option.flags)}\`: ${escapeHtml(option.description || 'No description.')}${fallback}` +} - const mdStructure = [ - { h2: `agentbox ${fullName}` }, - { p: command.description() }, - { h3: 'Usage' }, - { - code: { - language: 'bash', - content: `agentbox ${fullName} ${command.usage()}`, - }, - }, - ...(command.options.length > 0 - ? [ - { h3: 'Options' }, - { - ul: command.options.map( - (y: any) => - `\`${y.flags}: ${y.description} ${ - y.defaultValue !== undefined - ? `[default: ${y.defaultValue}]` - : '' - }\`` - ), - }, - ] - : []), - ] +function renderCommand(command: Command, parents: string[] = []): string { + const fullName = [...parents, command.name()].join(' ') + const usage = command.usage() || '[options]' + const lines = [ + `## agentbox ${fullName}`, + '', + escapeHtml(command.description() || 'No description.'), + '', + '### Usage', + '', + '```bash', + `agentbox ${fullName} ${usage}`.trimEnd(), + '```', + '', + ] - let mdContent = json2md(mdStructure) + if (command.options.length) { + lines.push('### Options', '', ...command.options.map(renderOption), '') + } - // Process subcommands - command.commands.forEach((subcommand: any) => { - const [, subMdContent] = commandToMd(subcommand, fullName) - mdContent += subMdContent + '\n\n' - }) + for (const subcommand of [...command.commands].sort((a, b) => + a.name().localeCompare(b.name()) + )) { + lines.push(renderCommand(subcommand, [...parents, command.name()])) + } + return lines.join('\n') +} - // Clean the mdContent from terminal colors and escape HTML characters - mdContent = mdContent - .replace(//g, '>') - .replace(/\[1m/g, '') - .replace(/\[22m/g, '') - .replace(/\[34m/g, '') - .replace(/\[39m/g, '') - .replace(/\[38;2;255;183;102m/g, '') +export function commands2md( + commands: readonly Command[], + outputDir: string +): void { + fs.rmSync(outputDir, { recursive: true, force: true }) + fs.mkdirSync(outputDir, { recursive: true }) - return [fullName, mdContent] - } + const groups = new Map([ + ['auth', commands.filter((command) => command.name() === 'configure')], + ['sandbox', commands.filter((command) => command.name() === 'sandbox')], + ['template', commands.filter((command) => command.name() === 'template')], + ]) - commands.forEach((command: any) => { - try { - const [commandName, mdContent] = commandToMd(command) - const fileName = `${commandName}.md` - const filePath = path.join(outputDir, fileName) - fs.writeFileSync(filePath, mdContent) - console.log(`Generated documentation for ${commandName} at ${filePath}`) - } catch (error) { - console.error(`Error processing command: ${command.name()}`) - console.error(error) + for (const [group, groupCommands] of groups) { + if (!groupCommands.length) { + throw new Error(`CLI reference group ${group} has no commands`) } - }) + const title = group[0].toUpperCase() + group.slice(1) + const markdown = [ + `# ${title} commands`, + '', + ...groupCommands.map((command) => renderCommand(command)), + ].join('\n') + fs.writeFileSync(path.join(outputDir, `${group}.md`), `${markdown}\n`) + } } diff --git a/packages/code-interpreter-js/README.md b/packages/code-interpreter-js/README.md index 9ccec3ba..2078625d 100644 --- a/packages/code-interpreter-js/README.md +++ b/packages/code-interpreter-js/README.md @@ -22,4 +22,4 @@ try { } ``` -See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/) and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/javascript/code-interpreter/). +See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/) and [API reference](https://docs.agentbox.ru/en/sdk-reference/javascript/code-interpreter/). diff --git a/packages/code-interpreter-python/README.md b/packages/code-interpreter-python/README.md index 8c2e44e5..040e06ab 100644 --- a/packages/code-interpreter-python/README.md +++ b/packages/code-interpreter-python/README.md @@ -18,4 +18,4 @@ with Sandbox.create() as sandbox: print(execution.text) ``` -`AsyncSandbox` provides the equivalent async API. See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/) and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/python/code-interpreter/). +`AsyncSandbox` provides the equivalent async API. See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/) and [API reference](https://docs.agentbox.ru/en/sdk-reference/python/code-interpreter/). diff --git a/packages/code-interpreter-python/pyproject.toml b/packages/code-interpreter-python/pyproject.toml index 185659dd..482cce64 100644 --- a/packages/code-interpreter-python/pyproject.toml +++ b/packages/code-interpreter-python/pyproject.toml @@ -15,7 +15,7 @@ dependencies = [ [project.urls] Homepage = "https://docs.agentbox.ru/en/sdk/code-interpreter/" -Documentation = "https://docs.agentbox.ru/en/sdk/api-reference/python/code-interpreter/" +Documentation = "https://docs.agentbox.ru/en/sdk-reference/python/code-interpreter/" Repository = "https://github.com/abox-dev/sdk/tree/main/packages/code-interpreter-python" "Bug Tracker" = "https://github.com/abox-dev/sdk/issues" diff --git a/packages/js-sdk/README.md b/packages/js-sdk/README.md index 91f43e00..d108664a 100644 --- a/packages/js-sdk/README.md +++ b/packages/js-sdk/README.md @@ -31,4 +31,4 @@ const client = new AgentBox({ apiKey: 'ab_...' }) const sandbox = await client.Sandbox.create() ``` -Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/javascript/). +Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk-reference/javascript/). diff --git a/packages/python-sdk/README.md b/packages/python-sdk/README.md index 0e4ba7ad..92c2af64 100644 --- a/packages/python-sdk/README.md +++ b/packages/python-sdk/README.md @@ -27,4 +27,4 @@ client = AgentBox(api_key="ab_...") sandbox = await client.AsyncSandbox.create() ``` -Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk/api-reference/python/). +Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/), [sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/), [commands](https://docs.agentbox.ru/en/sdk/commands/), [files](https://docs.agentbox.ru/en/sdk/files/), [templates](https://docs.agentbox.ru/en/sdk/templates/), and [API reference](https://docs.agentbox.ru/en/sdk-reference/python/). diff --git a/packages/python-sdk/pyproject.toml b/packages/python-sdk/pyproject.toml index 1417c538..f685cbef 100644 --- a/packages/python-sdk/pyproject.toml +++ b/packages/python-sdk/pyproject.toml @@ -26,7 +26,7 @@ dependencies = [ [project.urls] Homepage = "https://docs.agentbox.ru/en/sdk/" -Documentation = "https://docs.agentbox.ru/en/sdk/api-reference/python/" +Documentation = "https://docs.agentbox.ru/en/sdk-reference/python/" Repository = "https://github.com/abox-dev/sdk/tree/main/packages/python-sdk" "Bug Tracker" = "https://github.com/abox-dev/sdk/issues" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 56bed8a8..bc2780c2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -78,13 +78,22 @@ importers: version: 3.6.2 tsdown: specifier: 'catalog:' - version: 0.22.14(@typescript/typescript6@6.0.2)(tsx@4.23.12) + version: 0.22.14(@typescript/typescript6@6.0.2)(tsx@4.20.6) + tsx: + specifier: 4.20.6 + version: 4.20.6 + typedoc: + specifier: 0.28.20 + version: 0.28.20(@typescript/typescript6@6.0.2) + typedoc-plugin-markdown: + specifier: 4.13.0 + version: 4.13.0(typedoc@0.28.20(@typescript/typescript6@6.0.2)) typescript: specifier: 'catalog:' version: '@typescript/typescript6@6.0.2' vitest: specifier: 'catalog:' - version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) packages/cli: dependencies: @@ -122,9 +131,6 @@ importers: '@types/inquirer': specifier: ^9.0.10 version: 9.0.10 - '@types/json2md': - specifier: ^1.5.4 - version: 1.5.4 '@types/node': specifier: 'catalog:' version: 20.19.43 @@ -137,9 +143,6 @@ importers: '@vitest/coverage-v8': specifier: 'catalog:' version: 4.1.10(@vitest/browser@4.1.10)(vitest@4.1.10) - json2md: - specifier: ^2.0.3 - version: 2.0.3 knip: specifier: ^5.43.6 version: 5.43.6(@types/node@20.19.43)(@typescript/typescript6@6.0.2) @@ -151,7 +154,7 @@ importers: version: '@typescript/typescript6@6.0.2' vitest: specifier: 'catalog:' - version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) packages/code-interpreter-js: dependencies: @@ -179,7 +182,7 @@ importers: version: '@typescript/typescript6@6.0.2' vitest: specifier: 'catalog:' - version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) packages/code-interpreter-python: {} @@ -245,13 +248,13 @@ importers: version: typescript@7.0.2 '@vitejs/plugin-react': specifier: ^4.3.4 - version: 4.3.4(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + version: 4.3.4(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) '@vitest/browser': specifier: 'catalog:' - version: 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10) + version: 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10) '@vitest/browser-playwright': specifier: 'catalog:' - version: 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10) + version: 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10) dotenv: specifier: ^16.4.5 version: 16.4.5 @@ -290,7 +293,7 @@ importers: version: '@typescript/typescript6@6.0.2' vitest: specifier: 'catalog:' - version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + version: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) vitest-browser-react: specifier: ^2.2.0 version: 2.2.0(@types/react-dom@19.2.4(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(vitest@4.1.10) @@ -854,6 +857,9 @@ packages: cpu: [x64] os: [win32] + '@gerrit0/mini-shiki@3.23.0': + resolution: {integrity: sha512-bEMORlG0cqdjVyCEuU0cDQbORWX+kYCeo0kV1lbxF5bt4r7SID2l9bqsxJEM0zndaxpOUT7riCyIVEuqq/Ynxg==} + '@img/colour@1.1.0': resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==} engines: {node: '>=18'} @@ -1811,6 +1817,21 @@ packages: cpu: [x64] os: [win32] + '@shikijs/engine-oniguruma@3.23.0': + resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==} + + '@shikijs/langs@3.23.0': + resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==} + + '@shikijs/themes@3.23.0': + resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==} + + '@shikijs/types@3.23.0': + resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==} + + '@shikijs/vscode-textmate@10.0.2': + resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} + '@sindresorhus/is@7.2.0': resolution: {integrity: sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==} engines: {node: '>=18'} @@ -1870,15 +1891,15 @@ packages: '@types/estree@1.0.9': resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==} + '@types/hast@3.0.5': + resolution: {integrity: sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==} + '@types/inquirer@9.0.10': resolution: {integrity: sha512-vFW2WbXwO9eZpRT5GJGFJ/shgyMNnYozmnjakt9jCQSS1lvqX8pZEQMjJ9RdDPct/YxwciQ8+V8OYn9euIrZDA==} '@types/json-schema@7.0.15': resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} - '@types/json2md@1.5.4': - resolution: {integrity: sha512-OFTAYD7Nnyu7FZPGnDwYbGOTKqzDfX71uFSgTbGhcr0aHCi17QkSOY3wO5H4yv5h23Ly+7suvf2lzHcdeDIH2Q==} - '@types/lodash@4.17.20': resolution: {integrity: sha512-H3MHACvFUEiujabxhaI/ImO6gUrd8oOurg7LQtS7mbwIXA/cUqWrvBsaeJ23aZEPk1TAYkurjfMbSELfoCXlGA==} @@ -1905,6 +1926,9 @@ packages: '@types/through@0.0.33': resolution: {integrity: sha512-HsJ+z3QuETzP3cswwtzt2vEIiHBk/dCcHGhbmG5X3ecnwFD/lPrMpliGXxSCg03L9AhrdwA4Oz/qfspkDW+xGQ==} + '@types/unist@3.0.3': + resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} + '@typescript/typescript-aix-ppc64@7.0.2': resolution: {integrity: sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==} engines: {node: '>=16.20.0'} @@ -2555,6 +2579,10 @@ packages: resolution: {integrity: sha512-ZSW3ma5GkcQBIpwZTSRAI8N71Uuwgs93IezB7mf7R60tC8ZbJideoDNKjHn2O9KIlx6rkGTTEk1xUCK2E1Y2Yg==} engines: {node: '>=10.13.0'} + entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + error-ex@1.3.2: resolution: {integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==} @@ -2702,6 +2730,9 @@ packages: resolution: {integrity: sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg==} engines: {node: '>= 0.4'} + get-tsconfig@4.14.3: + resolution: {integrity: sha512-++QEw4DIY7WGoukz+/+A/8dGYPT9l9yIadnmSgZ8Rjr3YVSVDipQSO9CdnJo9ePqFqUUqh+wk9uIaoiAwsiPkA==} + get-tsconfig@5.0.0-beta.5: resolution: {integrity: sha512-/6gFNr0N04nob252sTQxyFLi3eKFRqIg1I87YcqAMT1i6SQrSF6KujUEQrtrjMV0H/eejTCltLdDSTEMzHbnsQ==} engines: {node: '>=20.20.0'} @@ -2813,9 +2844,6 @@ packages: resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==} engines: {node: '>=8'} - indento@1.1.13: - resolution: {integrity: sha512-YZWk3mreBEM7sBPddsiQnW9Z8SGg/gNpFfscJq00HCDS7pxcQWWWMSVKJU7YkTRyDu1Zv2s8zaK8gQWKmCXHlg==} - index-to-position@1.2.0: resolution: {integrity: sha512-Yg7+ztRkqslMAS2iFaU+Oa4KTSidr63OsFGlOrJoW981kIYO3CGCS3wA95P1mUi/IVSJkn0D479KTJpVpvFNuw==} engines: {node: '>=18'} @@ -3002,9 +3030,6 @@ packages: json-schema-traverse@1.0.0: resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==} - json2md@2.0.3: - resolution: {integrity: sha512-ZPzh6Djvqz8grJMxKllfCHo0p+p7BsbZ1J95KcCJgvvfdoy7myuKrrkUp80Kpy+wGauykC0dYljLqLY0kENaOw==} - json5@2.2.3: resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==} engines: {node: '>=6'} @@ -3022,6 +3047,9 @@ packages: '@types/node': '>=18' typescript: '>=5.0.4' + linkify-it@5.0.2: + resolution: {integrity: sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==} + load-json-file@4.0.0: resolution: {integrity: sha512-Kx8hMakjX03tiGTLAIdJ+lL0htKnXjEZN6hk/tozf/WOuYGdZBJrZ+rCJRbVCugsjB3jMLn9746NsQIf5VjBMw==} engines: {node: '>=4'} @@ -3036,6 +3064,9 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} + lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + lz-string@1.5.0: resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==} hasBin: true @@ -3050,10 +3081,17 @@ packages: resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==} engines: {node: '>=10'} + markdown-it@14.3.1: + resolution: {integrity: sha512-4Ej49aYTDFIQ+uBkfX8GBvJGccoARxxPep+7aWTs55ozbjQJpW9M26Fe53vnGgvLeVzva/amzjQQaQu9w0vMhA==} + hasBin: true + math-intrinsics@1.1.0: resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} engines: {node: '>= 0.4'} + mdurl@2.1.0: + resolution: {integrity: sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==} + memorystream@0.3.1: resolution: {integrity: sha512-S3UwM3yj5mtUSEfP41UZmt/0SCoVYUcU1rkXv+BQ5Ig8ndL4sPoJNBUJERafdPb5jjHJGuMgytgKvKIf58XNBw==} engines: {node: '>= 0.10.0'} @@ -3312,6 +3350,10 @@ packages: resolution: {integrity: sha512-o1piW0n3tgKIKCwk2vpM/vOV13zjJzvP37Ioze54YlTHE06m4tjEbzg9WsKkvTuyYln2DHjo5pY4qrZGI0otpw==} engines: {node: '>=18'} + punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + quansync@1.0.0: resolution: {integrity: sha512-5xZacEEufv3HSTPQuchrvV6soaiACMFnq1H8wkVioctoH3TRha9Sz66lOxRwPK/qZj7HPiSveih9yAyh98gvqA==} @@ -3730,6 +3772,11 @@ packages: tslib@2.8.1: resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} + tsx@4.20.6: + resolution: {integrity: sha512-ytQKuwgmrrkDTFP4LjR0ToE2nqgy886GpvRSpU0JAnrdBYppuY5rLkRUYPU1yCryb24SsKBTL/hlDQAEFVwtZg==} + engines: {node: '>=18.0.0'} + hasBin: true + tsx@4.23.12: resolution: {integrity: sha512-FDf4L4sYzKtzWYhU/Xm0AQFdTjdIxNo9ElTf2mxXM6k8YMHXzYUe4yODVaXP4V9uMFbVg8c0qyBccK2OOxb45Q==} engines: {node: '>=18.0.0'} @@ -3763,6 +3810,19 @@ packages: resolution: {integrity: sha512-3KS2b+kL7fsuk/eJZ7EQdnEmQoaho/r6KUef7hxvltNA5DR8NAUM+8wJMbJyZ4G9/7i3v5zPBIMN5aybAh2/Jg==} engines: {node: '>= 0.4'} + typedoc-plugin-markdown@4.13.0: + resolution: {integrity: sha512-OHaOLoMTS0wL2ud73WXvxv486mrUEtgXxW4iKiTOGJVipT/VBWY76rlVRMQGes7aVonoIf5roWRe1UvHbufLlQ==} + engines: {node: '>= 18'} + peerDependencies: + typedoc: 0.28.x + + typedoc@0.28.20: + resolution: {integrity: sha512-uSKqkh8Cr48vllnEy+jdaAgOeR6Y+QCBW7usgUsKj7gJEfR7stw9U/fE49LBnj2tPRKPY0c0EBJSWe9Appmplg==} + engines: {node: '>= 18', pnpm: '>= 10'} + hasBin: true + peerDependencies: + typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x || 6.0.x + typescript@6.0.3: resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==} engines: {node: '>=14.17'} @@ -3773,6 +3833,9 @@ packages: engines: {node: '>=16.20.0'} hasBin: true + uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + unbox-primitive@1.1.0: resolution: {integrity: sha512-nWJ91DjeOkej/TA8pXQ3myruKpKEYgqvpw9lz4OPHj/NWFNluYrjbz9j01CJ8yKQd2g4jFoOkINCTW2I5LEEyw==} engines: {node: '>= 0.4'} @@ -4018,6 +4081,11 @@ packages: yaml-ast-parser@0.0.43: resolution: {integrity: sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==} + yaml@2.9.0: + resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==} + engines: {node: '>= 14.6'} + hasBin: true + yargs-parser@20.2.9: resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==} engines: {node: '>=10'} @@ -4241,7 +4309,7 @@ snapshots: cjs-module-lexer: 1.2.3 esbuild: 0.28.1 miniflare: 4.20260721.0(@types/node@20.19.43)(bufferutil@4.0.8)(utf-8-validate@6.0.3) - vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) wrangler: 4.113.0(@types/node@20.19.43)(bufferutil@4.0.8)(utf-8-validate@6.0.3) zod: 3.25.76 transitivePeerDependencies: @@ -4459,6 +4527,14 @@ snapshots: '@esbuild/win32-x64@0.28.1': optional: true + '@gerrit0/mini-shiki@3.23.0': + dependencies: + '@shikijs/engine-oniguruma': 3.23.0 + '@shikijs/langs': 3.23.0 + '@shikijs/themes': 3.23.0 + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + '@img/colour@1.1.0': {} '@img/sharp-darwin-arm64@0.35.2': @@ -5128,6 +5204,26 @@ snapshots: '@rollup/rollup-win32-x64-msvc@4.62.5': optional: true + '@shikijs/engine-oniguruma@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + + '@shikijs/langs@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + + '@shikijs/themes@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + + '@shikijs/types@3.23.0': + dependencies: + '@shikijs/vscode-textmate': 10.0.2 + '@types/hast': 3.0.5 + + '@shikijs/vscode-textmate@10.0.2': {} + '@sindresorhus/is@7.2.0': {} '@snyk/github-codeowners@1.1.0': @@ -5193,6 +5289,10 @@ snapshots: '@types/estree@1.0.9': {} + '@types/hast@3.0.5': + dependencies: + '@types/unist': 3.0.3 + '@types/inquirer@9.0.10': dependencies: '@types/through': 0.0.33 @@ -5200,8 +5300,6 @@ snapshots: '@types/json-schema@7.0.15': {} - '@types/json2md@1.5.4': {} - '@types/lodash@4.17.20': {} '@types/node@20.19.43': @@ -5228,6 +5326,8 @@ snapshots: dependencies: '@types/node': 20.19.43 + '@types/unist@3.0.3': {} + '@typescript/typescript-aix-ppc64@7.0.2': optional: true @@ -5292,40 +5392,72 @@ snapshots: dependencies: '@typescript/old': typescript@6.0.3 - '@vitejs/plugin-react@4.3.4(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))': + '@vitejs/plugin-react@4.3.4(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))': dependencies: '@babel/core': 7.29.7 '@babel/plugin-transform-react-jsx-self': 7.25.9(@babel/core@7.29.7) '@babel/plugin-transform-react-jsx-source': 7.25.9(@babel/core@7.29.7) '@types/babel__core': 7.20.5 react-refresh: 0.14.2 - vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12) + vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0) transitivePeerDependencies: - supports-color - '@vitest/browser-playwright@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10)': + '@vitest/browser-playwright@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0))(vitest@4.1.10)': + dependencies: + '@vitest/browser': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0))(vitest@4.1.10) + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) + playwright: 1.62.1 + tinyrainbow: 3.1.0 + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) + transitivePeerDependencies: + - bufferutil + - msw + - utf-8-validate + - vite + optional: true + + '@vitest/browser-playwright@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10)': dependencies: - '@vitest/browser': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10) - '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + '@vitest/browser': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10) + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) playwright: 1.62.1 tinyrainbow: 3.1.0 - vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) transitivePeerDependencies: - bufferutil - msw - utf-8-validate - vite - '@vitest/browser@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10)': + '@vitest/browser@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0))(vitest@4.1.10)': dependencies: '@blazediff/core': 1.9.1 - '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) '@vitest/utils': 4.1.10 magic-string: 0.30.21 pngjs: 7.0.0 sirv: 3.0.2 tinyrainbow: 3.1.0 - vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) + ws: 8.21.0(bufferutil@4.0.8)(utf-8-validate@6.0.3) + transitivePeerDependencies: + - bufferutil + - msw + - utf-8-validate + - vite + optional: true + + '@vitest/browser@4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10)': + dependencies: + '@blazediff/core': 1.9.1 + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) + '@vitest/utils': 4.1.10 + magic-string: 0.30.21 + pngjs: 7.0.0 + sirv: 3.0.2 + tinyrainbow: 3.1.0 + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) ws: 8.21.0(bufferutil@4.0.8)(utf-8-validate@6.0.3) transitivePeerDependencies: - bufferutil @@ -5345,9 +5477,9 @@ snapshots: obug: 2.1.4 std-env: 4.1.0 tinyrainbow: 3.1.0 - vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) optionalDependencies: - '@vitest/browser': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10) + '@vitest/browser': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10) '@vitest/expect@4.1.10': dependencies: @@ -5358,14 +5490,23 @@ snapshots: chai: 6.2.2 tinyrainbow: 3.1.0 - '@vitest/mocker@4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))': + '@vitest/mocker@4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0))': dependencies: '@vitest/spy': 4.1.10 estree-walker: 3.0.3 magic-string: 0.30.21 optionalDependencies: msw: 2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2) - vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12) + vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0) + + '@vitest/mocker@4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))': + dependencies: + '@vitest/spy': 4.1.10 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + msw: 2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2) + vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0) '@vitest/pretty-format@4.1.10': dependencies: @@ -5789,6 +5930,8 @@ snapshots: graceful-fs: 4.2.11 tapable: 2.2.1 + entities@4.5.0: {} + error-ex@1.3.2: dependencies: is-arrayish: 0.2.1 @@ -6045,6 +6188,10 @@ snapshots: es-errors: 1.3.0 get-intrinsic: 1.3.0 + get-tsconfig@4.14.3: + dependencies: + resolve-pkg-maps: 1.0.0 + get-tsconfig@5.0.0-beta.5: dependencies: resolve-pkg-maps: 1.0.0 @@ -6140,8 +6287,6 @@ snapshots: indent-string@4.0.0: {} - indento@1.1.13: {} - index-to-position@1.2.0: {} inquirer@12.10.0(@types/node@20.19.43): @@ -6323,10 +6468,6 @@ snapshots: json-schema-traverse@1.0.0: {} - json2md@2.0.3: - dependencies: - indento: 1.1.13 - json5@2.2.3: {} kleur@4.1.5: {} @@ -6352,6 +6493,10 @@ snapshots: zod: 3.22.4 zod-validation-error: 3.4.0(zod@3.22.4) + linkify-it@5.0.2: + dependencies: + uc.micro: 2.1.0 + load-json-file@4.0.0: dependencies: graceful-fs: 4.2.11 @@ -6367,6 +6512,8 @@ snapshots: dependencies: yallist: 3.1.1 + lunr@2.3.9: {} + lz-string@1.5.0: {} magic-string@0.30.21: @@ -6383,8 +6530,19 @@ snapshots: dependencies: semver: 7.8.5 + markdown-it@14.3.1: + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.2 + mdurl: 2.1.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + math-intrinsics@1.1.0: {} + mdurl@2.1.0: {} + memorystream@0.3.1: {} merge2@1.4.1: {} @@ -6657,6 +6815,8 @@ snapshots: dependencies: parse-ms: 4.0.0 + punycode.js@2.3.1: {} + quansync@1.0.0: {} queue-microtask@1.2.3: {} @@ -7139,6 +7299,32 @@ snapshots: tree-kill@1.2.2: {} + tsdown@0.22.14(@typescript/typescript6@6.0.2)(tsx@4.20.6): + dependencies: + ansis: 4.3.1 + cac: 7.0.0 + defu: 6.1.7 + empathic: 2.0.1 + hookable: 6.1.1 + import-without-cache: 0.4.0 + obug: 2.1.4 + picomatch: 4.0.5 + rolldown: 1.2.5 + rolldown-plugin-dts: 0.27.14(@typescript/typescript6@6.0.2)(rolldown@1.2.5) + tinyexec: 1.2.4 + tinyglobby: 0.2.17 + tree-kill: 1.2.2 + unconfig-core: 7.5.0 + verkit: 0.3.2 + optionalDependencies: + tsx: 4.20.6 + typescript: '@typescript/typescript6@6.0.2' + transitivePeerDependencies: + - '@typescript/native-preview' + - '@volar/typescript' + - oxc-resolver + - vue-tsc + tsdown@0.22.14(@typescript/typescript6@6.0.2)(tsx@4.23.12): dependencies: ansis: 4.3.1 @@ -7167,6 +7353,13 @@ snapshots: tslib@2.8.1: {} + tsx@4.20.6: + dependencies: + esbuild: 0.25.12 + get-tsconfig: 4.14.3 + optionalDependencies: + fsevents: 2.3.3 + tsx@4.23.12: dependencies: esbuild: 0.28.1 @@ -7215,6 +7408,19 @@ snapshots: possible-typed-array-names: 1.1.0 reflect.getprototypeof: 1.0.10 + typedoc-plugin-markdown@4.13.0(typedoc@0.28.20(@typescript/typescript6@6.0.2)): + dependencies: + typedoc: 0.28.20(@typescript/typescript6@6.0.2) + + typedoc@0.28.20(@typescript/typescript6@6.0.2): + dependencies: + '@gerrit0/mini-shiki': 3.23.0 + lunr: 2.3.9 + markdown-it: 14.3.1 + minimatch: 10.2.5 + typescript: '@typescript/typescript6@6.0.2' + yaml: 2.9.0 + typescript@6.0.3: {} typescript@7.0.2: @@ -7240,6 +7446,8 @@ snapshots: '@typescript/typescript-win32-arm64': 7.0.2 '@typescript/typescript-win32-x64': 7.0.2 + uc.micro@2.1.0: {} + unbox-primitive@1.1.0: dependencies: call-bound: 1.0.4 @@ -7285,7 +7493,23 @@ snapshots: verkit@0.3.2: {} - vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12): + vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0): + dependencies: + esbuild: 0.25.12 + fdir: 6.5.0(picomatch@4.0.5) + picomatch: 4.0.5 + postcss: 8.5.26 + rollup: 4.62.5 + tinyglobby: 0.2.17 + optionalDependencies: + '@types/node': 20.19.43 + fsevents: 2.3.3 + jiti: 2.4.2 + terser: 5.46.0 + tsx: 4.20.6 + yaml: 2.9.0 + + vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0): dependencies: esbuild: 0.25.12 fdir: 6.5.0(picomatch@4.0.5) @@ -7299,20 +7523,50 @@ snapshots: jiti: 2.4.2 terser: 5.46.0 tsx: 4.23.12 + yaml: 2.9.0 vitest-browser-react@2.2.0(@types/react-dom@19.2.4(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(vitest@4.1.10): dependencies: react: 19.2.8 react-dom: 19.2.8(react@19.2.8) - vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + vitest: 4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) optionalDependencies: '@types/react': 19.2.18 '@types/react-dom': 19.2.4(@types/react@19.2.18) - vitest@4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)): + vitest@4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)): + dependencies: + '@vitest/expect': 4.1.10 + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0)) + '@vitest/pretty-format': 4.1.10 + '@vitest/runner': 4.1.10 + '@vitest/snapshot': 4.1.10 + '@vitest/spy': 4.1.10 + '@vitest/utils': 4.1.10 + es-module-lexer: 2.1.0 + expect-type: 1.3.0 + magic-string: 0.30.21 + obug: 2.1.4 + pathe: 2.0.3 + picomatch: 4.0.5 + std-env: 4.1.0 + tinybench: 2.9.0 + tinyexec: 1.2.4 + tinyglobby: 0.2.17 + tinyrainbow: 3.1.0 + vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0) + why-is-node-running: 2.3.0 + optionalDependencies: + '@types/node': 20.19.43 + '@vitest/browser-playwright': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.20.6)(yaml@2.9.0))(vitest@4.1.10) + '@vitest/coverage-v8': 4.1.10(@vitest/browser@4.1.10)(vitest@4.1.10) + transitivePeerDependencies: + - msw + + vitest@4.1.10(@types/node@20.19.43)(@vitest/browser-playwright@4.1.10)(@vitest/coverage-v8@4.1.10)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)): dependencies: '@vitest/expect': 4.1.10 - '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)) + '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0)) '@vitest/pretty-format': 4.1.10 '@vitest/runner': 4.1.10 '@vitest/snapshot': 4.1.10 @@ -7329,11 +7583,11 @@ snapshots: tinyexec: 1.2.4 tinyglobby: 0.2.17 tinyrainbow: 3.1.0 - vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12) + vite: 6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0) why-is-node-running: 2.3.0 optionalDependencies: '@types/node': 20.19.43 - '@vitest/browser-playwright': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12))(vitest@4.1.10) + '@vitest/browser-playwright': 4.1.10(bufferutil@4.0.8)(msw@2.15.0(@types/node@20.19.43)(@typescript/typescript6@6.0.2))(playwright@1.62.1)(utf-8-validate@6.0.3)(vite@6.4.3(@types/node@20.19.43)(jiti@2.4.2)(terser@5.46.0)(tsx@4.23.12)(yaml@2.9.0))(vitest@4.1.10) '@vitest/coverage-v8': 4.1.10(@vitest/browser@4.1.10)(vitest@4.1.10) transitivePeerDependencies: - msw @@ -7481,6 +7735,8 @@ snapshots: yaml-ast-parser@0.0.43: {} + yaml@2.9.0: {} + yargs-parser@20.2.9: {} yargs-parser@21.1.1: {} diff --git a/reference-config/operations.yaml b/reference-config/operations.yaml new file mode 100644 index 00000000..3593301c --- /dev/null +++ b/reference-config/operations.yaml @@ -0,0 +1,50 @@ +schemaVersion: 1 + +controlPlane: + source: spec/openapi.yml + publicTags: + - sandboxes + - snapshots + - templates + - tags + operations: + GET /teams/{teamID}/metrics: { id: getTeamMetrics, group: team-metrics, slug: team-metrics } + GET /teams/{teamID}/metrics/max: { id: getTeamMetricsMax, group: team-metrics, slug: team-metrics-max } + POST /sandboxes: { id: createSandbox, group: sandboxes, slug: create } + GET /v2/sandboxes: { id: listSandboxes, group: sandboxes, slug: list } + GET /sandboxes/metrics: { id: listSandboxMetrics, group: sandboxes, slug: list-metrics } + GET /v2/sandboxes/{sandboxID}/logs: { id: getSandboxLogs, group: sandboxes, slug: logs } + GET /sandboxes/{sandboxID}: { id: getSandbox, group: sandboxes, slug: get } + DELETE /sandboxes/{sandboxID}: { id: killSandbox, group: sandboxes, slug: kill } + GET /sandboxes/{sandboxID}/metrics: { id: getSandboxMetrics, group: sandboxes, slug: metrics } + POST /sandboxes/{sandboxID}/pause: { id: pauseSandbox, group: sandboxes, slug: pause } + POST /sandboxes/{sandboxID}/fork: { id: forkSandbox, group: sandboxes, slug: fork } + POST /sandboxes/{sandboxID}/connect: { id: connectSandbox, group: sandboxes, slug: connect } + POST /sandboxes/{sandboxID}/timeout: { id: setSandboxTimeout, group: sandboxes, slug: timeout } + PUT /sandboxes/{sandboxID}/network: { id: updateSandboxNetwork, group: sandboxes, slug: network } + POST /sandboxes/{sandboxID}/refreshes: { id: refreshSandbox, group: sandboxes, slug: refresh } + POST /sandboxes/{sandboxID}/snapshots: { id: createSnapshot, group: snapshots, slug: create } + GET /snapshots: { id: listSnapshots, group: snapshots, slug: list } + POST /v3/templates: { id: createTemplate, group: templates, slug: create } + GET /v2/templates: { id: listTemplates, group: templates, slug: list } + GET /templates/{templateID}/files/{hash}: { id: getTemplateUploadUrl, group: templates, slug: upload-url } + GET /templates/{templateID}: { id: getTemplate, group: templates, slug: get } + DELETE /templates/{templateID}: { id: deleteTemplate, group: templates, slug: delete } + POST /v2/templates/{templateID}/builds/{buildID}: { id: startTemplateBuild, group: templates, slug: start-build } + PATCH /v2/templates/{templateID}: { id: updateTemplate, group: templates, slug: update } + GET /templates/{templateID}/builds/{buildID}/status: { id: getTemplateBuildStatus, group: templates, slug: build-status } + GET /templates/{templateID}/builds/{buildID}/logs: { id: getTemplateBuildLogs, group: templates, slug: build-logs } + POST /templates/tags: { id: assignTemplateTags, group: tags, slug: assign } + DELETE /templates/tags: { id: deleteTemplateTags, group: tags, slug: delete } + GET /templates/{templateID}/tags: { id: listTemplateTags, group: tags, slug: list } + GET /templates/aliases/{alias}: { id: getTemplateByAlias, group: templates, slug: alias } + +envd: + source: spec/envd/envd.yaml + operations: + GET /health: { id: getEnvironmentHealth, group: environment, slug: health } + GET /metrics: { id: getEnvironmentMetrics, group: environment, slug: metrics } + GET /envs: { id: getEnvironmentVariables, group: environment, slug: variables } + GET /files: { id: downloadFile, group: files, slug: download } + POST /files: { id: uploadFile, group: files, slug: upload } + POST /files/compose: { id: composeFiles, group: files, slug: compose } diff --git a/reference-config/sdk-groups.json b/reference-config/sdk-groups.json new file mode 100644 index 00000000..c138d1d2 --- /dev/null +++ b/reference-config/sdk-groups.json @@ -0,0 +1,34 @@ +{ + "javascript": { + "errors": ["packages/js-sdk/src/errors.ts"], + "sandbox": [ + "packages/js-sdk/src/sandbox/index.ts", + "packages/js-sdk/src/sandbox/sandboxApi.ts" + ], + "commands": ["packages/js-sdk/src/sandbox/commands/index.ts"], + "filesystem": ["packages/js-sdk/src/sandbox/filesystem/index.ts"], + "templates": ["packages/js-sdk/src/template/index.ts"], + "logger": ["packages/js-sdk/src/template/logger.ts"], + "ready-commands": ["packages/js-sdk/src/template/readycmd.ts"], + "code-interpreter": [ + "packages/code-interpreter-js/src/sandbox.ts", + "packages/code-interpreter-js/src/messaging.ts", + "packages/code-interpreter-js/src/charts.ts" + ] + }, + "python": { + "exceptions": ["agentbox.exceptions"], + "sandbox-sync": ["agentbox.sandbox_sync.main"], + "sandbox-async": ["agentbox.sandbox_async.main"], + "templates-sync": ["agentbox.template_sync.main"], + "templates-async": ["agentbox.template_async.main"], + "logger": ["agentbox.template.logger"], + "ready-commands": ["agentbox.template.readycmd"], + "code-interpreter-sync": [ + "agentbox_code_interpreter.code_interpreter_sync" + ], + "code-interpreter-async": [ + "agentbox_code_interpreter.code_interpreter_async" + ] + } +} diff --git a/reference/connect/filesystem.md b/reference/connect/filesystem.md new file mode 100644 index 00000000..ebc29ae2 --- /dev/null +++ b/reference/connect/filesystem.md @@ -0,0 +1,205 @@ +# Filesystem API + +Service: `Filesystem` + +## Stat + +Public RPC exposed by envd. + +- Request: `StatRequest` +- Response: `StatResponse` + +## MakeDir + +Public RPC exposed by envd. + +- Request: `MakeDirRequest` +- Response: `MakeDirResponse` + +## Move + +Public RPC exposed by envd. + +- Request: `MoveRequest` +- Response: `MoveResponse` + +## ListDir + +Public RPC exposed by envd. + +- Request: `ListDirRequest` +- Response: `ListDirResponse` + +## Remove + +Public RPC exposed by envd. + +- Request: `RemoveRequest` +- Response: `RemoveResponse` + +## WatchDir + +Public RPC exposed by envd. + +- Request: `WatchDirRequest` +- Response: `stream WatchDirResponse` + +## CreateWatcher + +Non-streaming versions of WatchDir + +- Request: `CreateWatcherRequest` +- Response: `CreateWatcherResponse` + +## GetWatcherEvents + +Public RPC exposed by envd. + +- Request: `GetWatcherEventsRequest` +- Response: `GetWatcherEventsResponse` + +## RemoveWatcher + +Public RPC exposed by envd. + +- Request: `RemoveWatcherRequest` +- Response: `RemoveWatcherResponse` + +## Message types + +### MoveRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `source` | `string` | 1 | | +| `destination` | `string` | 2 | | + +### MoveResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `entry` | `EntryInfo` | 1 | | + +### MakeDirRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | + +### MakeDirResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `entry` | `EntryInfo` | 1 | | + +### RemoveRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | + +### RemoveResponse + +### StatRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | + +### StatResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `entry` | `EntryInfo` | 1 | | + +### EntryInfo + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `name` | `string` | 1 | | +| `type` | `FileType` | 2 | | +| `path` | `string` | 3 | | +| `size` | `int64` | 4 | | +| `mode` | `uint32` | 5 | | +| `permissions` | `string` | 6 | | +| `owner` | `string` | 7 | | +| `group` | `string` | 8 | | +| `modified_time` | `google.protobuf.Timestamp` | 9 | | +| `symlink_target` | `optional string` | 10 | If the entry is a symlink, this field contains the target of the symlink. | + +### ListDirRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | +| `depth` | `uint32` | 2 | | + +### ListDirResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `entries` | `repeated EntryInfo` | 1 | | + +### WatchDirRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | +| `recursive` | `bool` | 2 | | +| `include_entry` | `bool` | 3 | If true, each FilesystemEvent includes the EntryInfo of the affected entry, when available. | +| `allow_network_mounts` | `bool` | 4 | Events on network mounts may be unreliable or not delivered at all. | + +### FilesystemEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `name` | `string` | 1 | | +| `type` | `EventType` | 2 | | +| `entry` | `optional EntryInfo` | 3 | events, where the entry no longer exists at this path). | + +### WatchDirResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `start` | `StartEvent` | 1 | | +| `filesystem` | `FilesystemEvent` | 2 | | +| `keepalive` | `KeepAlive` | 3 | | + +### StartEvent + +### KeepAlive + +### CreateWatcherRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `path` | `string` | 1 | | +| `recursive` | `bool` | 2 | | +| `include_entry` | `bool` | 3 | If true, each FilesystemEvent includes the EntryInfo of the affected entry, when available. | +| `allow_network_mounts` | `bool` | 4 | Events on network mounts may be unreliable or not delivered at all. | + +### CreateWatcherResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `watcher_id` | `string` | 1 | | + +### GetWatcherEventsRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `watcher_id` | `string` | 1 | | + +### GetWatcherEventsResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `events` | `repeated FilesystemEvent` | 1 | | + +### RemoveWatcherRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `watcher_id` | `string` | 1 | | + +### RemoveWatcherResponse diff --git a/reference/connect/process.md b/reference/connect/process.md new file mode 100644 index 00000000..3d99106c --- /dev/null +++ b/reference/connect/process.md @@ -0,0 +1,244 @@ +# Process API + +Service: `Process` + +## List + +Public RPC exposed by envd. + +- Request: `ListRequest` +- Response: `ListResponse` + +## Connect + +Public RPC exposed by envd. + +- Request: `ConnectRequest` +- Response: `stream ConnectResponse` + +## Start + +Public RPC exposed by envd. + +- Request: `StartRequest` +- Response: `stream StartResponse` + +## Update + +Public RPC exposed by envd. + +- Request: `UpdateRequest` +- Response: `UpdateResponse` + +## StreamInput + +Client input stream ensures ordering of messages + +- Request: `stream StreamInputRequest` +- Response: `StreamInputResponse` + +## SendInput + +Public RPC exposed by envd. + +- Request: `SendInputRequest` +- Response: `SendInputResponse` + +## SendSignal + +Public RPC exposed by envd. + +- Request: `SendSignalRequest` +- Response: `SendSignalResponse` + +## CloseStdin + +Only works for non-PTY processes. For PTY, send Ctrl+D (0x04) instead. + +- Request: `CloseStdinRequest` +- Response: `CloseStdinResponse` + +## Message types + +### PTY + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `size` | `Size` | 1 | | +| `cols` | `uint32` | 1 | | +| `rows` | `uint32` | 2 | | + +### Size + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `cols` | `uint32` | 1 | | +| `rows` | `uint32` | 2 | | + +### ProcessConfig + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `cmd` | `string` | 1 | | +| `args` | `repeated string` | 2 | | +| `cwd` | `optional string` | 4 | | + +### ListRequest + +### ProcessInfo + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `config` | `ProcessConfig` | 1 | | +| `pid` | `uint32` | 2 | | +| `tag` | `optional string` | 3 | | + +### ListResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `processes` | `repeated ProcessInfo` | 1 | | + +### StartRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessConfig` | 1 | | +| `pty` | `optional PTY` | 2 | | +| `tag` | `optional string` | 3 | | +| `stdin` | `optional bool` | 4 | We default to true. New SDK versions will set this to false by default. | + +### UpdateRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | +| `pty` | `optional PTY` | 2 | | + +### UpdateResponse + +### ProcessEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `start` | `StartEvent` | 1 | | +| `data` | `DataEvent` | 2 | | +| `end` | `EndEvent` | 3 | | +| `keepalive` | `KeepAlive` | 4 | | +| `pid` | `uint32` | 1 | | +| `stdout` | `bytes` | 1 | | +| `stderr` | `bytes` | 2 | | +| `pty` | `bytes` | 3 | | +| `exit_code` | `sint32` | 1 | | +| `exited` | `bool` | 2 | | +| `status` | `string` | 3 | | +| `error` | `optional string` | 4 | | + +### StartEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `pid` | `uint32` | 1 | | + +### DataEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `stdout` | `bytes` | 1 | | +| `stderr` | `bytes` | 2 | | +| `pty` | `bytes` | 3 | | + +### EndEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `exit_code` | `sint32` | 1 | | +| `exited` | `bool` | 2 | | +| `status` | `string` | 3 | | +| `error` | `optional string` | 4 | | + +### KeepAlive + +### StartResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `event` | `ProcessEvent` | 1 | | + +### ConnectResponse + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `event` | `ProcessEvent` | 1 | | + +### SendInputRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | +| `input` | `ProcessInput` | 2 | | + +### SendInputResponse + +### ProcessInput + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `stdin` | `bytes` | 1 | | +| `pty` | `bytes` | 2 | | + +### StreamInputRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `start` | `StartEvent` | 1 | | +| `data` | `DataEvent` | 2 | | +| `keepalive` | `KeepAlive` | 3 | | +| `process` | `ProcessSelector` | 1 | | +| `input` | `ProcessInput` | 2 | | + +### StartEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | + +### DataEvent + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `input` | `ProcessInput` | 2 | | + +### KeepAlive + +### StreamInputResponse + +### SendSignalRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | +| `signal` | `Signal` | 2 | | + +### SendSignalResponse + +### CloseStdinRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | + +### CloseStdinResponse + +### ConnectRequest + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `process` | `ProcessSelector` | 1 | | + +### ProcessSelector + +| Field | Type | Number | Description | +| --- | --- | ---: | --- | +| `pid` | `uint32` | 1 | | +| `tag` | `string` | 2 | | diff --git a/reference/manifest.json b/reference/manifest.json new file mode 100644 index 00000000..9c10826e --- /dev/null +++ b/reference/manifest.json @@ -0,0 +1,163 @@ +{ + "files": { + "connect/filesystem.md": "1cc1e81386810d3c5c999458e02340e3becb3da8138d943558584094750e5aae", + "connect/process.md": "037574455e9e8c5159c391d8c007e7272560f62c4e5ee681f8aec29f9cd24539", + "openapi/control-plane.yml": "f0a5b8c69f92bc19ed2bebb77d1fc097f991f8ecdd06cf439082eb73b64c93fe", + "openapi/envd.yml": "e4d91017beb3885ef4b389ab23f30f43682ee6a2c01721275e6513d8cfe6217d", + "openapi/operations.json": "78801f197ba691e54d42c5b6026aa4112f883eeb1966595cc2529f895dc0852a", + "sdk/cli/auth.md": "0b2c75262b0c0670c7bc0f0f3cbed65fbe4a16d6fe4437789a5685b8bf2174a1", + "sdk/cli/sandbox.md": "0f59649197a6f42282a8b789c4384e8e41d2e525de414a22dffe073f0fca4d64", + "sdk/cli/template.md": "f270b22b9ee10a9b954a14f24e04c5449b4d5823bb28002ffde3ed682594cfc5", + "sdk/javascript/code-interpreter/README.md": "039623531e5230593b947e9a1a21690cfbf0ae99d96bf1f28e855d3cde9bb4f8", + "sdk/javascript/code-interpreter/charts/README.md": "9ccf26a23701a8424a6603ccf62e9d11e6f94420856d91275d17e9f792f0bd1f", + "sdk/javascript/code-interpreter/charts/enumerations/ChartType.md": "c393d23dafe81aec247ce84270fdfee89aa31fc5d8b78b668a894b2bc9b1102b", + "sdk/javascript/code-interpreter/charts/enumerations/ScaleType.md": "9997e8c06d17e7f1f540c7ff3e8582fecdddc2c0b7192c465a49fcbb0649a1ac", + "sdk/javascript/code-interpreter/charts/functions/deserializeChart.md": "973ca2b42d0cc25c97435eed21e2e5a5622ffa8ef4d3c61f143dcad1427d02a9", + "sdk/javascript/code-interpreter/charts/type-aliases/BarChart.md": "87c25787fd08c5a398c821e922afc937a4dda8f47a7ebe4cde439969efabd8cd", + "sdk/javascript/code-interpreter/charts/type-aliases/BarData.md": "f9e5653a14e631e010cd0b8ec84b71af5c74ed2113513bdbb26f0b622ea80020", + "sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerChart.md": "daeaffc6df025985c55303cfe37f074942e878463685a19af02440f786f98ba6", + "sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerData.md": "5a03be5357a27e6964f22b4ca5bcc4780d80d18a564a4860401a83c70629af6b", + "sdk/javascript/code-interpreter/charts/type-aliases/Chart.md": "607fcd5c742952765d3651df25738812add74efc3aac955ae4bd7fc67a63976b", + "sdk/javascript/code-interpreter/charts/type-aliases/ChartTypes.md": "40252fe3c0af2c82b2b82735f5cb654bf3f6d04fd957ccf6788c9f0ae1ca5a02", + "sdk/javascript/code-interpreter/charts/type-aliases/LineChart.md": "07a1257762c47c47e14b6fc1d2889abfa34fc29a11cf2299d6c114912f458011", + "sdk/javascript/code-interpreter/charts/type-aliases/PieChart.md": "5f1458673413562ec8bb62da444e8a2bf2bf4f904c780316077fb8013c0c87d6", + "sdk/javascript/code-interpreter/charts/type-aliases/PieData.md": "37d400c47d192918c8d6d95d6cc5c4c4fd53f50d668ffb35d64f97375ecd9c78", + "sdk/javascript/code-interpreter/charts/type-aliases/PointData.md": "9f795ecc3a19b30c14d659451c89c4be6da023898c0dfffd925f464fc5aa7ef0", + "sdk/javascript/code-interpreter/charts/type-aliases/ScatterChart.md": "1f54d35203890751fe3a2c9bc550a727d980062351bef1e23451e4fd356866bb", + "sdk/javascript/code-interpreter/charts/type-aliases/SuperChart.md": "a2a98a221d1b4b090f152218e4f89ad75303b619db10a54c7a71d392918e23cf", + "sdk/javascript/code-interpreter/messaging/README.md": "bc0fb2eb6b33aece38ada22b433e96f3b40c1652536522656e6ced3935260dc7", + "sdk/javascript/code-interpreter/messaging/classes/Execution.md": "8582fb8dd0036eec1b66303b5ad71d33008bade55233ac9fb692f41bc7f5aac9", + "sdk/javascript/code-interpreter/messaging/classes/ExecutionError.md": "bba0cd11403a179297d6684ef2b328db743e3632e4f962ba013fb658f5546e8b", + "sdk/javascript/code-interpreter/messaging/classes/OutputMessage.md": "308fe78a3e9d8af7deca22fe9750599b83bf9d704c5e3b19bc6f00f1753462f0", + "sdk/javascript/code-interpreter/messaging/classes/Result.md": "88dc6a0fee61eb5c30f6db136e6416d55794619f6dd0f87e3d24672259e6abfe", + "sdk/javascript/code-interpreter/messaging/functions/extractError.md": "1a9e1cc0750542df81ad425335be805a640f3e32964f8b54da42b6e15da799be", + "sdk/javascript/code-interpreter/messaging/functions/parseOutput.md": "af4fe0c24923bb81f1da89223ff90d432d4249d1e184cffa0855f90585424bb2", + "sdk/javascript/code-interpreter/messaging/type-aliases/Logs.md": "b8abe4852b01003ea43dbc1578a5ebddf251130a0697400481057878008133de", + "sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md": "e83e73d6a0e97763e7e82b736871be2363b73f078d500b0f753d0d5085a6737c", + "sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md": "1d4c93b749bebbb87e1f2b4a335528adb16f98360a24550c1fbb4d2056ca3c9b", + "sdk/javascript/code-interpreter/sandbox/README.md": "ce7ff81b5b0bc706ab215ebbb971aac7951fbcd82959c0884fff8c84f0aae33a", + "sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md": "00b255364c5db61830b4fbe58c2dcf32aa80735b7c31ba9d4c07fe1552a45cbd", + "sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md": "9077fc89c2bc9589e19112b63158ad55cd4d75c52879af93d3b65dd391fc1eaf", + "sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md": "b7518d5d91a0def0d7f2f10bb4153a76969f0c0c049cac930519342d93c64556", + "sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md": "01a1570ac3f1870cb303215203b7b3dddf26bfcf5cc53c863bb65ea493956825", + "sdk/javascript/code-interpreter/sandbox/type-aliases/RunCodeLanguage.md": "636454bcc7c0bbf51dfc12cc2ed6cb9cf844178929d3a4a6614276998cac5cc6", + "sdk/javascript/commands/README.md": "dabba5d624e6788045c622fa73d9197a22802ae8a2e6a7c892750210bca5bc11", + "sdk/javascript/commands/classes/Commands.md": "2b5da52e1e5b13a132a5f32a0b1fa70dd185b1c86faaedc5e758ed9b02431998", + "sdk/javascript/commands/classes/Pty.md": "50fe1486af6f004c3112309561fce7c2b8831ad8ddbfa8d163399f1db6bf366d", + "sdk/javascript/commands/interfaces/CommandRequestOpts.md": "df8e606a14ec23ea086f9c966ebebc46fa62f0158881b1266bb245a299202f34", + "sdk/javascript/commands/interfaces/CommandStartOpts.md": "fe944bc69cefad940990aaa52a7e195cef0fe986a0c31671221beea810a0a95c", + "sdk/javascript/commands/interfaces/ProcessInfo.md": "092cf569bf5fc6a785af445d9bf98fda3072e3776d22be5dbe97068b8b1e6d1b", + "sdk/javascript/commands/type-aliases/CommandConnectOpts.md": "474af2675eebc52a8fec3695f801d289337550fb06c323e45939dc6e98b43d3c", + "sdk/javascript/errors/README.md": "1ffc232147a41878ce032004326cf05e8fe7ca5b0dda890dc5217abef2fd9c85", + "sdk/javascript/errors/classes/AuthenticationError.md": "2680ac56bc87242c69d04b9148df55b2c1904135cf1e12be096560b5cbd59e22", + "sdk/javascript/errors/classes/BuildError.md": "2825b775a0c5731e9da8bd0bc463a3b0bfd01fa7aa5216e998f3c604a5d3c110", + "sdk/javascript/errors/classes/FileNotFoundError.md": "c413c9590d29b9fc382edc9bee1868471d86e9fdd7afceb7567aa6ba42e3435f", + "sdk/javascript/errors/classes/FileUploadError.md": "ce7070ac8013c4414340cbc6c917e24d05df732a3bbf72a4d7e8ac13cdd8affc", + "sdk/javascript/errors/classes/InvalidArgumentError.md": "032683cf008b05d24b62505e11cf48b8711b847b979bc20684328ee36f44bd68", + "sdk/javascript/errors/classes/NotEnoughSpaceError.md": "5d8026af48a12af101eb06d566cdb21dd23f9596a1943f50fe822bd119bc1ae3", + "sdk/javascript/errors/classes/RateLimitError.md": "5ee27148668630dbe20618cee2ef354a6337bcba3a8dbb042401d07bc0a22134", + "sdk/javascript/errors/classes/SandboxError.md": "fc706640efa003909b83d9242ae22ee6cd13de1ac7b8532cc8a063818c5e2a86", + "sdk/javascript/errors/classes/SandboxNotFoundError.md": "c5c86e302c5506fd4ed6effed1aee7f098fd95eac1105bab2e155fd804067ad4", + "sdk/javascript/errors/classes/TemplateError.md": "e308051d546329e1fdace73b5ef1bd88a811e301a68427d63e5fc3811ae31b25", + "sdk/javascript/errors/classes/TimeoutError.md": "2bf1a25743de8d27691213dc0bac79672227e41b44093499bd61d41b9c88bb1b", + "sdk/javascript/errors/functions/formatSandboxTimeoutError.md": "b988774343843655642def8a803258d0d46a297bd03bdbbd0d16259f6b610ea3", + "sdk/javascript/filesystem/README.md": "37effe2c50d20b4bdfd2b460bfa0418537a91744e71829e2ac996353d035801e", + "sdk/javascript/filesystem/classes/Filesystem.md": "3a82812bde29265b39ab29669795b6430247ad4cf630402d6755445622bf5193", + "sdk/javascript/filesystem/enumerations/FileType.md": "00df1e000a8f60644b75ad13765e35583c84a9e754f86d27446d271ffc757c70", + "sdk/javascript/filesystem/functions/mapEntryInfo.md": "84698ca0bdae9f442ede963d23c7bba5b8e91240ca71eb0c45fa7305825058ec", + "sdk/javascript/filesystem/interfaces/EntryInfo.md": "1d692b3fc4e6067ef8467246ec28b1a5e3297e4434cbc77b2e9bbb1c1afdd42e", + "sdk/javascript/filesystem/interfaces/FilesystemListOpts.md": "94f455099c31281a1c2244e5bcb97aaf6f32d22c17d37c314ffcefe44bd39a24", + "sdk/javascript/filesystem/interfaces/FilesystemReadOpts.md": "5677fdd1dc04db871462c0dc81180534f2eb0f0cc87a338fa39c75ef330f813b", + "sdk/javascript/filesystem/interfaces/FilesystemRequestOpts.md": "a2f8a0f1fceb25bdbb6633c1ebc8075d08ed44eb6020dfe8df56672e50485523", + "sdk/javascript/filesystem/interfaces/FilesystemWriteOpts.md": "679126fc65ff20e8dd9da8b4ec58b1bbc92be57db8c84c16ac0cba3cdff01f2f", + "sdk/javascript/filesystem/interfaces/WatchOpts.md": "4ec34e5f94f48f18342fd68dc7c6be028f0290ad2a266042c89a009470ea397b", + "sdk/javascript/filesystem/interfaces/WriteInfo.md": "83ceaaf70c4811125a7359bffef0f2b73616fe43681678f47bfa4a5cd3178861", + "sdk/javascript/filesystem/type-aliases/WriteEntry.md": "e0741a7f7b3c075d6ce4076b563cd1fa21c2defffe071703554ae3ac05e1bf0c", + "sdk/javascript/logger/README.md": "eef3e06788b317326c987ba9a40cb3f267fb55166dd6bdb0debbd0489c884c34", + "sdk/javascript/logger/classes/LogEntry.md": "631fd72818a8ae1f64ae1f337bd5f1f23e0e24fbf3515ecc30c023727874e357", + "sdk/javascript/logger/classes/LogEntryEnd.md": "eeda5c8cecc0644ea0b73cc1ac7e1345af62eec4ea0857ef8b40913326c470bc", + "sdk/javascript/logger/classes/LogEntryStart.md": "2f1ed14ea1e19287c00dfb028139fc4dc6dd67aadac235d1e1bfff5069bf98f7", + "sdk/javascript/logger/functions/defaultBuildLogger.md": "f8dc7e3a5d766f29c0202315bb7f05a95edc802d69ef2c6876abaacf2cb9cfe4", + "sdk/javascript/logger/type-aliases/LogEntryLevel.md": "a0286486a7bd1574c1e2238d0ca59bc9436303fe8b0d12bcbef8f7a207333cc0", + "sdk/javascript/ready-commands/README.md": "0d3f38c75323a366a915f6603014d0aa77618f1ed519bfa4685a75d87cf112fd", + "sdk/javascript/ready-commands/classes/ReadyCmd.md": "2946b0f847c6bc61670a655997cd9c1b7c3de365093657bcbaeb9cc3cb4cfd39", + "sdk/javascript/ready-commands/functions/waitForFile.md": "9c2f4b23c318f6bdbba4df678679ef41ce386ede374bbcd180c9b7942c297660", + "sdk/javascript/ready-commands/functions/waitForPort.md": "304c45757a7449748b18c056ba44daf318306ae6ac550a08ff297a2544503f57", + "sdk/javascript/ready-commands/functions/waitForProcess.md": "036288a363552520a527e152257e732ffbe32f209b0590c4cee12a60fcf7a970", + "sdk/javascript/ready-commands/functions/waitForTimeout.md": "26cb10fe7070b972ce1210e7f931ed32783c9edaeb2e3a31a9d1f30fffef470c", + "sdk/javascript/ready-commands/functions/waitForURL.md": "08bab702f4c333d5132cda05ba810c3262cb6bf01c9cddd0287abb2774940dc3", + "sdk/javascript/sandbox/README.md": "2c010fbaf61ec94a24067d30650db155e9bb92f5b5760cd255479c82019b0b81", + "sdk/javascript/sandbox/index/README.md": "d3d3842b2e46af321942d5bdf6fc2c75f3a6d474f2a8d3f7b7787b993acb8867", + "sdk/javascript/sandbox/index/classes/Sandbox.md": "831abee3f504380c7abb47e4cdd1e09f29173fbd960f320bd4603505827ad419", + "sdk/javascript/sandbox/index/interfaces/SandboxUrlOpts.md": "4e5afdc62b343bdfc89fc96478143ccf013d6f670253330a10042fa8775fe929", + "sdk/javascript/sandbox/sandboxApi/README.md": "c22958d25bc3cb59806d04ae768c02cc924845a10dc2cb9252cde643a2c1a24b", + "sdk/javascript/sandbox/sandboxApi/classes/SandboxApi.md": "34425d9542b006633d1c08af181bc2e3db7d21daaeca4c9452787a936f0e60e5", + "sdk/javascript/sandbox/sandboxApi/classes/SandboxPaginator.md": "296b8de58eb6e5871fcd2e273ee6f38638d2597fbff4a5f83ef5d79e2af456c8", + "sdk/javascript/sandbox/sandboxApi/classes/SnapshotPaginator.md": "3ffcb8d44a315f6f8ca2a63a58dff76933ea4f247871df5e8e1fa87a998edc4d", + "sdk/javascript/sandbox/sandboxApi/interfaces/CreateSnapshotOpts.md": "bd1256b70decc641f7f013c47d15a703c133a0656f83fedde3b7074f0cec472d", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxApiOpts.md": "28feeda0fe8484b19aeacdee3b08a34f8ced22bd929e00587e75ce0fc4ee5aba", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxForkOpts.md": "8084497f7cdfd120f8cad96e9ae3b0296fe985f39d7d74853d90f6f8be7262be", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamOpts.md": "3e94acde665c2a71a021593caadf11558723af1d6c5f49ce5568e9449197fcc0", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamToken.md": "c693c4478553e55f715f46518269da1b6ae2ab020cd6e639bdf20a57f3a6a37c", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxInfo.md": "51b792dc91c00c0f5ecb16677491c1f3dcc34b2e30cc1f7af433c051af1216ed", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxListOpts.md": "bf804e2ea39d835cba20e8c00636f2e466ad294c1630a3eb9262500fb14e4462", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetrics.md": "6a106c608cb3342ea41b708ec2d841b432bd4ce4ffb003037a1bb9facaea4ddb", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetricsOpts.md": "95a90db4c36b86e2d855965849dbba6d1b5e2b1cccb916fbb168464e657ac954", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxOpts.md": "0735fd0cc646b1a46ded791d36f6e73e0a68d2b7a038ca57ea147bc5c2c0ed56", + "sdk/javascript/sandbox/sandboxApi/interfaces/SandboxPauseOpts.md": "db3f46dc7f9653aa0165ee85a92de5d97d30f4f2fec9e7034cdeb6d625e3ce7c", + "sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotInfo.md": "84ef8016ef145ec1875e2479574bc48487856cd0a933835d7b11265dc8ea2776", + "sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotListOpts.md": "de16d942da289c61f41d39f39d7874cef2878852388049947184e6d79115f481", + "sdk/javascript/sandbox/sandboxApi/type-aliases/GitHubMcpServer.md": "543bc45cd5775ce52e2f199f4c8b6b5e0cad9b85f88d70bd36f61411f60cf873", + "sdk/javascript/sandbox/sandboxApi/type-aliases/McpServer.md": "af908c010089b8663f76520041771792e56ded927c94a7944b18fcdd86de2306", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxConnectOpts.md": "26b3e3bb550e86c143cc5540fa51d7b353ab1d44968f10f5767f069c89e3364b", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxIamTokenType.md": "1f5a4c23b63209e303d8937d24c99b6efcc9ab9d2bc411d657d39259e1e7cd3f", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxInfoLifecycle.md": "ae4807422fb962da0ca5f6ade53bfe79b9bf10ec85bbfe726076d640fbe492f3", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxLifecycle.md": "14702520802cbbe4182a7bd76fd1be0f624533cc2c7a3a189bb71cffbc10edd7", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkInfo.md": "af64327aa8900abe9aa9d421d85ee8f7cc989b99437100e4615a37657bd389e5", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkOpts.md": "7a45898ae2d7a6f78ddea277fc0412fe2f932cad41da88517440a4604399d73c", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRule.md": "1f1ed032d7a0f40d26d33977d7ef5cb96ff3b9a0aae055113c160eb1242f7741", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRuleInfo.md": "ce78abbe3c851bcbd34d83bb73f3d322d8ac10be17b334452b8e7f08019852f4", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRules.md": "29424e7c6f63b6c731a1a4e37c9d1db1569fc548e0b22ee3bc4c3cb143f738fc", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelector.md": "5e24a00dd86239d9601af780822004212e8e0671cf9ed1dc5c6d9bbf37a53a4e", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelectorContext.md": "56db302979385122e05233fc3e9d67231e67415b3f31d09972d03b8d513f96df", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransform.md": "e50309d3e0753dc12d06369a469c845481deb4db701635e8f9682eb829410343", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformContext.md": "42cdc1dcd0c8880dc0449a1cb2d37cfb4778217b8c340182790ab0bbe87459e4", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformResolver.md": "f0a75157d8cb7dee305a9caf58bac1d3717ff2ce44ed1f6d1ff79b0c7f7922e1", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkUpdate.md": "9a2b030bd4203906f38ba85c82978575f9e110e0816d3b56fafaf39e311747ff", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxOnTimeout.md": "a585ebbb7daf376e3486198841598b30040b816bf88b596b9ea765f00f2e0683", + "sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxState.md": "1489273567a77a83cc8a91389f5ce3ca088cb2ba289c2a11c442bdbfb07d7e27", + "sdk/javascript/templates/README.md": "2f1eb594c20f28fabf010749911d9fafd4b5b815dc59b3d400b75f346e1bf2f6", + "sdk/javascript/templates/classes/TemplateBase.md": "1d3a5dc108b747952bf4b20789521ae2b074e4cbcc0f339457fa502fe6788c2c", + "sdk/javascript/templates/interfaces/TemplateBuilder.md": "b19bc17ce1f968a492d9211802aacd3ead94552a46d1c313394d392826b0988b", + "sdk/javascript/templates/type-aliases/BuildInfo.md": "a15fd36415ea4efe21ec9cada3e72048b33529cada0fec41690ac12b5b06defe", + "sdk/javascript/templates/type-aliases/BuildOptions.md": "1f794dba0649a3b6b9964e70c1beadc29be6bbea0ed4cbaf0929d93dba9fb754", + "sdk/javascript/templates/type-aliases/BuildStatusReason.md": "c1a51ea8f9f5950a291b372bf939b8f271c280f2810f02813e88f625acac91cc", + "sdk/javascript/templates/type-aliases/CopyItem.md": "d71df73a594e4cb03fa222f0ee521e48307d5aa9a584fbbe0afe1b5eb1103f92", + "sdk/javascript/templates/type-aliases/GetBuildStatusOptions.md": "e72dc7271670924d0f2b1f3587c875218885cf571504a319fef3ccd8c74b7fc8", + "sdk/javascript/templates/type-aliases/McpServerName.md": "5f7c676e7a0240cd630c8d692f520d8d8e7f1c801f895c32f963be8243955c8f", + "sdk/javascript/templates/type-aliases/TemplateBuildStatus.md": "ef893242c02a3dcc0ea92b1c852d04e67e24da1d3442ccd1aa287b02d9e845fc", + "sdk/javascript/templates/type-aliases/TemplateBuildStatusResponse.md": "c049cdb468c647ab4cfcf5f0b728a12f38e1fe1e177778ea701b67cb3ca51a65", + "sdk/javascript/templates/type-aliases/TemplateClass.md": "28ca1c5a025e17d54b69d61ee69f52ecf205e68501f0089352e917805f585581", + "sdk/javascript/templates/type-aliases/TemplateTag.md": "74162c518610fa858fc7a5afd235413c5ffe4e5ca627de0f26016025b6c600a4", + "sdk/javascript/templates/type-aliases/TemplateTagInfo.md": "981a48f86db51afdf465b8f00f63cb21771bd6f227f9543d3120c3a57d6eb3f5", + "sdk/javascript/templates/variables/Template.md": "b637efaa6ec0ecc231302ecbbac8472a718415e4f5e2697f38a33ccf2d8e2553", + "sdk/python/code-interpreter-async.md": "2fcf8b77695cab09d90940343d955f0cf18de1d28a37f95032f967df286957e2", + "sdk/python/code-interpreter-sync.md": "51d85e86292e41cfcc94b232d7f451e5c1d45d3bbff03f21f9e677695aa0d18a", + "sdk/python/exceptions.md": "804b83597afdfa8a82ad4c40fae2327f00c84d557097d56afef7cb7ccd694144", + "sdk/python/logger.md": "13481eacc8f693495df7f82bede8a79cfee725d7db73952741557d26067647d5", + "sdk/python/ready-commands.md": "a4f8be5c446ea0f9ab192e9d40de4f27410a68425ff67ca1f57b3810367f0775", + "sdk/python/sandbox-async.md": "0d9e05b4c4043d3da7a6f2bdbadd3940af0f3b184a2ccb4ba1d799d7919276e5", + "sdk/python/sandbox-sync.md": "ecd3e7faed9b6042bdb041b822039c4997ae265cec304c6d18351f0737ab9c88", + "sdk/python/templates-async.md": "f5485b2595b9ccd9be8eda2990ed3341cddb39c5bcb0f9bdbcf9efc82dc8f3b3", + "sdk/python/templates-sync.md": "e1c5ce24c0e608ec0a3b248f0c19e90e521ec19a6e12626ecc23244afde3a249" + }, + "monoRevision": "559cf23aa80d22eeb1bd2769d4ab6646b8e40fcb", + "packages": { + "@abox-dev/cli": "0.1.0", + "@abox-dev/code-interpreter": "0.1.0", + "@abox-dev/sdk": "0.1.0", + "abox-code-interpreter": "0.1.0", + "abox-sdk": "0.1.0" + }, + "schemaVersion": 1 +} diff --git a/reference/openapi/control-plane.yml b/reference/openapi/control-plane.yml new file mode 100644 index 00000000..e8f6c103 --- /dev/null +++ b/reference/openapi/control-plane.yml @@ -0,0 +1,3126 @@ +openapi: 3.0.0 +info: + version: 0.1.0 + title: AgentBox API +servers: +- url: https://api.agentbox-runtime.ru +components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + 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 + required: true + schema: + type: string + buildID: + name: buildID + in: path + required: true + schema: + type: string + sandboxID: + name: sandboxID + in: path + required: true + schema: + type: string + teamID: + name: teamID + in: path + 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 + description: Maximum number of items to return per page + required: false + schema: + type: integer + format: int32 + minimum: 1 + default: 100 + maximum: 100 + paginationNextToken: + name: nextToken + in: query + description: Cursor to start the list from + 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 + schema: + type: string + XTotalRunning: + description: 'Number of running sandboxes matching the filters, before pagination + is applied. Only present when running sandboxes were requested. + + ' + schema: + type: integer + format: int32 + responses: + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '410': + description: Gone + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Server error + content: + application/json: + 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 + - email + properties: + id: + type: string + format: uuid + description: Identifier of the user + email: + type: string + nullable: true + deprecated: true + default: null + description: Email of the user + TemplateUpdateRequest: + properties: + public: + type: boolean + description: Whether the template is public or only accessible by the team + TemplateUpdateResponse: + required: + - names + properties: + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + CPUCount: + type: integer + format: int32 + minimum: 1 + description: CPU cores for the sandbox + MemoryMB: + type: integer + format: int32 + minimum: 128 + description: Memory for the sandbox in MiB + DiskSizeMB: + type: integer + format: int32 + minimum: 0 + description: Disk size for the sandbox in MiB + EnvdVersion: + type: string + description: Version of the envd running in the sandbox + SandboxMetadata: + additionalProperties: + type: string + description: Metadata of the sandbox + SandboxState: + type: string + description: State of the sandbox + enum: + - running + - paused + SnapshotInfo: + type: object + required: + - snapshotID + - names + properties: + snapshotID: + type: string + description: Identifier of the snapshot template including the tag. Uses + namespace/alias when a name was provided (e.g. team-slug/my-snapshot:default), + otherwise falls back to the raw template ID (e.g. abc123:default). + names: + type: array + items: + type: string + description: Full names of the snapshot template including team namespace + and tag (e.g. team-slug/my-snapshot:v2) + EnvVars: + additionalProperties: + type: string + description: Environment variables for the sandbox + Mcp: + type: object + description: MCP configuration for the sandbox + additionalProperties: {} + nullable: true + SandboxNetworkConfig: + type: object + properties: + allowPublicTraffic: + type: boolean + default: true + description: Specify if the sandbox URLs should be accessible only with + authentication. + allowOut: + type: array + description: 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. + items: + type: string + denyOut: + type: array + description: List of denied CIDR blocks or IP addresses for egress traffic. + Domain names are not supported for deny rules. + items: + type: string + maskRequestHost: + type: string + description: Specify host mask which will be used for all sandbox requests + rules: + type: object + description: '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. + + ' + additionalProperties: + type: array + items: + $ref: '#/components/schemas/SandboxNetworkRule' + SandboxNetworkUpdateConfig: + type: object + description: Network configuration update for a running sandbox. Replaces the + current egress rules with the provided configuration. Omitting a field clears + it. + properties: + allowOut: + type: array + description: 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. + items: + type: string + denyOut: + type: array + description: List of denied CIDR blocks or IP addresses for egress traffic. + Domain names are not supported for deny rules. + items: + type: string + rules: + type: object + description: Per-domain transform rules. Replaces all existing rules when + provided. + additionalProperties: + type: array + items: + $ref: '#/components/schemas/SandboxNetworkRule' + allow_internet_access: + type: boolean + description: 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. + SandboxNetworkRule: + type: object + description: Transform rule applied to egress requests matching a domain pattern. + properties: + transform: + $ref: '#/components/schemas/SandboxNetworkTransform' + SandboxNetworkTransform: + type: object + description: Transformations applied to matching egress requests before forwarding. + properties: + headers: + type: object + description: '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. + + ' + additionalProperties: + type: string + SandboxAutoResumeEnabled: + type: boolean + description: Auto-resume enabled flag for paused sandboxes. Default false. + default: false + SandboxAutoResumeConfig: + type: object + description: Auto-resume configuration for paused sandboxes. + required: + - enabled + properties: + enabled: + $ref: '#/components/schemas/SandboxAutoResumeEnabled' + SandboxOnTimeout: + type: string + description: Action taken when the sandbox times out. + enum: + - kill + - pause + SandboxLifecycle: + type: object + description: Sandbox lifecycle policy returned by sandbox info. + required: + - autoResume + - onTimeout + properties: + autoResume: + type: boolean + 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 + - level + - message + - fields + properties: + id: + type: string + description: Stable identifier used to reconcile overlapping live log pages + timestamp: + type: string + format: date-time + description: Timestamp of the log entry + message: + type: string + description: Log message content + level: + $ref: '#/components/schemas/LogLevel' + fields: + 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 + properties: + logs: + default: [] + description: Sandbox logs structured + type: array + items: + $ref: '#/components/schemas/SandboxLogEntry' + nextCursor: + type: string + description: Opaque continuation cursor for the next page + SandboxMetric: + description: Metric entry with timestamp and line + required: + - timestamp + - timestampUnix + - cpuCount + - cpuUsedPct + - memUsed + - memTotal + - memCache + - diskUsed + - diskTotal + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + cpuCount: + type: integer + format: int32 + description: Number of CPU cores + cpuUsedPct: + type: number + format: float + description: CPU usage percentage + memUsed: + type: integer + format: int64 + description: Memory used in bytes + memTotal: + type: integer + format: int64 + description: Total memory in bytes + memCache: + type: integer + format: int64 + description: Cached memory (page cache) in bytes + diskUsed: + type: integer + format: int64 + description: Disk used in bytes + diskTotal: + type: integer + format: int64 + description: Total disk space in bytes + SandboxVolumeMount: + type: object + properties: + name: + type: string + description: Name of the volume + path: + type: string + description: Path of the volume + required: + - name + - path + Sandbox: + required: + - templateID + - sandboxID + - clientID + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + sandboxID: + type: string + description: Identifier of the sandbox + alias: + type: string + description: Alias of the template + clientID: + type: string + deprecated: true + description: Identifier of the client + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + envdAccessToken: + type: string + description: Access token used for envd communication + trafficAccessToken: + type: string + nullable: true + description: Token required for accessing sandbox via proxy. + domain: + type: string + nullable: true + description: Base domain where the sandbox traffic is accessible + SandboxDetail: + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + alias: + type: string + description: Alias of the template + sandboxID: + type: string + description: Identifier of the sandbox + clientID: + type: string + deprecated: true + description: Identifier of the client + startedAt: + type: string + format: date-time + description: Time when the sandbox was started + endAt: + type: string + format: date-time + description: Time when the sandbox will expire + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + envdAccessToken: + type: string + description: Access token used for envd communication + allowInternetAccess: + type: boolean + nullable: true + description: Whether internet access was explicitly enabled or disabled + for the sandbox. Null means it was not explicitly set. + domain: + type: string + nullable: true + description: Base domain where the sandbox traffic is accessible + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + metadata: + $ref: '#/components/schemas/SandboxMetadata' + state: + $ref: '#/components/schemas/SandboxState' + network: + $ref: '#/components/schemas/SandboxNetworkConfig' + lifecycle: + $ref: '#/components/schemas/SandboxLifecycle' + volumeMounts: + type: array + items: + $ref: '#/components/schemas/SandboxVolumeMount' + ListedSandbox: + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + alias: + type: string + description: Alias of the template + sandboxID: + type: string + description: Identifier of the sandbox + clientID: + type: string + deprecated: true + description: Identifier of the client + startedAt: + type: string + format: date-time + description: Time when the sandbox was started + endAt: + type: string + format: date-time + description: Time when the sandbox will expire + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + metadata: + $ref: '#/components/schemas/SandboxMetadata' + state: + $ref: '#/components/schemas/SandboxState' + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + volumeMounts: + type: array + items: + $ref: '#/components/schemas/SandboxVolumeMount' + SandboxesWithMetrics: + required: + - sandboxes + properties: + sandboxes: + additionalProperties: + $ref: '#/components/schemas/SandboxMetric' + NewSandbox: + required: + - templateID + properties: + templateID: + type: string + description: Identifier of the required template + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: Time to live for the sandbox in seconds. + autoPause: + type: boolean + default: false + description: Automatically pauses the sandbox after the timeout + autoPauseMemory: + type: boolean + default: true + description: 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). + autoResume: + $ref: '#/components/schemas/SandboxAutoResumeConfig' + secure: + type: boolean + description: Secure all system communication with sandbox + allow_internet_access: + type: boolean + description: 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. + network: + $ref: '#/components/schemas/SandboxNetworkConfig' + metadata: + $ref: '#/components/schemas/SandboxMetadata' + envVars: + $ref: '#/components/schemas/EnvVars' + mcp: + $ref: '#/components/schemas/Mcp' + iam: + $ref: '#/components/schemas/SandboxIam' + volumeMounts: + type: array + items: + $ref: '#/components/schemas/SandboxVolumeMount' + SandboxIam: + type: object + description: Sandbox workload identity configuration. A non-empty, valid tokens + map enables workload identity for the sandbox. + properties: + tokens: + $ref: '#/components/schemas/SandboxIamTokens' + SandboxIamTokens: + type: object + description: Named workload-token definitions, keyed by a caller-chosen token + name. + additionalProperties: + $ref: '#/components/schemas/SandboxIamToken' + SandboxIamToken: + type: object + required: + - audience + - tokenType + properties: + audience: + type: string + description: Audience of the workload token, stored exactly as provided. + 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. + autoPause: + type: boolean + deprecated: true + description: Automatically pauses the sandbox after the timeout + ConnectSandbox: + type: object + required: + - timeout + properties: + timeout: + description: Timeout in seconds from the current time after which the sandbox + should expire + type: integer + format: int32 + minimum: 0 + SandboxTimeoutRequest: + type: object + required: + - timeout + properties: + timeout: + description: Timeout in seconds from the current time after which the sandbox + should expire + type: integer + format: int32 + minimum: 0 + SandboxRefreshRequest: + type: object + properties: + duration: + description: Duration for which the sandbox should be kept alive in seconds + type: integer + maximum: 3600 + minimum: 0 + SandboxSnapshotRequest: + type: object + properties: + name: + type: string + description: Optional name for the snapshot template. If a snapshot template + with this name already exists, a new build will be assigned to the existing + template instead of creating a new one. + SandboxPauseRequest: + type: object + properties: + memory: + type: boolean + default: true + description: Whether to capture a full memory snapshot. When false, only + the filesystem is persisted and resuming the sandbox cold-boots (reboots) + it from disk, losing in-memory state, running processes, and open connections. + Resume it with an explicit request (connect or resume); auto-resume, which + can be triggered by arbitrary traffic, refuses such a sandbox. Defaults + to true. + SandboxForkRequest: + type: object + properties: + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: Time to live for the new forked sandboxes in seconds. + count: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 1 + description: 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. + SandboxForkResult: + type: object + description: 'Result of one requested fork. Exactly one of sandbox or error + is set: sandbox when the fork started successfully, error when it failed to + start.' + properties: + sandbox: + $ref: '#/components/schemas/Sandbox' + error: + $ref: '#/components/schemas/Error' + TeamMetric: + description: Team metric with timestamp + required: + - timestamp + - timestampUnix + - concurrentSandboxes + - sandboxStartRate + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + concurrentSandboxes: + type: integer + format: int32 + description: The number of concurrent sandboxes for the team + sandboxStartRate: + type: number + format: float + description: Number of sandboxes started per second + MaxTeamMetric: + description: Team metric with timestamp + required: + - timestamp + - timestampUnix + - value + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + 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 + VolumeToken: + type: object + properties: + token: + type: string + required: + - token + Template: + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + - names + - buildStatus + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + buildCount: + type: integer + format: int32 + description: Number of times the template was built + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + buildStatus: + $ref: '#/components/schemas/TemplateBuildStatus' + TemplateRequestResponseV3: + required: + - templateID + - buildID + - public + - aliases + - names + - tags + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + public: + type: boolean + description: Whether the template is public or only accessible by the team + names: + type: array + description: Names of the template + items: + type: string + tags: + type: array + description: Tags assigned to the template build + items: + type: string + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + TemplateLegacy: + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + buildCount: + type: integer + format: int32 + description: Number of times the template was built + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + TemplateBuild: + required: + - buildID + - status + - createdAt + - updatedAt + - cpuCount + - memoryMB + properties: + buildID: + type: string + format: uuid + description: Identifier of the build + status: + $ref: '#/components/schemas/TemplateBuildStatus' + createdAt: + type: string + format: date-time + description: Time when the build was created + updatedAt: + type: string + format: date-time + description: Time when the build was last updated + finishedAt: + type: string + format: date-time + description: Time when the build was finished + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + TemplateWithBuilds: + required: + - templateID + - public + - aliases + - names + - createdAt + - updatedAt + - lastSpawnedAt + - spawnCount + - builds + properties: + templateID: + type: string + description: Identifier of the template + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + builds: + type: array + description: List of builds for the template + items: + $ref: '#/components/schemas/TemplateBuild' + TemplateAliasResponse: + required: + - templateID + - public + properties: + templateID: + type: string + description: Identifier of the template + 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: + - type + properties: + type: + type: string + description: Type of the step + args: + default: [] + type: array + description: Arguments for the step + items: + type: string + filesHash: + type: string + description: Hash of the files used in the step + force: + default: false + type: boolean + description: Whether the step should be forced to run regardless of the + cache + TemplateBuildRequestV3: + properties: + name: + description: 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. + type: string + maxLength: 128 + tags: + type: array + description: Tags to assign to the template build + items: + type: string + alias: + description: Alias of the template. Deprecated, use name instead. + type: string + maxLength: 128 + deprecated: true + teamID: + deprecated: true + type: string + description: Identifier of the team + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + TemplateBuildRequestV2: + required: + - alias + properties: + alias: + description: Alias of the template + type: string + teamID: + deprecated: true + type: string + description: Identifier of the team + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + FromImageRegistry: + oneOf: + - $ref: '#/components/schemas/AWSRegistry' + - $ref: '#/components/schemas/GCPRegistry' + - $ref: '#/components/schemas/GeneralRegistry' + discriminator: + propertyName: type + mapping: + aws: '#/components/schemas/AWSRegistry' + gcp: '#/components/schemas/GCPRegistry' + registry: '#/components/schemas/GeneralRegistry' + AWSRegistry: + type: object + required: + - type + - awsAccessKeyId + - awsSecretAccessKey + - awsRegion + properties: + type: + type: string + enum: + - aws + description: Type of registry authentication + awsAccessKeyId: + type: string + description: AWS Access Key ID for ECR authentication + awsSecretAccessKey: + type: string + description: AWS Secret Access Key for ECR authentication + awsRegion: + type: string + description: AWS Region where the ECR registry is located + GCPRegistry: + type: object + required: + - type + - serviceAccountJson + properties: + type: + type: string + enum: + - gcp + description: Type of registry authentication + serviceAccountJson: + type: string + description: Service Account JSON for GCP authentication + GeneralRegistry: + type: object + required: + - type + - username + - password + properties: + type: + type: string + enum: + - registry + description: Type of registry authentication + username: + type: string + description: Username to use for the registry + password: + type: string + description: Password to use for the registry + TemplateBuildStartV2: + type: object + properties: + fromImage: + type: string + description: Image to use as a base for the template build + fromTemplate: + type: string + description: Template to use as a base for the template build + fromImageRegistry: + $ref: '#/components/schemas/FromImageRegistry' + force: + default: false + type: boolean + description: Whether the whole build should be forced to run regardless + of the cache + steps: + default: [] + description: List of steps to execute in the template build + type: array + items: + $ref: '#/components/schemas/TemplateStep' + 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 + TemplateBuildFileUpload: + required: + - present + properties: + present: + type: boolean + description: Whether the file is already present in the cache + url: + description: Url where the file should be uploaded to + type: string + LogLevel: + type: string + description: State of the sandbox + enum: + - debug + - info + - warn + - error + BuildLogEntry: + required: + - timestamp + - message + - level + properties: + id: + type: string + description: Stable identifier used to reconcile overlapping live log pages + timestamp: + type: string + format: date-time + description: Timestamp of the log entry + message: + type: string + description: Log message content + level: + $ref: '#/components/schemas/LogLevel' + step: + type: string + description: Step in the build process related to the log entry + BuildStatusReason: + required: + - message + properties: + message: + type: string + description: Message with the status reason, currently reporting only for + error status + step: + type: string + description: Step that failed + logEntries: + default: [] + description: Log entries related to the status reason + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + TemplateBuildStatus: + type: string + description: Status of the template build + enum: + - building + - waiting + - ready + - error + TemplateBuildInfo: + required: + - templateID + - buildID + - status + - logs + - logEntries + properties: + logs: + default: [] + description: Build logs + type: array + items: + type: string + logEntries: + default: [] + description: Build logs structured + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the build + status: + $ref: '#/components/schemas/TemplateBuildStatus' + reason: + $ref: '#/components/schemas/BuildStatusReason' + TemplateBuildLogsResponse: + required: + - logs + properties: + logs: + default: [] + description: Build logs structured + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + nextCursor: + type: string + description: Opaque continuation cursor for the next page + source: + $ref: '#/components/schemas/LogsSource' + description: Actual source used to serve this page + LogsDirection: + type: string + description: Direction of the logs that should be returned + enum: + - forward + - backward + LogsSource: + type: string + description: Source of the logs that should be returned + 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 + CreatedAccessToken: + required: + - id + - name + - token + - mask + - createdAt + properties: + id: + type: string + format: uuid + description: Identifier of the access token + name: + type: string + description: Name of the access token + token: + type: string + description: The fully created access token + mask: + $ref: '#/components/schemas/IdentifierMaskingDetails' + createdAt: + type: string + format: date-time + description: Timestamp of access token creation + NewAccessToken: + required: + - name + properties: + name: + type: string + description: Name of the access token + 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 + - buildID + properties: + tags: + type: array + items: + type: string + description: Assigned tags of the template + buildID: + type: string + format: uuid + description: Identifier of the build associated with these tags + TemplateTag: + required: + - tag + - buildID + - createdAt + properties: + tag: + type: string + description: The tag name + buildID: + type: string + format: uuid + description: Identifier of the build associated with this tag + createdAt: + type: string + format: date-time + description: Time when the tag was assigned + AssignTemplateTagsRequest: + required: + - target + - tags + properties: + target: + type: string + description: Target template in "name:tag" format + tags: + description: Tags to assign to the template + type: array + items: + type: string + DeleteTemplateTagsRequest: + required: + - name + - tags + properties: + name: + type: string + description: Name of the template + tags: + description: Tags to delete + type: array + items: + type: string + Error: + required: + - code + - message + properties: + code: + type: integer + format: int32 + description: Error code + 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 + Volume: + type: object + properties: + volumeID: + type: string + description: ID of the volume + name: + type: string + description: Name of the volume + required: + - volumeID + - name + VolumeAndToken: + type: object + properties: + volumeID: + type: string + description: ID of the volume + name: + type: string + description: Name of the volume + token: + type: string + description: Auth token to use for interacting with volume content + domain: + type: string + description: 'Domain to use as the destination for volume content requests, + + replacing the default `api.`. Only returned when the + + team is connected to a custom (BYOC) cluster; absent otherwise, in + + which case the default domain is used. + + ' + required: + - volumeID + - name + - token + NewVolume: + type: object + properties: + name: + type: string + description: Name of the volume + pattern: ^[a-zA-Z0-9_-]+$ + required: + - name +tags: +- name: sandboxes +- name: snapshots +- name: tags +- name: team-metrics +- name: templates +paths: + /teams/{teamID}/metrics: + get: + summary: Team metrics + description: Get metrics for the team + tags: + - team-metrics + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/teamID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for + which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for + which the metrics + responses: + '200': + description: Successfully returned the team metrics + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TeamMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + operationId: getTeamMetrics + /teams/{teamID}/metrics/max: + get: + summary: Maximum team metrics + description: Get the maximum metrics for the team in the given interval + tags: + - team-metrics + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/teamID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for + which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for + which the metrics + - in: query + name: metric + required: true + schema: + type: string + enum: + - concurrent_sandboxes + - sandbox_start_rate + description: Metric to retrieve the maximum value for + responses: + '200': + description: Successfully returned the team metrics + content: + application/json: + schema: + $ref: '#/components/schemas/MaxTeamMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + operationId: getTeamMetricsMax + /sandboxes: + post: + summary: Create sandbox + description: Create a sandbox from the template + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/NewSandbox' + responses: + '201': + description: The sandbox was created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '401': + $ref: '#/components/responses/401' + '400': + $ref: '#/components/responses/400' + '500': + $ref: '#/components/responses/500' + operationId: createSandbox + /v2/sandboxes: + get: + summary: List sandboxes (v2) + description: List all sandboxes + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - name: metadata + in: query + description: Metadata query used to filter the sandboxes (e.g. "user=abc&app=prod"). + Each key and values must be URL encoded. + required: false + schema: + type: string + - name: state + in: query + description: Filter sandboxes by one or more states + required: false + schema: + type: array + items: + $ref: '#/components/schemas/SandboxState' + style: form + explode: false + - $ref: '#/components/parameters/paginationNextToken' + - $ref: '#/components/parameters/paginationLimit' + responses: + '200': + description: Successfully returned all running sandboxes + headers: + X-Next-Token: + $ref: '#/components/headers/XNextToken' + X-Total-Running: + $ref: '#/components/headers/XTotalRunning' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ListedSandbox' + '401': + $ref: '#/components/responses/401' + '400': + $ref: '#/components/responses/400' + '500': + $ref: '#/components/responses/500' + operationId: listSandboxes + /sandboxes/metrics: + get: + summary: List sandbox metrics + description: List metrics for given sandboxes + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - name: sandbox_ids + in: query + required: true + description: Comma-separated list of sandbox IDs to get metrics for + explode: false + schema: + type: array + items: + type: string + maxItems: 100 + uniqueItems: true + responses: + '200': + description: Successfully returned all running sandboxes with metrics + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxesWithMetrics' + '401': + $ref: '#/components/responses/401' + '400': + $ref: '#/components/responses/400' + '500': + $ref: '#/components/responses/500' + operationId: listSandboxMetrics + /v2/sandboxes/{sandboxID}/logs: + get: + summary: Sandbox logs (v2) + description: Get sandbox logs + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + - in: query + name: pageCursor + schema: + type: string + maxLength: 512 + description: Opaque continuation cursor returned as nextCursor by the previous + page + - in: query + name: cursor + schema: + type: integer + format: int64 + minimum: 0 + description: Starting timestamp of the logs that should be returned in milliseconds + - in: query + name: limit + schema: + default: 1000 + type: integer + format: int32 + minimum: 0 + maximum: 1000 + description: Maximum number of logs that should be returned + - in: query + name: direction + schema: + $ref: '#/components/schemas/LogsDirection' + description: Direction of the logs that should be returned + - in: query + name: level + schema: + $ref: '#/components/schemas/LogLevel' + description: Minimum log level to return. Logs below this level are excluded + - in: query + name: search + schema: + type: string + maxLength: 256 + description: Case-sensitive substring match on log message content + responses: + '200': + description: Successfully returned the sandbox logs + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxLogsV2Response' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getSandboxLogs + /sandboxes/{sandboxID}: + get: + summary: Sandbox + description: Get a sandbox by id + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '200': + description: Successfully returned the sandbox + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxDetail' + '404': + $ref: '#/components/responses/404' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: getSandbox + delete: + summary: Kill sandbox + description: Kill a sandbox + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: The sandbox was killed successfully + '404': + $ref: '#/components/responses/404' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: killSandbox + /sandboxes/{sandboxID}/metrics: + get: + summary: Sandbox metrics + description: Get sandbox metrics + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for + which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for + which the metrics + responses: + '200': + description: Successfully returned the sandbox metrics + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SandboxMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getSandboxMetrics + /sandboxes/{sandboxID}/pause: + post: + summary: Pause sandbox + description: Pause the sandbox + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxPauseRequest' + responses: + '204': + description: The sandbox was paused successfully and can be resumed + '409': + $ref: '#/components/responses/409' + '404': + $ref: '#/components/responses/404' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: pauseSandbox + /sandboxes/{sandboxID}/fork: + post: + summary: Fork sandbox + description: 'Fork the sandbox: checkpoint the running sandbox in place (it + is briefly paused, snapshotted with its full memory state, and resumed on + its node, keeping its ID and expiration untouched) and create count new sandboxes + from that snapshot. Returns one result per requested fork, each carrying either + the created sandbox or the error that prevented it from starting. A non-201 + status means the request failed before any fork was attempted.' + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxForkRequest' + responses: + '201': + description: The sandbox was snapshotted and the forks were attempted; each + entry reports one fork's outcome + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SandboxForkResult' + '409': + $ref: '#/components/responses/409' + '404': + $ref: '#/components/responses/404' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: forkSandbox + /sandboxes/{sandboxID}/connect: + post: + summary: Connect sandbox + description: Returns sandbox details. If the sandbox is paused, it will be resumed. + TTL is only extended. + tags: + - sandboxes + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectSandbox' + responses: + '200': + description: The sandbox was already running + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '201': + description: The sandbox was resumed successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: connectSandbox + /sandboxes/{sandboxID}/timeout: + post: + summary: Set sandbox timeout + description: Set the timeout for the sandbox. The sandbox will expire x seconds + from the time of the request. Calling this method multiple times overwrites + the TTL, each time using the current timestamp as the starting point to measure + the timeout duration. + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + tags: + - sandboxes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxTimeoutRequest' + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: Successfully set the sandbox timeout + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: setSandboxTimeout + /sandboxes/{sandboxID}/network: + put: + summary: Update sandbox network + description: Update the network configuration for a running sandbox. Replaces + the current egress rules with the provided configuration. Omitting field clears + it. + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + tags: + - sandboxes + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxNetworkUpdateConfig' + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: Successfully updated the sandbox network configuration + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '409': + $ref: '#/components/responses/409' + '500': + $ref: '#/components/responses/500' + operationId: updateSandboxNetwork + /sandboxes/{sandboxID}/refreshes: + post: + summary: Refresh sandbox + description: Refresh the sandbox extending its time to live + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + tags: + - sandboxes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxRefreshRequest' + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: Successfully refreshed the sandbox + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + operationId: refreshSandbox + /sandboxes/{sandboxID}/snapshots: + post: + summary: Create snapshot + description: Create a persistent snapshot from the sandbox's current state. + Snapshots can be used to create new sandboxes and persist beyond the original + sandbox's lifetime. + tags: + - snapshots + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxSnapshotRequest' + responses: + '201': + description: Snapshot created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/SnapshotInfo' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: createSnapshot + /snapshots: + get: + summary: List snapshots + description: List all snapshots for the team + tags: + - snapshots + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - name: sandboxID + in: query + required: false + schema: + type: string + description: Filter snapshots by source sandbox ID + - name: name + in: query + description: Filter snapshots by name or ID, optionally tag-qualified (e.g. + "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1"). + required: false + schema: + type: string + - $ref: '#/components/parameters/paginationLimit' + - $ref: '#/components/parameters/paginationNextToken' + responses: + '200': + description: Successfully returned snapshots + headers: + X-Next-Token: + $ref: '#/components/headers/XNextToken' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SnapshotInfo' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: listSnapshots + /v3/templates: + post: + summary: Create template (v3) + description: Create a new template + tags: + - templates + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildRequestV3' + responses: + '202': + description: The build was requested successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateRequestResponseV3' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + operationId: createTemplate + /v2/templates: + get: + summary: List templates (v2) + description: List all templates + tags: + - templates + security: + - ApiKeyAuth: [] + - AccessTokenAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - in: query + required: false + name: teamID + schema: + type: string + description: Identifier of the team + - $ref: '#/components/parameters/paginationNextToken' + - $ref: '#/components/parameters/paginationLimit' + responses: + '200': + description: Successfully returned all templates + headers: + X-Next-Token: + $ref: '#/components/headers/XNextToken' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Template' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + operationId: listTemplates + /templates/{templateID}/files/{hash}: + get: + summary: Template build file upload URL + description: Get an upload link for a tar file containing build layer files + tags: + - templates + security: + - AccessTokenAuth: [] + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - in: path + name: hash + required: true + schema: + type: string + description: Hash of the files + responses: + '201': + description: The upload link where to upload the tar file + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildFileUpload' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getTemplateUploadUrl + /templates/{templateID}: + get: + summary: List template builds + description: List all builds for a template + tags: + - templates + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/paginationNextToken' + - $ref: '#/components/parameters/paginationLimit' + responses: + '200': + description: Successfully returned the template with its builds + headers: + X-Next-Token: + $ref: '#/components/headers/XNextToken' + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateWithBuilds' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: getTemplate + delete: + summary: Delete template + description: Delete a template + tags: + - templates + security: + - ApiKeyAuth: [] + - AccessTokenAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + responses: + '204': + description: The template was deleted successfully + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: deleteTemplate + /v2/templates/{templateID}/builds/{buildID}: + post: + summary: Start template build (v2) + description: Start the build + tags: + - templates + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildStartV2' + responses: + '202': + description: The build has started + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: startTemplateBuild + /v2/templates/{templateID}: + patch: + summary: Update template (v2) + description: Update template + tags: + - templates + security: + - ApiKeyAuth: [] + - AccessTokenAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateUpdateRequest' + responses: + '200': + description: The template was updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateUpdateResponse' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + operationId: updateTemplate + /templates/{templateID}/builds/{buildID}/status: + get: + summary: Template build status + description: Get template build info + tags: + - templates + security: + - AccessTokenAuth: [] + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + - in: query + name: logsOffset + schema: + default: 0 + type: integer + format: int32 + minimum: 0 + description: Index of the starting build log that should be returned with + the template + - in: query + name: limit + schema: + default: 100 + type: integer + format: int32 + minimum: 0 + maximum: 100 + description: Maximum number of logs that should be returned + - in: query + name: level + schema: + $ref: '#/components/schemas/LogLevel' + responses: + '200': + description: Successfully returned the template + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildInfo' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getTemplateBuildStatus + /templates/{templateID}/builds/{buildID}/logs: + get: + summary: Template build logs + description: Get template build logs + tags: + - templates + security: + - AccessTokenAuth: [] + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + - in: query + name: pageCursor + schema: + type: string + maxLength: 512 + description: Opaque continuation cursor returned as nextCursor by the previous + page + - in: query + name: cursor + schema: + type: integer + format: int64 + minimum: 0 + description: Starting timestamp of the logs that should be returned in milliseconds + - in: query + name: limit + schema: + default: 100 + type: integer + format: int32 + minimum: 0 + maximum: 100 + description: Maximum number of logs that should be returned + - in: query + name: direction + schema: + $ref: '#/components/schemas/LogsDirection' + - in: query + name: level + schema: + $ref: '#/components/schemas/LogLevel' + - in: query + name: source + schema: + $ref: '#/components/schemas/LogsSource' + description: Source of the logs that should be returned from + responses: + '200': + description: Successfully returned the template build logs + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildLogsResponse' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getTemplateBuildLogs + /templates/tags: + post: + summary: Assign template tags + description: Assign tag(s) to a template build + tags: + - tags + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AssignTemplateTagsRequest' + responses: + '201': + description: Tag assigned successfully + content: + application/json: + schema: + $ref: '#/components/schemas/AssignedTemplateTags' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: assignTemplateTags + delete: + summary: Delete template tags + description: Delete multiple tags from templates + tags: + - tags + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteTemplateTagsRequest' + responses: + '204': + description: Tags deleted successfully + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: deleteTemplateTags + /templates/{templateID}/tags: + get: + summary: List template tags + description: List all tags for a template + tags: + - tags + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + responses: + '200': + description: Successfully returned the template tags + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TemplateTag' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: listTemplateTags + /templates/aliases/{alias}: + get: + summary: Check template alias + description: Check if template with given alias exists + tags: + - templates + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + parameters: + - name: alias + in: path + required: true + schema: + type: string + description: Template alias + responses: + '200': + description: Successfully queried template by alias + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateAliasResponse' + '400': + $ref: '#/components/responses/400' + '403': + $ref: '#/components/responses/403' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + operationId: getTemplateByAlias diff --git a/reference/openapi/envd.yml b/reference/openapi/envd.yml new file mode 100644 index 00000000..918e65f0 --- /dev/null +++ b/reference/openapi/envd.yml @@ -0,0 +1,435 @@ +openapi: 3.0.0 +info: + title: envd + version: 0.1.3 + description: API for managing files' content and controlling envd +tags: +- name: environment +- name: files +paths: + /health: + get: + summary: Check the health of the service + responses: + '204': + description: The service is healthy + operationId: getEnvironmentHealth + tags: + - environment + /metrics: + get: + summary: Service stats + security: + - AccessTokenAuth: [] + - {} + responses: + '200': + description: The resource usage metrics of the service + content: + application/json: + schema: + $ref: '#/components/schemas/Metrics' + operationId: getEnvironmentMetrics + tags: + - environment + /envs: + get: + summary: Environment variables + security: + - AccessTokenAuth: [] + - {} + responses: + '200': + description: Environment variables + content: + application/json: + schema: + $ref: '#/components/schemas/EnvVars' + operationId: getEnvironmentVariables + tags: + - environment + /files: + get: + summary: Download a file + tags: + - files + security: + - AccessTokenAuth: [] + - {} + parameters: + - $ref: '#/components/parameters/FilePath' + - $ref: '#/components/parameters/User' + - $ref: '#/components/parameters/Signature' + - $ref: '#/components/parameters/SignatureExpiration' + responses: + '200': + $ref: '#/components/responses/DownloadSuccess' + '400': + $ref: '#/components/responses/InvalidPath' + '401': + $ref: '#/components/responses/InvalidUser' + '404': + $ref: '#/components/responses/FileNotFound' + '406': + $ref: '#/components/responses/NotAcceptable' + '500': + $ref: '#/components/responses/InternalServerError' + operationId: downloadFile + post: + summary: Upload a file and ensure the parent directories exist. If the file + exists, it will be overwritten. + description: 'Any request header of the form `X-Metadata-: ` is + persisted + + as a user-defined extended attribute on the uploaded file. The + + `X-Metadata-` prefix is stripped and the remaining header name is + + lowercased to form the metadata key; the resulting map is returned on + + `EntryInfo` lookups (e.g. `Stat`, `ListDir`). + + + Each upload replaces the file''s metadata with the keys provided in + + that request: keys previously stored but absent from the new request + + are removed, and an upload that sends no `X-Metadata-*` header clears + + all existing metadata. + + + Both keys and values must be printable US-ASCII (bytes `0x20`-`0x7E`) + + and are rejected with HTTP 400 otherwise. Each key is capped at 246 + + bytes (the Linux VFS xattr-name limit minus the namespace prefix), and + + the combined size of all metadata on a file (keys plus values, with the + + namespace prefix counted per key) is capped at 4096 bytes to stay within + + the filesystem''s per-inode xattr budget. Multiple files in a single + + multipart upload receive the same metadata. If the same + + `X-Metadata-` header is sent more than once, only the first + + value is used. + + ' + tags: + - files + security: + - AccessTokenAuth: [] + - {} + parameters: + - $ref: '#/components/parameters/FilePath' + - $ref: '#/components/parameters/User' + - $ref: '#/components/parameters/Signature' + - $ref: '#/components/parameters/SignatureExpiration' + requestBody: + $ref: '#/components/requestBodies/File' + responses: + '200': + $ref: '#/components/responses/UploadSuccess' + '400': + $ref: '#/components/responses/InvalidPath' + '401': + $ref: '#/components/responses/InvalidUser' + '500': + $ref: '#/components/responses/InternalServerError' + '507': + $ref: '#/components/responses/NotEnoughDiskSpace' + operationId: uploadFile + /files/compose: + post: + summary: Compose multiple files into a single file using zero-copy concatenation. + Source files are deleted after successful composition. + tags: + - files + security: + - AccessTokenAuth: [] + - {} + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ComposeRequest' + responses: + '200': + description: Files composed successfully + content: + application/json: + schema: + $ref: '#/components/schemas/EntryInfo' + '400': + $ref: '#/components/responses/InvalidPath' + '401': + $ref: '#/components/responses/InvalidUser' + '404': + $ref: '#/components/responses/FileNotFound' + '500': + $ref: '#/components/responses/InternalServerError' + '507': + $ref: '#/components/responses/NotEnoughDiskSpace' + operationId: composeFiles +components: + securitySchemes: {} + parameters: + FilePath: + name: path + in: query + required: false + description: Path to the file, URL encoded. Can be relative to the user's home + directory (e.g. "file.txt" resolves to ~/file.txt). + schema: + type: string + User: + name: username + in: query + required: false + description: User for setting file ownership and resolving relative paths. Defaults + to the sandbox's default user. + schema: + type: string + Signature: + name: signature + in: query + required: false + description: Signature used for file access permission verification. + schema: + type: string + SignatureExpiration: + name: signature_expiration + in: query + required: false + description: Unix timestamp (seconds) after which the signature expires. Only + used with the signature parameter. + schema: + type: integer + requestBodies: + File: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + application/octet-stream: + schema: + type: string + format: binary + description: Raw file content. The 'path' query parameter is required + when using this content type. + responses: + UploadSuccess: + description: The file was uploaded successfully. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/EntryInfo' + example: + - path: /home/user/hello.txt + name: hello.txt + type: file + DownloadSuccess: + description: Entire file downloaded successfully. + content: + application/octet-stream: + schema: + type: string + format: binary + description: The raw file content + NotAcceptable: + description: Requested encoding is not supported + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: 'no acceptable encoding found, supported: [identity, gzip]' + code: 406 + InvalidPath: + description: Invalid path + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: path '/home/user/docs' is a directory + code: 400 + InternalServerError: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: 'error opening file ''/home/user/file.txt'': permission denied' + code: 500 + FileNotFound: + description: File not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: path '/home/user/missing.txt' does not exist + code: 404 + InvalidUser: + description: Invalid user + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: 'error looking up user ''nonexistent'': user: unknown user nonexistent' + code: 401 + NotEnoughDiskSpace: + description: Not enough disk space + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + message: not enough disk space available + code: 507 + schemas: + Error: + required: + - message + - code + properties: + message: + type: string + description: Error message + code: + type: integer + description: Error code + EntryInfo: + required: + - path + - name + - type + properties: + path: + type: string + description: Path to the file + name: + type: string + description: Name of the file + type: + type: string + description: Type of the file + enum: + - file + metadata: + type: object + description: User-defined metadata stored as extended attributes on the + file. + additionalProperties: + type: string + EnvVars: + type: object + description: Environment variables to set + additionalProperties: + type: string + Metrics: + type: object + description: Resource usage metrics + properties: + ts: + type: integer + format: int64 + description: Unix timestamp in UTC for current sandbox time + cpu_count: + type: integer + description: Number of CPU cores + cpu_used_pct: + type: number + format: float + description: CPU usage percentage + mem_total: + type: integer + description: Total virtual memory in bytes + mem_used: + type: integer + description: Used virtual memory in bytes + mem_cache: + type: integer + description: Cached memory (page cache) in bytes + mem_total_mib: + type: integer + description: Total virtual memory in MiB + mem_used_mib: + type: integer + description: Used virtual memory in MiB + disk_used: + type: integer + description: Used disk space in bytes + 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: + - source_paths + - destination + properties: + source_paths: + type: array + items: + type: string + description: Ordered list of source file paths to concatenate + destination: + type: string + description: Destination file path for the composed file + 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 diff --git a/reference/openapi/operations.json b/reference/openapi/operations.json new file mode 100644 index 00000000..1f652095 --- /dev/null +++ b/reference/openapi/operations.json @@ -0,0 +1,290 @@ +[ + { + "operationId": "connectSandbox", + "method": "POST", + "path": "/sandboxes/{sandboxID}/connect", + "group": "sandboxes", + "slug": "connect", + "spec": "control-plane" + }, + { + "operationId": "createSandbox", + "method": "POST", + "path": "/sandboxes", + "group": "sandboxes", + "slug": "create", + "spec": "control-plane" + }, + { + "operationId": "forkSandbox", + "method": "POST", + "path": "/sandboxes/{sandboxID}/fork", + "group": "sandboxes", + "slug": "fork", + "spec": "control-plane" + }, + { + "operationId": "getSandbox", + "method": "GET", + "path": "/sandboxes/{sandboxID}", + "group": "sandboxes", + "slug": "get", + "spec": "control-plane" + }, + { + "operationId": "killSandbox", + "method": "DELETE", + "path": "/sandboxes/{sandboxID}", + "group": "sandboxes", + "slug": "kill", + "spec": "control-plane" + }, + { + "operationId": "listSandboxes", + "method": "GET", + "path": "/v2/sandboxes", + "group": "sandboxes", + "slug": "list", + "spec": "control-plane" + }, + { + "operationId": "listSandboxMetrics", + "method": "GET", + "path": "/sandboxes/metrics", + "group": "sandboxes", + "slug": "list-metrics", + "spec": "control-plane" + }, + { + "operationId": "getSandboxLogs", + "method": "GET", + "path": "/v2/sandboxes/{sandboxID}/logs", + "group": "sandboxes", + "slug": "logs", + "spec": "control-plane" + }, + { + "operationId": "getSandboxMetrics", + "method": "GET", + "path": "/sandboxes/{sandboxID}/metrics", + "group": "sandboxes", + "slug": "metrics", + "spec": "control-plane" + }, + { + "operationId": "updateSandboxNetwork", + "method": "PUT", + "path": "/sandboxes/{sandboxID}/network", + "group": "sandboxes", + "slug": "network", + "spec": "control-plane" + }, + { + "operationId": "pauseSandbox", + "method": "POST", + "path": "/sandboxes/{sandboxID}/pause", + "group": "sandboxes", + "slug": "pause", + "spec": "control-plane" + }, + { + "operationId": "refreshSandbox", + "method": "POST", + "path": "/sandboxes/{sandboxID}/refreshes", + "group": "sandboxes", + "slug": "refresh", + "spec": "control-plane" + }, + { + "operationId": "setSandboxTimeout", + "method": "POST", + "path": "/sandboxes/{sandboxID}/timeout", + "group": "sandboxes", + "slug": "timeout", + "spec": "control-plane" + }, + { + "operationId": "createSnapshot", + "method": "POST", + "path": "/sandboxes/{sandboxID}/snapshots", + "group": "snapshots", + "slug": "create", + "spec": "control-plane" + }, + { + "operationId": "listSnapshots", + "method": "GET", + "path": "/snapshots", + "group": "snapshots", + "slug": "list", + "spec": "control-plane" + }, + { + "operationId": "assignTemplateTags", + "method": "POST", + "path": "/templates/tags", + "group": "tags", + "slug": "assign", + "spec": "control-plane" + }, + { + "operationId": "deleteTemplateTags", + "method": "DELETE", + "path": "/templates/tags", + "group": "tags", + "slug": "delete", + "spec": "control-plane" + }, + { + "operationId": "listTemplateTags", + "method": "GET", + "path": "/templates/{templateID}/tags", + "group": "tags", + "slug": "list", + "spec": "control-plane" + }, + { + "operationId": "getTeamMetrics", + "method": "GET", + "path": "/teams/{teamID}/metrics", + "group": "team-metrics", + "slug": "team-metrics", + "spec": "control-plane" + }, + { + "operationId": "getTeamMetricsMax", + "method": "GET", + "path": "/teams/{teamID}/metrics/max", + "group": "team-metrics", + "slug": "team-metrics-max", + "spec": "control-plane" + }, + { + "operationId": "getTemplateByAlias", + "method": "GET", + "path": "/templates/aliases/{alias}", + "group": "templates", + "slug": "alias", + "spec": "control-plane" + }, + { + "operationId": "getTemplateBuildLogs", + "method": "GET", + "path": "/templates/{templateID}/builds/{buildID}/logs", + "group": "templates", + "slug": "build-logs", + "spec": "control-plane" + }, + { + "operationId": "getTemplateBuildStatus", + "method": "GET", + "path": "/templates/{templateID}/builds/{buildID}/status", + "group": "templates", + "slug": "build-status", + "spec": "control-plane" + }, + { + "operationId": "createTemplate", + "method": "POST", + "path": "/v3/templates", + "group": "templates", + "slug": "create", + "spec": "control-plane" + }, + { + "operationId": "deleteTemplate", + "method": "DELETE", + "path": "/templates/{templateID}", + "group": "templates", + "slug": "delete", + "spec": "control-plane" + }, + { + "operationId": "getTemplate", + "method": "GET", + "path": "/templates/{templateID}", + "group": "templates", + "slug": "get", + "spec": "control-plane" + }, + { + "operationId": "listTemplates", + "method": "GET", + "path": "/v2/templates", + "group": "templates", + "slug": "list", + "spec": "control-plane" + }, + { + "operationId": "startTemplateBuild", + "method": "POST", + "path": "/v2/templates/{templateID}/builds/{buildID}", + "group": "templates", + "slug": "start-build", + "spec": "control-plane" + }, + { + "operationId": "updateTemplate", + "method": "PATCH", + "path": "/v2/templates/{templateID}", + "group": "templates", + "slug": "update", + "spec": "control-plane" + }, + { + "operationId": "getTemplateUploadUrl", + "method": "GET", + "path": "/templates/{templateID}/files/{hash}", + "group": "templates", + "slug": "upload-url", + "spec": "control-plane" + }, + { + "operationId": "getEnvironmentHealth", + "method": "GET", + "path": "/health", + "group": "environment", + "slug": "health", + "spec": "envd" + }, + { + "operationId": "getEnvironmentMetrics", + "method": "GET", + "path": "/metrics", + "group": "environment", + "slug": "metrics", + "spec": "envd" + }, + { + "operationId": "getEnvironmentVariables", + "method": "GET", + "path": "/envs", + "group": "environment", + "slug": "variables", + "spec": "envd" + }, + { + "operationId": "composeFiles", + "method": "POST", + "path": "/files/compose", + "group": "files", + "slug": "compose", + "spec": "envd" + }, + { + "operationId": "downloadFile", + "method": "GET", + "path": "/files", + "group": "files", + "slug": "download", + "spec": "envd" + }, + { + "operationId": "uploadFile", + "method": "POST", + "path": "/files", + "group": "files", + "slug": "upload", + "spec": "envd" + } +] diff --git a/reference/sdk/cli/auth.md b/reference/sdk/cli/auth.md new file mode 100644 index 00000000..2adec06a --- /dev/null +++ b/reference/sdk/cli/auth.md @@ -0,0 +1,16 @@ +# Auth commands + +## agentbox configure + +store an AgentBox API key and optional project ID + +### Usage + +```bash +agentbox configure [options] [api-key] +``` + +### Options + +- `--project-id <project-id>`: default AgentBox project ID + diff --git a/reference/sdk/cli/sandbox.md b/reference/sdk/cli/sandbox.md new file mode 100644 index 00000000..dd034105 --- /dev/null +++ b/reference/sdk/cli/sandbox.md @@ -0,0 +1,214 @@ +# Sandbox commands + +## agentbox sandbox + +work with sandboxes + +### Usage + +```bash +agentbox sandbox [options] [command] +``` + +## agentbox sandbox connect + +connect terminal to already running sandbox + +### Usage + +```bash +agentbox sandbox connect [options] +``` + +### Options + +- `-u, --user <user>`: user to start the terminal session as +- `-c, --cwd <dir>`: working directory for the terminal session +- `-e, --env <KEY=VALUE>`: set environment variable for the terminal session (repeatable) Default: `[object Object]`. + +## agentbox sandbox create + +create sandbox and connect terminal to it + +### Usage + +```bash +agentbox sandbox create [options] [template] +``` + +### Options + +- `-d, --detach`: create sandbox without connecting terminal to it +- `--lifecycle.ontimeout <action>`: action when sandbox timeout is reached: pause or kill +- `--lifecycle.autoresume`: enable sandbox auto-resume, requires --lifecycle.ontimeout pause +- `--timeout <seconds>`: sandbox timeout in seconds +- `-u, --user <user>`: user to start the terminal session as +- `-c, --cwd <dir>`: working directory for the terminal session +- `-e, --env <KEY=VALUE>`: set environment variable for the terminal session (repeatable) Default: `[object Object]`. + +## agentbox sandbox exec + +execute a command in a running sandbox + +### Usage + +```bash +agentbox sandbox exec [options] +``` + +### Options + +- `-b, --background`: run in background and return immediately +- `-c, --cwd <dir>`: working directory +- `-u, --user <user>`: run as specified user +- `-e, --env <KEY=VALUE>`: set environment variable (repeatable) Default: `[object Object]`. + +## agentbox sandbox info + +show information for a sandbox + +### Usage + +```bash +agentbox sandbox info [options] +``` + +### Options + +- `-f, --format <format>`: output format, eg. json, pretty + +## agentbox sandbox kill + +kill sandbox + +### Usage + +```bash +agentbox sandbox kill [options] [sandboxIDs...] +``` + +### Options + +- `-a, --all`: kill all sandboxes +- `-s, --state <state>`: when used with -a/--all flag, filter by state, eg. running, paused. Defaults to running +- `-m, --metadata <metadata>`: when used with -a/--all flag, filter by metadata, eg. key1=value1 + +## agentbox sandbox list + +list all sandboxes, by default it list only running ones + +### Usage + +```bash +agentbox sandbox list [options] +``` + +### Options + +- `-s, --state <state>`: filter by state, eg. running, paused. Defaults to running +- `-m, --metadata <metadata>`: filter by metadata, eg. key1=value1 +- `-l, --limit <limit>`: limit the number of sandboxes returned (default: 1000, 0 for no limit) +- `-f, --format <format>`: output format, eg. json, pretty + +## agentbox sandbox logs + +show logs for sandbox + +### Usage + +```bash +agentbox sandbox logs [options] +``` + +### Options + +- `--level <level>`: filter logs by level (DEBUG, INFO, WARN, ERROR). The logs with the higher levels will be also shown. Default: `INFO`. +- `-f, --follow`: keep streaming logs until the sandbox is closed +- `--format <format>`: specify format for printing logs (json, pretty) Default: `pretty`. +- `--loggers [loggers]`: filter logs by loggers. Specify multiple loggers by separating them with a comma. + +## agentbox sandbox metrics + +show metrics for sandbox + +### Usage + +```bash +agentbox sandbox metrics [options] +``` + +### Options + +- `-f, --follow`: keep streaming metrics until the sandbox is closed +- `--format <format>`: specify format for printing metrics (json, pretty) Default: `pretty`. + +## agentbox sandbox pause + +pause sandbox + +### Usage + +```bash +agentbox sandbox pause [options] +``` + +## agentbox sandbox resume + +resume paused sandbox + +### Usage + +```bash +agentbox sandbox resume [options] +``` + +## agentbox sandbox snapshot + +work with sandbox snapshots + +### Usage + +```bash +agentbox sandbox snapshot [options] [command] +``` + +## agentbox sandbox snapshot create + +create a snapshot from a sandbox + +### Usage + +```bash +agentbox sandbox snapshot create [options] +``` + +### Options + +- `-n, --name <name>`: name for the snapshot template, reuses the existing template if it already exists + +## agentbox sandbox snapshot delete + +delete snapshots + +### Usage + +```bash +agentbox sandbox snapshot delete [options] +``` + +## agentbox sandbox snapshot list + +list snapshots + +### Usage + +```bash +agentbox sandbox snapshot list [options] [sandboxID] +``` + +### Options + +- `-n, --name <name>`: filter by snapshot name or ID, optionally tag-qualified, eg. my-snapshot:v1 +- `-l, --limit <limit>`: limit the number of snapshots returned (default: 1000, 0 for no limit) +- `-f, --format <format>`: output format, eg. json, pretty + diff --git a/reference/sdk/cli/template.md b/reference/sdk/cli/template.md new file mode 100644 index 00000000..c8333ad8 --- /dev/null +++ b/reference/sdk/cli/template.md @@ -0,0 +1,63 @@ +# Template commands + +## agentbox template + +manage sandbox templates + +### Usage + +```bash +agentbox template [options] [command] +``` + +## agentbox template create + +build Dockerfile as a Sandbox template. This command reads a Dockerfile and builds it directly. + +### Usage + +```bash +agentbox template create [options] +``` + +### Options + +- `-p, --path <path>`: change root directory where command is executed to <path> directory +- `-d, --dockerfile <file>`: specify path to Dockerfile. By default AgentBox tries to find agentbox.Dockerfile or Dockerfile in root directory. +- `-c, --cmd <start-command>`: specify command that will be executed when the sandbox is started. +- `--ready-cmd <ready-command>`: specify command that will need to exit 0 for the template to be ready. +- `--cpu-count <cpu-count>`: specify the number of CPUs that will be used to run the sandbox. The default value is 2. +- `--memory-mb <memory-mb>`: specify the amount of memory in megabytes that will be used to run the sandbox. Must be an even number. The default value is 1024. +- `--no-cache`: skip cache when building the template. + +## agentbox template delete + +delete sandbox template + +### Usage + +```bash +agentbox template delete [options] [template] +``` + +### Options + +- `-s, --select`: select sandbox template from interactive list +- `-t, --project <project-id>`: specify the project ID for the operation. See https://docs.agentbox.ru/en/cli/configuration/. +- `-y, --yes`: skip manual delete confirmation + +## agentbox template list + +list sandbox templates + +### Usage + +```bash +agentbox template list [options] +``` + +### Options + +- `-t, --project <project-id>`: specify the project ID for the operation. See https://docs.agentbox.ru/en/cli/configuration/. +- `-f, --format <format>`: output format, eg. json, pretty + diff --git a/reference/sdk/javascript/code-interpreter/README.md b/reference/sdk/javascript/code-interpreter/README.md new file mode 100644 index 00000000..b73448c6 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/README.md @@ -0,0 +1,7 @@ +# @abox-dev/code-interpreter + +## Modules + +- [charts](charts/README.md) +- [messaging](messaging/README.md) +- [sandbox](sandbox/README.md) diff --git a/reference/sdk/javascript/code-interpreter/charts/README.md b/reference/sdk/javascript/code-interpreter/charts/README.md new file mode 100644 index 00000000..c3115799 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/README.md @@ -0,0 +1,27 @@ +[@abox-dev/code-interpreter](../README.md) / charts + +# charts + +## Enumerations + +- [ChartType](enumerations/ChartType.md) +- [ScaleType](enumerations/ScaleType.md) + +## Type Aliases + +- [BarChart](type-aliases/BarChart.md) +- [BarData](type-aliases/BarData.md) +- [BoxAndWhiskerChart](type-aliases/BoxAndWhiskerChart.md) +- [BoxAndWhiskerData](type-aliases/BoxAndWhiskerData.md) +- [Chart](type-aliases/Chart.md) +- [ChartTypes](type-aliases/ChartTypes.md) +- [LineChart](type-aliases/LineChart.md) +- [PieChart](type-aliases/PieChart.md) +- [PieData](type-aliases/PieData.md) +- [PointData](type-aliases/PointData.md) +- [ScatterChart](type-aliases/ScatterChart.md) +- [SuperChart](type-aliases/SuperChart.md) + +## Functions + +- [deserializeChart](functions/deserializeChart.md) diff --git a/reference/sdk/javascript/code-interpreter/charts/enumerations/ChartType.md b/reference/sdk/javascript/code-interpreter/charts/enumerations/ChartType.md new file mode 100644 index 00000000..9c70c30e --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/enumerations/ChartType.md @@ -0,0 +1,47 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / ChartType + +# Enumeration: ChartType + +Chart types + +## Enumeration Members + +### BAR + +> **BAR**: `"bar"` + +*** + +### BOX\_AND\_WHISKER + +> **BOX\_AND\_WHISKER**: `"box_and_whisker"` + +*** + +### LINE + +> **LINE**: `"line"` + +*** + +### PIE + +> **PIE**: `"pie"` + +*** + +### SCATTER + +> **SCATTER**: `"scatter"` + +*** + +### SUPERCHART + +> **SUPERCHART**: `"superchart"` + +*** + +### UNKNOWN + +> **UNKNOWN**: `"unknown"` diff --git a/reference/sdk/javascript/code-interpreter/charts/enumerations/ScaleType.md b/reference/sdk/javascript/code-interpreter/charts/enumerations/ScaleType.md new file mode 100644 index 00000000..672fb68e --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/enumerations/ScaleType.md @@ -0,0 +1,59 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / ScaleType + +# Enumeration: ScaleType + +Ax scale types + +## Enumeration Members + +### ASINH + +> **ASINH**: `"asinh"` + +*** + +### CATEGORICAL + +> **CATEGORICAL**: `"categorical"` + +*** + +### DATETIME + +> **DATETIME**: `"datetime"` + +*** + +### FUNCTION + +> **FUNCTION**: `"function"` + +*** + +### FUNCTIONLOG + +> **FUNCTIONLOG**: `"functionlog"` + +*** + +### LINEAR + +> **LINEAR**: `"linear"` + +*** + +### LOG + +> **LOG**: `"log"` + +*** + +### LOGIT + +> **LOGIT**: `"logit"` + +*** + +### SYMLOG + +> **SYMLOG**: `"symlog"` diff --git a/reference/sdk/javascript/code-interpreter/charts/functions/deserializeChart.md b/reference/sdk/javascript/code-interpreter/charts/functions/deserializeChart.md new file mode 100644 index 00000000..13585dc5 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/functions/deserializeChart.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / deserializeChart + +# Function: deserializeChart() + +> **deserializeChart**(`data`): [`Chart`](../type-aliases/Chart.md) + +## Parameters + +### data + +`any` + +## Returns + +[`Chart`](../type-aliases/Chart.md) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarChart.md new file mode 100644 index 00000000..692430dd --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarChart.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / BarChart + +# Type Alias: BarChart + +> **BarChart** = `Chart2D` & `object` + +## Type Declaration + +### elements + +> **elements**: [`BarData`](BarData.md)[] + +### type + +> **type**: [`BAR`](../enumerations/ChartType.md#bar) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarData.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarData.md new file mode 100644 index 00000000..7ffecad2 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BarData.md @@ -0,0 +1,23 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / BarData + +# Type Alias: BarData + +> **BarData** = `object` + +## Properties + +### group + +> **group**: `string` + +*** + +### label + +> **label**: `string` + +*** + +### value + +> **value**: `string` diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerChart.md new file mode 100644 index 00000000..60802274 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerChart.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / BoxAndWhiskerChart + +# Type Alias: BoxAndWhiskerChart + +> **BoxAndWhiskerChart** = `Chart2D` & `object` + +## Type Declaration + +### elements + +> **elements**: [`BoxAndWhiskerData`](BoxAndWhiskerData.md)[] + +### type + +> **type**: [`BOX_AND_WHISKER`](../enumerations/ChartType.md#box_and_whisker) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerData.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerData.md new file mode 100644 index 00000000..f7ff16ce --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/BoxAndWhiskerData.md @@ -0,0 +1,47 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / BoxAndWhiskerData + +# Type Alias: BoxAndWhiskerData + +> **BoxAndWhiskerData** = `object` + +## Properties + +### first\_quartile + +> **first\_quartile**: `number` + +*** + +### label + +> **label**: `string` + +*** + +### max + +> **max**: `number` + +*** + +### median + +> **median**: `number` + +*** + +### min + +> **min**: `number` + +*** + +### outliers + +> **outliers**: `number`[] + +*** + +### third\_quartile + +> **third\_quartile**: `number` diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/Chart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/Chart.md new file mode 100644 index 00000000..327c753a --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/Chart.md @@ -0,0 +1,25 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / Chart + +# Type Alias: Chart + +> **Chart** = `object` + +Represents a chart. + +## Properties + +### elements + +> **elements**: `any`[] + +*** + +### title + +> **title**: `string` + +*** + +### type + +> **type**: [`ChartType`](../enumerations/ChartType.md) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/ChartTypes.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/ChartTypes.md new file mode 100644 index 00000000..f2f64c50 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/ChartTypes.md @@ -0,0 +1,5 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / ChartTypes + +# Type Alias: ChartTypes + +> **ChartTypes** = [`LineChart`](LineChart.md) \| [`ScatterChart`](ScatterChart.md) \| [`BarChart`](BarChart.md) \| [`PieChart`](PieChart.md) \| [`BoxAndWhiskerChart`](BoxAndWhiskerChart.md) \| [`SuperChart`](SuperChart.md) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/LineChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/LineChart.md new file mode 100644 index 00000000..8159af8f --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/LineChart.md @@ -0,0 +1,11 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / LineChart + +# Type Alias: LineChart + +> **LineChart** = `PointChart` & `object` + +## Type Declaration + +### type + +> **type**: [`LINE`](../enumerations/ChartType.md#line) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieChart.md new file mode 100644 index 00000000..09bfec4d --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieChart.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / PieChart + +# Type Alias: PieChart + +> **PieChart** = [`Chart`](Chart.md) & `object` + +## Type Declaration + +### elements + +> **elements**: [`PieData`](PieData.md)[] + +### type + +> **type**: [`PIE`](../enumerations/ChartType.md#pie) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieData.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieData.md new file mode 100644 index 00000000..aacbeced --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PieData.md @@ -0,0 +1,23 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / PieData + +# Type Alias: PieData + +> **PieData** = `object` + +## Properties + +### angle + +> **angle**: `number` + +*** + +### label + +> **label**: `string` + +*** + +### radius + +> **radius**: `number` diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/PointData.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PointData.md new file mode 100644 index 00000000..4f1f3024 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/PointData.md @@ -0,0 +1,17 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / PointData + +# Type Alias: PointData + +> **PointData** = `object` + +## Properties + +### label + +> **label**: `string` + +*** + +### points + +> **points**: \[`number` \| `string`, `number` \| `string`\][] diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/ScatterChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/ScatterChart.md new file mode 100644 index 00000000..94be2788 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/ScatterChart.md @@ -0,0 +1,11 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / ScatterChart + +# Type Alias: ScatterChart + +> **ScatterChart** = `PointChart` & `object` + +## Type Declaration + +### type + +> **type**: [`SCATTER`](../enumerations/ChartType.md#scatter) diff --git a/reference/sdk/javascript/code-interpreter/charts/type-aliases/SuperChart.md b/reference/sdk/javascript/code-interpreter/charts/type-aliases/SuperChart.md new file mode 100644 index 00000000..c7af7898 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/charts/type-aliases/SuperChart.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [charts](../README.md) / SuperChart + +# Type Alias: SuperChart + +> **SuperChart** = [`Chart`](Chart.md) & `object` + +## Type Declaration + +### elements + +> **elements**: [`Chart`](Chart.md)[] + +### type + +> **type**: [`SUPERCHART`](../enumerations/ChartType.md#superchart) diff --git a/reference/sdk/javascript/code-interpreter/messaging/README.md b/reference/sdk/javascript/code-interpreter/messaging/README.md new file mode 100644 index 00000000..ee14ffe6 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/README.md @@ -0,0 +1,21 @@ +[@abox-dev/code-interpreter](../README.md) / messaging + +# messaging + +## Classes + +- [Execution](classes/Execution.md) +- [ExecutionError](classes/ExecutionError.md) +- [OutputMessage](classes/OutputMessage.md) +- [Result](classes/Result.md) + +## Type Aliases + +- [Logs](type-aliases/Logs.md) +- [MIMEType](type-aliases/MIMEType.md) +- [RawData](type-aliases/RawData.md) + +## Functions + +- [extractError](functions/extractError.md) +- [parseOutput](functions/parseOutput.md) diff --git a/reference/sdk/javascript/code-interpreter/messaging/classes/Execution.md b/reference/sdk/javascript/code-interpreter/messaging/classes/Execution.md new file mode 100644 index 00000000..e848fdf2 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/classes/Execution.md @@ -0,0 +1,111 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / Execution + +# Class: Execution + +Represents the result of a cell execution. + +## Constructors + +### Constructor + +> **new Execution**(`results?`, `logs?`, `error?`, `executionCount?`): `Execution` + +#### Parameters + +##### results? + +[`Result`](Result.md)[] = `[]` + +List of result of the cell (interactively interpreted last line), display calls (e.g. matplotlib plots). + +##### logs? + +[`Logs`](../type-aliases/Logs.md) = `...` + +Logs printed to stdout and stderr during execution. + +##### error? + +[`ExecutionError`](ExecutionError.md) + +An Error object if an error occurred, null otherwise. + +##### executionCount? + +`number` + +Execution count of the cell. + +#### Returns + +`Execution` + +## Properties + +### error? + +> `optional` **error?**: [`ExecutionError`](ExecutionError.md) + +An Error object if an error occurred, null otherwise. + +*** + +### executionCount? + +> `optional` **executionCount?**: `number` + +Execution count of the cell. + +*** + +### logs + +> **logs**: [`Logs`](../type-aliases/Logs.md) + +Logs printed to stdout and stderr during execution. + +*** + +### results + +> **results**: [`Result`](Result.md)[] = `[]` + +List of result of the cell (interactively interpreted last line), display calls (e.g. matplotlib plots). + +## Accessors + +### text + +#### Get Signature + +> **get** **text**(): `string` \| `undefined` + +Returns the text representation of the main result of the cell. + +##### Returns + +`string` \| `undefined` + +## Methods + +### toJSON() + +> **toJSON**(): `object` + +Returns the serializable representation of the execution result. + +#### Returns + +`object` + +##### error + +> **error**: [`ExecutionError`](ExecutionError.md) \| `undefined` + +##### logs + +> **logs**: [`Logs`](../type-aliases/Logs.md) + +##### results + +> **results**: [`Result`](Result.md)[] diff --git a/reference/sdk/javascript/code-interpreter/messaging/classes/ExecutionError.md b/reference/sdk/javascript/code-interpreter/messaging/classes/ExecutionError.md new file mode 100644 index 00000000..2c194914 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/classes/ExecutionError.md @@ -0,0 +1,60 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / ExecutionError + +# Class: ExecutionError + +Represents an error that occurred during the execution of a cell. +The error contains the name of the error, the value of the error, and the traceback. + +## Constructors + +### Constructor + +> **new ExecutionError**(`name`, `value`, `traceback`): `ExecutionError` + +#### Parameters + +##### name + +`string` + +Name of the error. + +##### value + +`string` + +Value of the error. + +##### traceback + +`string` + +The raw traceback of the error. + +#### Returns + +`ExecutionError` + +## Properties + +### name + +> **name**: `string` + +Name of the error. + +*** + +### traceback + +> **traceback**: `string` + +The raw traceback of the error. + +*** + +### value + +> **value**: `string` + +Value of the error. diff --git a/reference/sdk/javascript/code-interpreter/messaging/classes/OutputMessage.md b/reference/sdk/javascript/code-interpreter/messaging/classes/OutputMessage.md new file mode 100644 index 00000000..ea48bf17 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/classes/OutputMessage.md @@ -0,0 +1,69 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / OutputMessage + +# Class: OutputMessage + +Represents an output message from the sandbox code execution. + +## Constructors + +### Constructor + +> **new OutputMessage**(`line`, `timestamp`, `error`): `OutputMessage` + +#### Parameters + +##### line + +`string` + +The output line. + +##### timestamp + +`number` + +Unix epoch in nanoseconds. + +##### error + +`boolean` + +Whether the output is an error. + +#### Returns + +`OutputMessage` + +## Properties + +### error + +> `readonly` **error**: `boolean` + +Whether the output is an error. + +*** + +### line + +> `readonly` **line**: `string` + +The output line. + +*** + +### timestamp + +> `readonly` **timestamp**: `number` + +Unix epoch in nanoseconds. + +## Methods + +### toString() + +> **toString**(): `string` + +#### Returns + +`string` diff --git a/reference/sdk/javascript/code-interpreter/messaging/classes/Result.md b/reference/sdk/javascript/code-interpreter/messaging/classes/Result.md new file mode 100644 index 00000000..b87d4840 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/classes/Result.md @@ -0,0 +1,216 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / Result + +# Class: Result + +Represents the data to be displayed as a result of executing a cell in a Jupyter notebook. +The result is similar to the structure returned by ipython kernel: https://ipython.readthedocs.io/en/stable/development/execution.html#execution-semantics + +The result can contain multiple types of data, such as text, images, plots, etc. Each type of data is represented +as a string, and the result can contain multiple types of data. The display calls don't have to have text representation, +for the actual result the representation is always present for the result, the other representations are always optional. + +## Constructors + +### Constructor + +> **new Result**(`rawData`, `isMainResult`): `Result` + +#### Parameters + +##### rawData + +[`RawData`](../type-aliases/RawData.md) + +##### isMainResult + +`boolean` + +#### Returns + +`Result` + +## Properties + +### chart? + +> `readonly` `optional` **chart?**: [`ChartTypes`](../../charts/type-aliases/ChartTypes.md) + +Contains the chart data. + +*** + +### data? + +> `readonly` `optional` **data?**: `Record`\<`string`, `unknown`\> + +Contains the data from DataFrame. + +*** + +### extra? + +> `readonly` `optional` **extra?**: `any` + +Extra data that can be included. Not part of the standard types. + +*** + +### html? + +> `readonly` `optional` **html?**: `string` + +HTML representation of the data. + +*** + +### isMainResult + +> `readonly` **isMainResult**: `boolean` + +*** + +### javascript? + +> `readonly` `optional` **javascript?**: `string` + +JavaScript representation of the data. + +*** + +### jpeg? + +> `readonly` `optional` **jpeg?**: `string` + +JPEG representation of the data. + +*** + +### json? + +> `readonly` `optional` **json?**: `string` + +JSON representation of the data. + +*** + +### latex? + +> `readonly` `optional` **latex?**: `string` + +LaTeX representation of the data. + +*** + +### markdown? + +> `readonly` `optional` **markdown?**: `string` + +Markdown representation of the data. + +*** + +### pdf? + +> `readonly` `optional` **pdf?**: `string` + +PDF representation of the data. + +*** + +### png? + +> `readonly` `optional` **png?**: `string` + +PNG representation of the data. + +*** + +### raw + +> `readonly` **raw**: [`RawData`](../type-aliases/RawData.md) + +*** + +### svg? + +> `readonly` `optional` **svg?**: `string` + +SVG representation of the data. + +*** + +### text? + +> `readonly` `optional` **text?**: `string` + +Text representation of the result. + +## Methods + +### formats() + +> **formats**(): `string`[] + +Returns all the formats available for the result. + +#### Returns + +`string`[] + +Array of strings representing the formats available for the result. + +*** + +### toJSON() + +> **toJSON**(): `object` + +Returns the serializable representation of the result. + +#### Returns + +`object` + +##### extra? + +> `optional` **extra?**: `any` + +##### html + +> **html**: `string` \| `undefined` + +##### javascript + +> **javascript**: `string` \| `undefined` + +##### jpeg + +> **jpeg**: `string` \| `undefined` + +##### json + +> **json**: `string` \| `undefined` + +##### latex + +> **latex**: `string` \| `undefined` + +##### markdown + +> **markdown**: `string` \| `undefined` + +##### pdf + +> **pdf**: `string` \| `undefined` + +##### png + +> **png**: `string` \| `undefined` + +##### svg + +> **svg**: `string` \| `undefined` + +##### text + +> **text**: `string` \| `undefined` diff --git a/reference/sdk/javascript/code-interpreter/messaging/functions/extractError.md b/reference/sdk/javascript/code-interpreter/messaging/functions/extractError.md new file mode 100644 index 00000000..554d6710 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/functions/extractError.md @@ -0,0 +1,15 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / extractError + +# Function: extractError() + +> **extractError**(`res`): `Promise`\<`SandboxError` \| `undefined`\> + +## Parameters + +### res + +`Response` + +## Returns + +`Promise`\<`SandboxError` \| `undefined`\> diff --git a/reference/sdk/javascript/code-interpreter/messaging/functions/parseOutput.md b/reference/sdk/javascript/code-interpreter/messaging/functions/parseOutput.md new file mode 100644 index 00000000..e86591d4 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/functions/parseOutput.md @@ -0,0 +1,35 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / parseOutput + +# Function: parseOutput() + +> **parseOutput**(`execution`, `line`, `onStdout?`, `onStderr?`, `onResult?`, `onError?`): `Promise`\<`void`\> + +## Parameters + +### execution + +[`Execution`](../classes/Execution.md) + +### line + +`string` + +### onStdout? + +(`output`) => `any` + +### onStderr? + +(`output`) => `any` + +### onResult? + +(`data`) => `any` + +### onError? + +(`error`) => `any` + +## Returns + +`Promise`\<`void`\> diff --git a/reference/sdk/javascript/code-interpreter/messaging/type-aliases/Logs.md b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/Logs.md new file mode 100644 index 00000000..5e8c6ffb --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/Logs.md @@ -0,0 +1,23 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / Logs + +# Type Alias: Logs + +> **Logs** = `object` + +Data printed to stdout and stderr during execution, usually by print statements, logs, warnings, subprocesses, etc. + +## Properties + +### stderr + +> **stderr**: `string`[] + +List of strings printed to stderr by prints, subprocesses, etc. + +*** + +### stdout + +> **stdout**: `string`[] + +List of strings printed to stdout by prints, subprocesses, etc. diff --git a/reference/sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md new file mode 100644 index 00000000..e6fac557 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md @@ -0,0 +1,7 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / MIMEType + +# Type Alias: MIMEType + +> **MIMEType** = `string` + +Represents a MIME type. diff --git a/reference/sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md new file mode 100644 index 00000000..1aa481c3 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md @@ -0,0 +1,7 @@ +[@abox-dev/code-interpreter](../../README.md) / [messaging](../README.md) / RawData + +# Type Alias: RawData + +> **RawData** = `object` & `AgentBoxData` + +Dictionary that maps MIME types to their corresponding representations of the data. diff --git a/reference/sdk/javascript/code-interpreter/sandbox/README.md b/reference/sdk/javascript/code-interpreter/sandbox/README.md new file mode 100644 index 00000000..56552aa9 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/README.md @@ -0,0 +1,17 @@ +[@abox-dev/code-interpreter](../README.md) / sandbox + +# sandbox + +## Classes + +- [Sandbox](classes/Sandbox.md) + +## Interfaces + +- [CreateCodeContextOpts](interfaces/CreateCodeContextOpts.md) +- [RunCodeOpts](interfaces/RunCodeOpts.md) + +## Type Aliases + +- [Context](type-aliases/Context.md) +- [RunCodeLanguage](type-aliases/RunCodeLanguage.md) diff --git a/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md b/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md new file mode 100644 index 00000000..f5b6e2ad --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md @@ -0,0 +1,1478 @@ +[@abox-dev/code-interpreter](../../README.md) / [sandbox](../README.md) / Sandbox + +# Class: Sandbox + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/). + +Use [Sandbox.create](#create) to create a new sandbox. + +## Example + +```ts +import { Sandbox } from '@abox-dev/code-interpreter' + +const sandbox = await Sandbox.create() +``` + +## Extends + +- `Sandbox` + +## Properties + +### commands + +> `readonly` **commands**: `Commands` + +Module for running commands in the sandbox + +#### Inherited from + +`BaseSandbox.commands` + +*** + +### 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` + +Module for interacting with the sandbox filesystem + +#### Inherited from + +`BaseSandbox.files` + +*** + +### mcpPort + +> `protected` `readonly` **mcpPort**: `50005` = `50005` + +#### Inherited from + +`BaseSandbox.mcpPort` + +*** + +### pty + +> `readonly` **pty**: `Pty` + +Module for interacting with the sandbox pseudo-terminals + +#### Inherited from + +`BaseSandbox.pty` + +*** + +### sandboxDomain + +> `readonly` **sandboxDomain**: `string` + +Domain where the sandbox is hosted. + +#### Inherited from + +`BaseSandbox.sandboxDomain` + +*** + +### sandboxId + +> `readonly` **sandboxId**: `string` + +Unique identifier of the sandbox. + +#### Inherited from + +`BaseSandbox.sandboxId` + +*** + +### trafficAccessToken? + +> `readonly` `optional` **trafficAccessToken?**: `string` + +Traffic access token for accessing sandbox services with restricted public traffic. + +#### Inherited from + +`BaseSandbox.trafficAccessToken` + +*** + +### defaultMcpTemplate + +> `protected` `readonly` `static` **defaultMcpTemplate**: `string` + +#### Inherited from + +`BaseSandbox.defaultMcpTemplate` + +*** + +### defaultSandboxTimeoutMs + +> `protected` `readonly` `static` **defaultSandboxTimeoutMs**: `300000` = `300000` + +#### 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() + +> **connect**(`opts?`): `Promise`\<`Sandbox`\> + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +#### Parameters + +##### opts? + +`SandboxConnectOpts` + +connection options. + +#### Returns + +`Promise`\<`Sandbox`\> + +A running sandbox instance + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.pause() + +// Connect to the same sandbox. +const sameSandbox = await sandbox.connect() +``` + +#### Inherited from + +`BaseSandbox.connect` + +*** + +### createCodeContext() + +> **createCodeContext**(`opts?`): `Promise`\<[`Context`](../type-aliases/Context.md)\> + +Creates a new context to run code in. + +#### Parameters + +##### opts? + +[`CreateCodeContextOpts`](../interfaces/CreateCodeContextOpts.md) + +options for creating the context. + +#### Returns + +`Promise`\<[`Context`](../type-aliases/Context.md)\> + +context object. + +*** + +### createSnapshot() + +> **createSnapshot**(`opts?`): `Promise`\<`SnapshotInfo`\> + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshotId` with `Sandbox.create(snapshotId)` to create a new sandbox from the snapshot. + +#### Parameters + +##### opts? + +`CreateSnapshotOpts` + +snapshot creation options including optional name and connection options. + +#### Returns + +`Promise`\<`SnapshotInfo`\> + +snapshot information including the snapshot ID. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.files.write('/app/state.json', '{"step": 1}') + +// Create a snapshot +const snapshot = await sandbox.createSnapshot({ name: 'my-snapshot' }) + +// Create a new sandbox from the snapshot +const newSandbox = await Sandbox.create(snapshot.snapshotId) +``` + +#### Inherited from + +`BaseSandbox.createSnapshot` + +*** + +### downloadUrl() + +> **downloadUrl**(`path`, `opts?`): `Promise`\<`string`\> + +Get the URL to download a file from the sandbox. + +#### Parameters + +##### path + +`string` + +path to the file in the sandbox. + +##### opts? + +`SandboxUrlOpts` + +download url options. + +#### Returns + +`Promise`\<`string`\> + +URL for downloading file. + +#### Inherited from + +`BaseSandbox.downloadUrl` + +*** + +### fork() + +> **fork**(`opts?`): `Promise`\<(`Error` \| `Sandbox`)[]\> + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with its +full memory state, and resumed — its ID and expiration stay untouched) and +`count` new sandboxes are created from that snapshot. All forks boot from +the same snapshot, so the snapshot is captured once regardless of count. + +Each fork succeeds or fails independently — the returned array contains +one entry per requested fork, either a running Sandbox instance or +an `Error` describing why that fork failed to start +(`Promise.allSettled`-style). Per-fork error codes map to the same error +classes as other API errors (e.g. 429 to `RateLimitError`). + +#### Parameters + +##### opts? + +`SandboxForkOpts` + +fork options — `count`, `timeoutMs` and connection options. + +#### Returns + +`Promise`\<(`Error` \| `Sandbox`)[]\> + +array with one entry per requested fork — a sandbox instance or an error. + +#### Example + +```ts +const sandbox = await Sandbox.create() + +const [fork1, fork2] = await sandbox.fork({ count: 2 }) +if (fork1 instanceof Sandbox) { + await fork1.commands.run('echo "hello from fork"') +} +``` + +#### Inherited from + +`BaseSandbox.fork` + +*** + +### getHost() + +> **getHost**(`port`): `string` + +Get the host address for the specified sandbox port. +You can then use this address to connect to the sandbox port from outside the sandbox via HTTP or WebSocket. + +#### Parameters + +##### port + +`number` + +number of the port in the sandbox. + +#### Returns + +`string` + +host address of the sandbox port. + +#### Example + +```ts +const sandbox = await Sandbox.create() +// Start an HTTP server +await sandbox.commands.run('python3 -m http.server 3000', { background: true }) +// Get the hostname of the HTTP server +const serverURL = sandbox.getHost(3000) +``` + +#### Inherited from + +`BaseSandbox.getHost` + +*** + +### getInfo() + +> **getInfo**(`opts?`): `Promise`\<`SandboxInfo`\> + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +#### Parameters + +##### opts? + +`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`SandboxInfo`\> + +information about the sandbox + +#### Inherited from + +`BaseSandbox.getInfo` + +*** + +### getMcpToken() + +> **getMcpToken**(): `Promise`\<`string` \| `undefined`\> + +Get the MCP token for the sandbox. + +#### Returns + +`Promise`\<`string` \| `undefined`\> + +MCP token for the sandbox, or undefined if MCP is not enabled. + +#### Inherited from + +`BaseSandbox.getMcpToken` + +*** + +### getMcpUrl() + +> **getMcpUrl**(): `string` + +Get the MCP URL for the sandbox. + +#### Returns + +`string` + +MCP URL for the sandbox. + +#### Inherited from + +`BaseSandbox.getMcpUrl` + +*** + +### getMetrics() + +> **getMetrics**(`opts?`): `Promise`\<`SandboxMetrics`[]\> + +Get the metrics of the sandbox. + +#### Parameters + +##### opts? + +`SandboxMetricsOpts` + +connection options. + +#### Returns + +`Promise`\<`SandboxMetrics`[]\> + +List of sandbox metrics containing CPU, memory and disk usage information. + +#### Inherited from + +`BaseSandbox.getMetrics` + +*** + +### isRunning() + +> **isRunning**(`opts?`): `Promise`\<`boolean`\> + +Check if the sandbox is running. + +#### Parameters + +##### opts? + +`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox is running, `false` otherwise. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.isRunning() // Returns true + +await sandbox.kill() +await sandbox.isRunning() // Returns false +``` + +#### Inherited from + +`BaseSandbox.isRunning` + +*** + +### kill() + +> **kill**(`opts?`): `Promise`\<`boolean`\> + +Kill the sandbox. + +#### Parameters + +##### opts? + +`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was killed, `false` if the sandbox was not found. + +#### Inherited from + +`BaseSandbox.kill` + +*** + +### listCodeContexts() + +> **listCodeContexts**(): `Promise`\<[`Context`](../type-aliases/Context.md)[]\> + +List all contexts. + +#### Returns + +`Promise`\<[`Context`](../type-aliases/Context.md)[]\> + +list of contexts. + +*** + +### listSnapshots() + +> **listSnapshots**(`opts?`): `SnapshotPaginator` + +List all snapshots created from this sandbox. + +#### Parameters + +##### opts? + +`Omit`\<`SnapshotListOpts`, `"sandboxId"`\> + +list options. + +#### Returns + +`SnapshotPaginator` + +paginator for listing snapshots from this sandbox. + +#### Inherited from + +`BaseSandbox.listSnapshots` + +*** + +### pause() + +> **pause**(`opts?`): `Promise`\<`boolean`\> + +Pause a sandbox by its ID. + +#### Parameters + +##### opts? + +`SandboxPauseOpts` + +connection options, plus `keepMemory` to control the snapshot +kind. When `opts.keepMemory` is `false`, the in-memory state is dropped and +only the filesystem is persisted (a filesystem-only snapshot); resuming such +a sandbox cold-boots (reboots) it from disk, losing running processes and +open connections. Defaults to `true` (full memory snapshot). + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox got paused, `false` if the sandbox was already paused. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.pause() + +// filesystem-only snapshot (resume reboots the sandbox) +await sandbox.pause({ keepMemory: false }) +``` + +#### Inherited from + +`BaseSandbox.pause` + +*** + +### removeCodeContext() + +> **removeCodeContext**(`context`): `Promise`\<`void`\> + +Removes a context. + +#### Parameters + +##### context + +`string` \| [`Context`](../type-aliases/Context.md) + +context to remove. + +#### Returns + +`Promise`\<`void`\> + +void. + +*** + +### restartCodeContext() + +> **restartCodeContext**(`context`): `Promise`\<`void`\> + +Restart a context. + +#### Parameters + +##### context + +`string` \| [`Context`](../type-aliases/Context.md) + +context to restart. + +#### Returns + +`Promise`\<`void`\> + +void. + +*** + +### runCode() + +#### Call Signature + +> **runCode**(`code`, `opts?`): `Promise`\<[`Execution`](../../messaging/classes/Execution.md)\> + +Run the code for the specified language. + +Specify the `language` or `context` option to run the code as a different language or in a different `Context`. +If no language is specified, Python is used. + +You can reference previously defined variables, imports, and functions in the code. + +##### Parameters + +###### code + +`string` + +code to execute. + +###### opts? + +[`RunCodeOpts`](../interfaces/RunCodeOpts.md) & `object` + +options for executing the code. + +##### Returns + +`Promise`\<[`Execution`](../../messaging/classes/Execution.md)\> + +`Execution` result object. + +#### Call Signature + +> **runCode**(`code`, `opts?`): `Promise`\<[`Execution`](../../messaging/classes/Execution.md)\> + +Runs the code in the specified context, if not specified, the default context is used. + +Specify the `language` or `context` option to run the code as a different language or in a different `Context`. + +You can reference previously defined variables, imports, and functions in the code. + +##### Parameters + +###### code + +`string` + +code to execute. + +###### opts? + +[`RunCodeOpts`](../interfaces/RunCodeOpts.md) & `object` + +options for executing the code + +##### Returns + +`Promise`\<[`Execution`](../../messaging/classes/Execution.md)\> + +`Execution` result object + +*** + +### setTimeout() + +> **setTimeout**(`timeoutMs`, `opts?`): `Promise`\<`void`\> + +Set the timeout of the sandbox. + +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.setTimeout`. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Parameters + +##### timeoutMs + +`number` + +timeout in **milliseconds**. + +##### opts? + +`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +`BaseSandbox.setTimeout` + +*** + +### updateNetwork() + +> **updateNetwork**(`network`, `opts?`): `Promise`\<`void`\> + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +#### Parameters + +##### network + +`SandboxNetworkUpdate` + +new network configuration. + +##### opts? + +`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +`BaseSandbox.updateNetwork` + +*** + +### uploadUrl() + +> **uploadUrl**(`path?`, `opts?`): `Promise`\<`string`\> + +Get the URL to upload a file to the sandbox. + +You have to send a POST request to this URL with the file as multipart/form-data. + +#### Parameters + +##### path? + +`string` + +path to the file in the sandbox. + +##### opts? + +`SandboxUrlOpts` + +download url options. + +#### Returns + +`Promise`\<`string`\> + +URL for uploading file. + +#### Inherited from + +`BaseSandbox.uploadUrl` + +*** + +### connect() + +> `static` **connect**\<`S`\>(`this`, `sandboxId`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +#### Type Parameters + +##### S + +`S` *extends* *typeof* `Sandbox` + +#### Parameters + +##### this + +`S` + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxConnectOpts` + +connection options. + +#### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +A running sandbox instance + +#### Example + +```ts +const sandbox = await Sandbox.create() +const sandboxId = sandbox.sandboxId + +// Connect to the same sandbox. +const sameSandbox = await Sandbox.connect(sandboxId) +``` + +#### Inherited from + +`BaseSandbox.connect` + +*** + +### 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 + +> `static` **create**\<`S`\>(`this`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the default `base` sandbox template. + +##### Type Parameters + +###### S + +`S` *extends* *typeof* `Sandbox` + +##### Parameters + +###### this + +`S` + +###### opts? + +`SandboxOpts` + +connection options. + +##### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +##### Example + +```ts +const sandbox = await Sandbox.create() +``` + +##### Constructs + +Sandbox + +##### Inherited from + +`BaseSandbox.create` + +#### Call Signature + +> `static` **create**\<`S`\>(`this`, `template`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the specified sandbox template. + +##### Type Parameters + +###### S + +`S` *extends* *typeof* `Sandbox` + +##### Parameters + +###### this + +`S` + +###### template + +`string` + +sandbox template name or ID. + +###### opts? + +`SandboxOpts` + +connection options. + +##### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +##### Example + +```ts +const sandbox = await Sandbox.create('') +``` + +##### Constructs + +Sandbox + +##### Inherited from + +`BaseSandbox.create` + +*** + +### 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`\> + +Create a snapshot from a sandbox. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same state. +The snapshot is a persistent image that survives sandbox deletion. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID to create snapshot from. + +##### opts? + +`CreateSnapshotOpts` + +snapshot creation options including optional name and connection options. + +#### Returns + +`Promise`\<`SnapshotInfo`\> + +snapshot information including the snapshot name that can be used with Sandbox.create(). + +#### Inherited from + +`BaseSandbox.createSnapshot` + +*** + +### deleteSnapshot() + +> `static` **deleteSnapshot**(`snapshotId`, `opts?`): `Promise`\<`boolean`\> + +Delete a snapshot. + +#### Parameters + +##### snapshotId + +`string` + +snapshot ID. + +##### opts? + +`SandboxApiOpts` + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the snapshot was deleted, `false` if it was not found. + +#### Inherited from + +`BaseSandbox.deleteSnapshot` + +*** + +### fork() + +> `static` **fork**\<`S`\>(`this`, `sandboxId`, `opts?`): `Promise`\<(`Error` \| `InstanceType`\<`S`\>)[]\> + +Fork a running sandbox specified by sandbox ID. + +The sandbox is checkpointed in place (briefly paused, snapshotted with its +full memory state, and resumed — its ID and expiration stay untouched) and +`count` new sandboxes are created from that snapshot. All forks boot from +the same snapshot, so the snapshot is captured once regardless of count. + +Each fork succeeds or fails independently — the returned array contains +one entry per requested fork, either a running Sandbox instance or +an `Error` describing why that fork failed to start +(`Promise.allSettled`-style). Per-fork error codes map to the same error +classes as other API errors (e.g. 429 to `RateLimitError`). + +#### Type Parameters + +##### S + +`S` *extends* *typeof* `Sandbox` + +#### Parameters + +##### this + +`S` + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxForkOpts` + +fork options — `count`, `timeoutMs` and connection options. + +#### Returns + +`Promise`\<(`Error` \| `InstanceType`\<`S`\>)[]\> + +array with one entry per requested fork — a sandbox instance or an error. + +#### Example + +```ts +const sandbox = await Sandbox.create() + +const [fork1, fork2] = await Sandbox.fork(sandbox.sandboxId, { count: 2 }) +if (fork1 instanceof Sandbox) { + await fork1.commands.run('echo "hello from fork"') +} +``` + +#### Inherited from + +`BaseSandbox.fork` + +*** + +### 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`\> + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxApiOpts` + +connection options. + +#### Returns + +`Promise`\<`SandboxInfo`\> + +sandbox information. + +#### Inherited from + +`BaseSandbox.getInfo` + +*** + +### getMetrics() + +> `static` **getMetrics**(`sandboxId`, `opts?`): `Promise`\<`SandboxMetrics`[]\> + +Get the metrics of the sandbox. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxMetricsOpts` + +sandbox metrics options. + +#### Returns + +`Promise`\<`SandboxMetrics`[]\> + +List of sandbox metrics containing CPU, memory and disk usage information. + +#### Inherited from + +`BaseSandbox.getMetrics` + +*** + +### kill() + +> `static` **kill**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Kill the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxApiOpts` + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was found and killed, `false` otherwise. + +#### Inherited from + +`BaseSandbox.kill` + +*** + +### list() + +> `static` **list**(`opts?`): `SandboxPaginator` + +List sandboxes. + +By default (no `query.state` set in `opts`), returns sandboxes in both +`running` and `paused` states. To filter by state, pass +`opts.query.state = [...]`. + +#### Parameters + +##### opts? + +`SandboxListOpts` + +connection options, plus optional `query` to filter by + metadata or state, and `limit` / `nextToken` for pagination. + +#### Returns + +`SandboxPaginator` + +a SandboxPaginator that yields pages of sandboxes + (running and paused by default). Iterate pages via + `await paginator.nextItems()` while `paginator.hasNext` is `true`. + +#### Inherited from + +`BaseSandbox.list` + +*** + +### listSnapshots() + +> `static` **listSnapshots**(`opts?`): `SnapshotPaginator` + +List all snapshots. + +#### Parameters + +##### opts? + +`SnapshotListOpts` + +list options including filters and pagination. + +#### Returns + +`SnapshotPaginator` + +paginator for listing snapshots. + +#### Inherited from + +`BaseSandbox.listSnapshots` + +*** + +### pause() + +> `static` **pause**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Pause the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +`SandboxPauseOpts` + +pause options, including `keepMemory` and connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox got paused, `false` if the sandbox was already paused. + +#### Inherited from + +`BaseSandbox.pause` + +*** + +### setTimeout() + +> `static` **setTimeout**(`sandboxId`, `timeoutMs`, `opts?`): `Promise`\<`void`\> + +Set the timeout of the specified sandbox. +After the timeout expires the sandbox will be automatically killed. + +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to [Sandbox.setTimeout](#settimeout-1). + +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### timeoutMs + +`number` + +timeout in **milliseconds**. + +##### opts? + +`SandboxApiOpts` + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +`BaseSandbox.setTimeout` + +*** + +### updateNetwork() + +> `static` **updateNetwork**(`sandboxId`, `network`, `opts?`): `Promise`\<`void`\> + +Update the network configuration of a running sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### network + +`SandboxNetworkUpdate` + +new network configuration. + +##### opts? + +`SandboxApiOpts` + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +`BaseSandbox.updateNetwork` diff --git a/reference/sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md b/reference/sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md new file mode 100644 index 00000000..06ead972 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md @@ -0,0 +1,47 @@ +[@abox-dev/code-interpreter](../../README.md) / [sandbox](../README.md) / CreateCodeContextOpts + +# Interface: CreateCodeContextOpts + +Options for creating a code context. + +## Properties + +### cwd? + +> `optional` **cwd?**: `string` + +Working directory for the context. + +#### Default + +```ts +/home/user +``` + +*** + +### language? + +> `optional` **language?**: [`RunCodeLanguage`](../type-aliases/RunCodeLanguage.md) + +Language for the context. + +#### Default + +```ts +python +``` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for the request in **milliseconds**. + +#### Default + +```ts +30_000 // 30 seconds +``` diff --git a/reference/sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md b/reference/sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md new file mode 100644 index 00000000..3e07bf15 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md @@ -0,0 +1,119 @@ +[@abox-dev/code-interpreter](../../README.md) / [sandbox](../README.md) / RunCodeOpts + +# Interface: RunCodeOpts + +Options for running code. + +## Properties + +### envs? + +> `optional` **envs?**: `Record`\<`string`, `string`\> + +Custom environment variables for code execution. + +#### Default + +```ts +{} +``` + +*** + +### onError? + +> `optional` **onError?**: (`error`) => `any` + +Callback for handling the `ExecutionError` object. + +#### Parameters + +##### error + +[`ExecutionError`](../../messaging/classes/ExecutionError.md) + +#### Returns + +`any` + +*** + +### onResult? + +> `optional` **onResult?**: (`data`) => `any` + +Callback for handling the final execution result. + +#### Parameters + +##### data + +[`Result`](../../messaging/classes/Result.md) + +#### Returns + +`any` + +*** + +### onStderr? + +> `optional` **onStderr?**: (`output`) => `any` + +Callback for handling stderr messages. + +#### Parameters + +##### output + +[`OutputMessage`](../../messaging/classes/OutputMessage.md) + +#### Returns + +`any` + +*** + +### onStdout? + +> `optional` **onStdout?**: (`output`) => `any` + +Callback for handling stdout messages. + +#### Parameters + +##### output + +[`OutputMessage`](../../messaging/classes/OutputMessage.md) + +#### Returns + +`any` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for the request in **milliseconds**. + +#### Default + +```ts +30_000 // 30 seconds +``` + +*** + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the code execution in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` diff --git a/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md b/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md new file mode 100644 index 00000000..92607ec6 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md @@ -0,0 +1,31 @@ +[@abox-dev/code-interpreter](../../README.md) / [sandbox](../README.md) / Context + +# Type Alias: Context + +> **Context** = `object` + +Represents a context for code execution. + +## Properties + +### cwd + +> **cwd**: `string` + +The working directory of the context. + +*** + +### id + +> **id**: `string` + +The ID of the context. + +*** + +### language + +> **language**: `string` + +The language of the context. diff --git a/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/RunCodeLanguage.md b/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/RunCodeLanguage.md new file mode 100644 index 00000000..c83b1c99 --- /dev/null +++ b/reference/sdk/javascript/code-interpreter/sandbox/type-aliases/RunCodeLanguage.md @@ -0,0 +1,7 @@ +[@abox-dev/code-interpreter](../../README.md) / [sandbox](../README.md) / RunCodeLanguage + +# Type Alias: RunCodeLanguage + +> **RunCodeLanguage** = `"python"` \| `"javascript"` \| `"typescript"` \| `"r"` \| `"java"` \| `"bash"` \| `string` & `object` + +Supported language for code execution. diff --git a/reference/sdk/javascript/commands/README.md b/reference/sdk/javascript/commands/README.md new file mode 100644 index 00000000..f0019d1d --- /dev/null +++ b/reference/sdk/javascript/commands/README.md @@ -0,0 +1,16 @@ +# @abox-dev/sdk + +## Classes + +- [Commands](classes/Commands.md) +- [Pty](classes/Pty.md) + +## Interfaces + +- [CommandRequestOpts](interfaces/CommandRequestOpts.md) +- [CommandStartOpts](interfaces/CommandStartOpts.md) +- [ProcessInfo](interfaces/ProcessInfo.md) + +## Type Aliases + +- [CommandConnectOpts](type-aliases/CommandConnectOpts.md) diff --git a/reference/sdk/javascript/commands/classes/Commands.md b/reference/sdk/javascript/commands/classes/Commands.md new file mode 100644 index 00000000..a0a7dfab --- /dev/null +++ b/reference/sdk/javascript/commands/classes/Commands.md @@ -0,0 +1,260 @@ +[@abox-dev/sdk](../README.md) / Commands + +# Class: Commands + +Module for starting and interacting with commands in the sandbox. + +## Constructors + +### Constructor + +> **new Commands**(`transport`, `envdApi`, `connectionConfig`): `Commands` + +#### Parameters + +##### transport + +`Transport` + +##### envdApi + +`EnvdApiClient` + +##### connectionConfig + +`ConnectionConfig` + +#### Returns + +`Commands` + +## Properties + +### rpc + +> `protected` `readonly` **rpc**: `Client`\<*typeof* `ProcessService`\> + +## Methods + +### closeStdin() + +> **closeStdin**(`pid`, `opts?`): `Promise`\<`void`\> + +Close command stdin. + +This signals EOF to the command. The command must have been started with `stdin: true`. + +#### Parameters + +##### pid + +`number` + +process ID of the command. You can get the list of running commands using [Commands.list](#list). + +##### opts? + +[`CommandRequestOpts`](../interfaces/CommandRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### connect() + +> **connect**(`pid`, `opts?`): `Promise`\<`CommandHandle`\> + +Connect to a running command. +You can use CommandHandle.wait to wait for the command to finish and get execution results. + +#### Parameters + +##### pid + +`number` + +process ID of the command to connect to. You can get the list of running commands using [Commands.list](#list). + +##### opts? + +[`CommandConnectOpts`](../type-aliases/CommandConnectOpts.md) + +connection options. + +#### Returns + +`Promise`\<`CommandHandle`\> + +`CommandHandle` handle to interact with the running command. + +*** + +### kill() + +> **kill**(`pid`, `opts?`): `Promise`\<`boolean`\> + +Kill a running command specified by its process ID. +It uses `SIGKILL` signal to kill the command. + +#### Parameters + +##### pid + +`number` + +process ID of the command. You can get the list of running commands using [Commands.list](#list). + +##### opts? + +[`CommandRequestOpts`](../interfaces/CommandRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the command was killed, `false` if the command was not found. + +*** + +### list() + +> **list**(`opts?`): `Promise`\<[`ProcessInfo`](../interfaces/ProcessInfo.md)[]\> + +List all running commands and PTY sessions. + +#### Parameters + +##### opts? + +[`CommandRequestOpts`](../interfaces/CommandRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`ProcessInfo`](../interfaces/ProcessInfo.md)[]\> + +list of running commands and PTY sessions. + +*** + +### run() + +#### Call Signature + +> **run**(`cmd`, `opts?`): `Promise`\<`CommandResult`\> + +Start a new command and wait until it finishes executing. + +##### Parameters + +###### cmd + +`string` + +command to execute. + +###### opts? + +[`CommandStartOpts`](../interfaces/CommandStartOpts.md) & `object` + +options for starting the command. + +##### Returns + +`Promise`\<`CommandResult`\> + +`CommandResult` result of the command execution. + +#### Call Signature + +> **run**(`cmd`, `opts`): `Promise`\<`CommandHandle`\> + +Start a new command in the background. +You can use CommandHandle.wait to wait for the command to finish and get its result. + +##### Parameters + +###### cmd + +`string` + +command to execute. + +###### opts + +[`CommandStartOpts`](../interfaces/CommandStartOpts.md) & `object` + +options for starting the command + +##### Returns + +`Promise`\<`CommandHandle`\> + +`CommandHandle` handle to interact with the running command. + +#### Call Signature + +> **run**(`cmd`, `opts?`): `Promise`\<`CommandResult` \| `CommandHandle`\> + +Start a new command. + +##### Parameters + +###### cmd + +`string` + +command to execute. + +###### opts? + +[`CommandStartOpts`](../interfaces/CommandStartOpts.md) & `object` + +options for starting the command. + - `opts.background: true` - runs in background, returns `CommandHandle` + - `opts.background: false | undefined` - waits for completion, returns `CommandResult` + +##### Returns + +`Promise`\<`CommandResult` \| `CommandHandle`\> + +Either a `CommandHandle` or a `CommandResult` (depending on `opts.background`). + +*** + +### sendStdin() + +> **sendStdin**(`pid`, `data`, `opts?`): `Promise`\<`void`\> + +Send data to command stdin. + +#### Parameters + +##### pid + +`number` + +process ID of the command. You can get the list of running commands using [Commands.list](#list). + +##### data + +`string` \| `Uint8Array`\<`ArrayBufferLike`\> + +data to send to the command. + +##### opts? + +[`CommandRequestOpts`](../interfaces/CommandRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> diff --git a/reference/sdk/javascript/commands/classes/Pty.md b/reference/sdk/javascript/commands/classes/Pty.md new file mode 100644 index 00000000..53ddf49d --- /dev/null +++ b/reference/sdk/javascript/commands/classes/Pty.md @@ -0,0 +1,179 @@ +[@abox-dev/sdk](../README.md) / Pty + +# Class: Pty + +Module for interacting with PTYs (pseudo-terminals) in the sandbox. + +## Constructors + +### Constructor + +> **new Pty**(`transport`, `envdApi`, `connectionConfig`): `Pty` + +#### Parameters + +##### transport + +`Transport` + +##### envdApi + +`EnvdApiClient` + +##### connectionConfig + +`ConnectionConfig` + +#### Returns + +`Pty` + +## Methods + +### connect() + +> **connect**(`pid`, `opts?`): `Promise`\<`CommandHandle`\> + +Connect to a running PTY. + +#### Parameters + +##### pid + +`number` + +process ID of the PTY to connect to. You can get the list of running PTYs using [Commands.list](Commands.md#list). + +##### opts? + +`PtyConnectOpts` + +connection options. + +#### Returns + +`Promise`\<`CommandHandle`\> + +handle to interact with the PTY. + +*** + +### create() + +> **create**(`opts`): `Promise`\<`CommandHandle`\> + +Create a new PTY (pseudo-terminal). + +#### Parameters + +##### opts + +`PtyCreateOpts` + +options for creating the PTY. + +#### Returns + +`Promise`\<`CommandHandle`\> + +handle to interact with the PTY. + +*** + +### kill() + +> **kill**(`pid`, `opts?`): `Promise`\<`boolean`\> + +Kill a running PTY specified by process ID. +It uses `SIGKILL` signal to kill the PTY. + +#### Parameters + +##### pid + +`number` + +process ID of the PTY. + +##### opts? + +`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the PTY was killed, `false` if the PTY was not found. + +*** + +### resize() + +> **resize**(`pid`, `size`, `opts?`): `Promise`\<`void`\> + +Resize PTY. +Call this when the terminal window is resized and the number of columns and rows has changed. + +#### Parameters + +##### pid + +`number` + +process ID of the PTY. + +##### size + +new size of the PTY. + +###### cols + +`number` + +###### rows + +`number` + +##### opts? + +`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### sendInput() + +> **sendInput**(`pid`, `data`, `opts?`): `Promise`\<`void`\> + +Send input to a PTY. + +#### Parameters + +##### pid + +`number` + +process ID of the PTY. + +##### data + +`Uint8Array` + +input data to send to the PTY. + +##### opts? + +`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> diff --git a/reference/sdk/javascript/commands/interfaces/CommandRequestOpts.md b/reference/sdk/javascript/commands/interfaces/CommandRequestOpts.md new file mode 100644 index 00000000..7b8d90cc --- /dev/null +++ b/reference/sdk/javascript/commands/interfaces/CommandRequestOpts.md @@ -0,0 +1,45 @@ +[@abox-dev/sdk](../README.md) / CommandRequestOpts + +# Interface: CommandRequestOpts + +Options for sending a command request. + +## Extends + +- `Partial`\<`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\>\> + +## Extended by + +- [`CommandStartOpts`](CommandStartOpts.md) + +## Properties + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +`Partial.requestTimeoutMs` + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +`Partial.signal` diff --git a/reference/sdk/javascript/commands/interfaces/CommandStartOpts.md b/reference/sdk/javascript/commands/interfaces/CommandStartOpts.md new file mode 100644 index 00000000..7be452da --- /dev/null +++ b/reference/sdk/javascript/commands/interfaces/CommandStartOpts.md @@ -0,0 +1,154 @@ +[@abox-dev/sdk](../README.md) / CommandStartOpts + +# Interface: CommandStartOpts + +Options for starting a new command. + +## Extends + +- [`CommandRequestOpts`](CommandRequestOpts.md) + +## Properties + +### background? + +> `optional` **background?**: `boolean` + +If true, starts command in the background and the method returns immediately. +You can use CommandHandle.wait to wait for the command to finish. + +*** + +### cwd? + +> `optional` **cwd?**: `string` + +Working directory for the command. + +#### Default + +```ts +// home directory of the user used to start the command +``` + +*** + +### envs? + +> `optional` **envs?**: `Record`\<`string`, `string`\> + +Environment variables used for the command. + +This overrides the default environment variables from `Sandbox` constructor. + +#### Default + +`{}` + +*** + +### onStderr? + +> `optional` **onStderr?**: (`data`) => `void` \| `Promise`\<`void`\> + +Callback for command stderr output. + +#### Parameters + +##### data + +`string` + +#### Returns + +`void` \| `Promise`\<`void`\> + +*** + +### onStdout? + +> `optional` **onStdout?**: (`data`) => `void` \| `Promise`\<`void`\> + +Callback for command stdout output. + +#### Parameters + +##### data + +`string` + +#### Returns + +`void` \| `Promise`\<`void`\> + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`CommandRequestOpts`](CommandRequestOpts.md).[`requestTimeoutMs`](CommandRequestOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`CommandRequestOpts`](CommandRequestOpts.md).[`signal`](CommandRequestOpts.md#signal) + +*** + +### stdin? + +> `optional` **stdin?**: `boolean` + +If true, command stdin is kept open and you can send data to it using [Commands.sendStdin](../classes/Commands.md#sendstdin) or CommandHandle.sendStdin. + +#### Default + +```ts +false +``` + +*** + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the command in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +*** + +### user? + +> `optional` **user?**: `string` + +User to run the command as. + +#### Default + +`default Sandbox user (as specified in the template)` diff --git a/reference/sdk/javascript/commands/interfaces/ProcessInfo.md b/reference/sdk/javascript/commands/interfaces/ProcessInfo.md new file mode 100644 index 00000000..17a2733d --- /dev/null +++ b/reference/sdk/javascript/commands/interfaces/ProcessInfo.md @@ -0,0 +1,53 @@ +[@abox-dev/sdk](../README.md) / ProcessInfo + +# Interface: ProcessInfo + +Information about a command, PTY session or start command running in the sandbox as process. + +## Properties + +### args + +> **args**: `string`[] + +Command arguments. + +*** + +### cmd + +> **cmd**: `string` + +Command that was executed. + +*** + +### cwd? + +> `optional` **cwd?**: `string` + +Executed command working directory. + +*** + +### envs + +> **envs**: `Record`\<`string`, `string`\> + +Environment variables used for the command. + +*** + +### pid + +> **pid**: `number` + +Process ID. + +*** + +### tag? + +> `optional` **tag?**: `string` + +Custom tag used for identifying special commands like start command in the custom template. diff --git a/reference/sdk/javascript/commands/type-aliases/CommandConnectOpts.md b/reference/sdk/javascript/commands/type-aliases/CommandConnectOpts.md new file mode 100644 index 00000000..fda3fff2 --- /dev/null +++ b/reference/sdk/javascript/commands/type-aliases/CommandConnectOpts.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / CommandConnectOpts + +# Type Alias: CommandConnectOpts + +> **CommandConnectOpts** = `Pick`\<[`CommandStartOpts`](../interfaces/CommandStartOpts.md), `"onStderr"` \| `"onStdout"` \| `"timeoutMs"`\> & [`CommandRequestOpts`](../interfaces/CommandRequestOpts.md) + +Options for connecting to a command. diff --git a/reference/sdk/javascript/errors/README.md b/reference/sdk/javascript/errors/README.md new file mode 100644 index 00000000..acfc5461 --- /dev/null +++ b/reference/sdk/javascript/errors/README.md @@ -0,0 +1,19 @@ +# @abox-dev/sdk + +## Classes + +- [AuthenticationError](classes/AuthenticationError.md) +- [BuildError](classes/BuildError.md) +- [FileNotFoundError](classes/FileNotFoundError.md) +- [FileUploadError](classes/FileUploadError.md) +- [InvalidArgumentError](classes/InvalidArgumentError.md) +- [NotEnoughSpaceError](classes/NotEnoughSpaceError.md) +- [RateLimitError](classes/RateLimitError.md) +- [SandboxError](classes/SandboxError.md) +- [SandboxNotFoundError](classes/SandboxNotFoundError.md) +- [TemplateError](classes/TemplateError.md) +- [TimeoutError](classes/TimeoutError.md) + +## Functions + +- [formatSandboxTimeoutError](functions/formatSandboxTimeoutError.md) diff --git a/reference/sdk/javascript/errors/classes/AuthenticationError.md b/reference/sdk/javascript/errors/classes/AuthenticationError.md new file mode 100644 index 00000000..445d4a0f --- /dev/null +++ b/reference/sdk/javascript/errors/classes/AuthenticationError.md @@ -0,0 +1,185 @@ +[@abox-dev/sdk](../README.md) / AuthenticationError + +# Class: AuthenticationError + +Thrown when authentication fails. + +## Extends + +- `Error` + +## Constructors + +### Constructor + +> **new AuthenticationError**(`message`): `AuthenticationError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`AuthenticationError` + +#### Overrides + +`Error.constructor` + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +`Error.cause` + +*** + +### message + +> **message**: `string` + +#### Inherited from + +`Error.message` + +*** + +### name + +> **name**: `string` + +#### Inherited from + +`Error.name` + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +`Error.stack` + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +`Error.stackTraceLimit` + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +`Error.captureStackTrace` + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +`Error.prepareStackTrace` diff --git a/reference/sdk/javascript/errors/classes/BuildError.md b/reference/sdk/javascript/errors/classes/BuildError.md new file mode 100644 index 00000000..bfadf4bf --- /dev/null +++ b/reference/sdk/javascript/errors/classes/BuildError.md @@ -0,0 +1,193 @@ +[@abox-dev/sdk](../README.md) / BuildError + +# Class: BuildError + +Thrown when the build fails. + +## Extends + +- `Error` + +## Extended by + +- [`FileUploadError`](FileUploadError.md) + +## Constructors + +### Constructor + +> **new BuildError**(`message`, `stackTrace?`): `BuildError` + +#### Parameters + +##### message + +`string` + +##### stackTrace? + +`string` + +#### Returns + +`BuildError` + +#### Overrides + +`Error.constructor` + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +`Error.cause` + +*** + +### message + +> **message**: `string` + +#### Inherited from + +`Error.message` + +*** + +### name + +> **name**: `string` + +#### Inherited from + +`Error.name` + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +`Error.stack` + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +`Error.stackTraceLimit` + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +`Error.captureStackTrace` + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +`Error.prepareStackTrace` diff --git a/reference/sdk/javascript/errors/classes/FileNotFoundError.md b/reference/sdk/javascript/errors/classes/FileNotFoundError.md new file mode 100644 index 00000000..50d4a2b8 --- /dev/null +++ b/reference/sdk/javascript/errors/classes/FileNotFoundError.md @@ -0,0 +1,185 @@ +[@abox-dev/sdk](../README.md) / FileNotFoundError + +# Class: FileNotFoundError + +Thrown when a file or directory is not found inside a sandbox. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new FileNotFoundError**(`message`): `FileNotFoundError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`FileNotFoundError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/FileUploadError.md b/reference/sdk/javascript/errors/classes/FileUploadError.md new file mode 100644 index 00000000..e633372e --- /dev/null +++ b/reference/sdk/javascript/errors/classes/FileUploadError.md @@ -0,0 +1,189 @@ +[@abox-dev/sdk](../README.md) / FileUploadError + +# Class: FileUploadError + +Thrown when the file upload fails. + +## Extends + +- [`BuildError`](BuildError.md) + +## Constructors + +### Constructor + +> **new FileUploadError**(`message`, `stackTrace?`): `FileUploadError` + +#### Parameters + +##### message + +`string` + +##### stackTrace? + +`string` + +#### Returns + +`FileUploadError` + +#### Overrides + +[`BuildError`](BuildError.md).[`constructor`](BuildError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`BuildError`](BuildError.md).[`cause`](BuildError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`BuildError`](BuildError.md).[`message`](BuildError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`BuildError`](BuildError.md).[`name`](BuildError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`BuildError`](BuildError.md).[`stack`](BuildError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`BuildError`](BuildError.md).[`stackTraceLimit`](BuildError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`BuildError`](BuildError.md).[`captureStackTrace`](BuildError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`BuildError`](BuildError.md).[`prepareStackTrace`](BuildError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/InvalidArgumentError.md b/reference/sdk/javascript/errors/classes/InvalidArgumentError.md new file mode 100644 index 00000000..8070cc99 --- /dev/null +++ b/reference/sdk/javascript/errors/classes/InvalidArgumentError.md @@ -0,0 +1,189 @@ +[@abox-dev/sdk](../README.md) / InvalidArgumentError + +# Class: InvalidArgumentError + +Thrown when an invalid argument is provided. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new InvalidArgumentError**(`message`, `stackTrace?`): `InvalidArgumentError` + +#### Parameters + +##### message + +`string` + +##### stackTrace? + +`string` + +#### Returns + +`InvalidArgumentError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/NotEnoughSpaceError.md b/reference/sdk/javascript/errors/classes/NotEnoughSpaceError.md new file mode 100644 index 00000000..d713ed81 --- /dev/null +++ b/reference/sdk/javascript/errors/classes/NotEnoughSpaceError.md @@ -0,0 +1,185 @@ +[@abox-dev/sdk](../README.md) / NotEnoughSpaceError + +# Class: NotEnoughSpaceError + +Thrown when there is not enough disk space. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new NotEnoughSpaceError**(`message`): `NotEnoughSpaceError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`NotEnoughSpaceError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/RateLimitError.md b/reference/sdk/javascript/errors/classes/RateLimitError.md new file mode 100644 index 00000000..6768cd55 --- /dev/null +++ b/reference/sdk/javascript/errors/classes/RateLimitError.md @@ -0,0 +1,185 @@ +[@abox-dev/sdk](../README.md) / RateLimitError + +# Class: RateLimitError + +Thrown when the API rate limit is exceeded. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new RateLimitError**(`message`): `RateLimitError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`RateLimitError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/SandboxError.md b/reference/sdk/javascript/errors/classes/SandboxError.md new file mode 100644 index 00000000..f7737c4c --- /dev/null +++ b/reference/sdk/javascript/errors/classes/SandboxError.md @@ -0,0 +1,197 @@ +[@abox-dev/sdk](../README.md) / SandboxError + +# Class: SandboxError + +Base class for all sandbox errors. + +Thrown when general sandbox errors occur. + +## Extends + +- `Error` + +## Extended by + +- [`TimeoutError`](TimeoutError.md) +- [`InvalidArgumentError`](InvalidArgumentError.md) +- [`NotEnoughSpaceError`](NotEnoughSpaceError.md) +- [`FileNotFoundError`](FileNotFoundError.md) +- [`SandboxNotFoundError`](SandboxNotFoundError.md) +- [`TemplateError`](TemplateError.md) +- [`RateLimitError`](RateLimitError.md) + +## Constructors + +### Constructor + +> **new SandboxError**(`message?`): `SandboxError` + +#### Parameters + +##### message? + +`string` + +#### Returns + +`SandboxError` + +#### Overrides + +`Error.constructor` + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +`Error.cause` + +*** + +### message + +> **message**: `string` + +#### Inherited from + +`Error.message` + +*** + +### name + +> **name**: `string` + +#### Inherited from + +`Error.name` + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +`Error.stack` + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +`Error.stackTraceLimit` + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +`Error.captureStackTrace` + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +`Error.prepareStackTrace` diff --git a/reference/sdk/javascript/errors/classes/SandboxNotFoundError.md b/reference/sdk/javascript/errors/classes/SandboxNotFoundError.md new file mode 100644 index 00000000..39c36a05 --- /dev/null +++ b/reference/sdk/javascript/errors/classes/SandboxNotFoundError.md @@ -0,0 +1,185 @@ +[@abox-dev/sdk](../README.md) / SandboxNotFoundError + +# Class: SandboxNotFoundError + +Thrown when a sandbox is not found (e.g. it doesn't exist or is no longer running). + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new SandboxNotFoundError**(`message`): `SandboxNotFoundError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`SandboxNotFoundError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/TemplateError.md b/reference/sdk/javascript/errors/classes/TemplateError.md new file mode 100644 index 00000000..99462d1c --- /dev/null +++ b/reference/sdk/javascript/errors/classes/TemplateError.md @@ -0,0 +1,189 @@ +[@abox-dev/sdk](../README.md) / TemplateError + +# Class: TemplateError + +Thrown when the template uses old envd version. It isn't compatible with the new SDK. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new TemplateError**(`message`, `stackTrace?`): `TemplateError` + +#### Parameters + +##### message + +`string` + +##### stackTrace? + +`string` + +#### Returns + +`TemplateError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/classes/TimeoutError.md b/reference/sdk/javascript/errors/classes/TimeoutError.md new file mode 100644 index 00000000..65a4926e --- /dev/null +++ b/reference/sdk/javascript/errors/classes/TimeoutError.md @@ -0,0 +1,193 @@ +[@abox-dev/sdk](../README.md) / TimeoutError + +# Class: TimeoutError + +Thrown when a timeout error occurs. + +The [unavailable] error type is caused by sandbox timeout. + +The [canceled] error type is caused by exceeding request timeout. + +The [deadline_exceeded] error type is caused by exceeding the timeout for command execution, watch, etc. + +The [unknown] error type is sometimes caused by the sandbox timeout when the request is not processed correctly. + +## Extends + +- [`SandboxError`](SandboxError.md) + +## Constructors + +### Constructor + +> **new TimeoutError**(`message`): `TimeoutError` + +#### Parameters + +##### message + +`string` + +#### Returns + +`TimeoutError` + +#### Overrides + +[`SandboxError`](SandboxError.md).[`constructor`](SandboxError.md#constructor) + +## Properties + +### cause? + +> `optional` **cause?**: `unknown` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`cause`](SandboxError.md#cause) + +*** + +### message + +> **message**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`message`](SandboxError.md#message) + +*** + +### name + +> **name**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`name`](SandboxError.md#name) + +*** + +### stack? + +> `optional` **stack?**: `string` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stack`](SandboxError.md#stack) + +*** + +### stackTraceLimit + +> `static` **stackTraceLimit**: `number` + +The `Error.stackTraceLimit` property specifies the number of stack frames +collected by a stack trace (whether generated by `new Error().stack` or +`Error.captureStackTrace(obj)`). + +The default value is `10` but may be set to any valid JavaScript number. Changes +will affect any stack trace captured _after_ the value has been changed. + +If set to a non-number value, or set to a negative number, stack traces will +not capture any frames. + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`stackTraceLimit`](SandboxError.md#stacktracelimit) + +## Methods + +### captureStackTrace() + +> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Creates a `.stack` property on `targetObject`, which when accessed returns +a string representing the location in the code at which +`Error.captureStackTrace()` was called. + +```js +const myObject = {}; +Error.captureStackTrace(myObject); +myObject.stack; // Similar to `new Error().stack` +``` + +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. + +The optional `constructorOpt` argument accepts a function. If given, all frames +above `constructorOpt`, including `constructorOpt`, will be omitted from the +generated stack trace. + +The `constructorOpt` argument is useful for hiding implementation +details of error generation from the user. For instance: + +```js +function a() { + b(); +} + +function b() { + c(); +} + +function c() { + // Create an error without stack trace to avoid calculating the stack trace twice. + const { stackTraceLimit } = Error; + Error.stackTraceLimit = 0; + const error = new Error(); + Error.stackTraceLimit = stackTraceLimit; + + // Capture the stack trace above function b + Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + throw error; +} + +a(); +``` + +#### Parameters + +##### targetObject + +`object` + +##### constructorOpt? + +`Function` + +#### Returns + +`void` + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`captureStackTrace`](SandboxError.md#capturestacktrace) + +*** + +### prepareStackTrace() + +> `static` **prepareStackTrace**(`err`, `stackTraces`): `any` + +#### Parameters + +##### err + +`Error` + +##### stackTraces + +`CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +[`SandboxError`](SandboxError.md).[`prepareStackTrace`](SandboxError.md#preparestacktrace) diff --git a/reference/sdk/javascript/errors/functions/formatSandboxTimeoutError.md b/reference/sdk/javascript/errors/functions/formatSandboxTimeoutError.md new file mode 100644 index 00000000..657891a6 --- /dev/null +++ b/reference/sdk/javascript/errors/functions/formatSandboxTimeoutError.md @@ -0,0 +1,15 @@ +[@abox-dev/sdk](../README.md) / formatSandboxTimeoutError + +# Function: formatSandboxTimeoutError() + +> **formatSandboxTimeoutError**(`message`): [`TimeoutError`](../classes/TimeoutError.md) + +## Parameters + +### message + +`string` + +## Returns + +[`TimeoutError`](../classes/TimeoutError.md) diff --git a/reference/sdk/javascript/filesystem/README.md b/reference/sdk/javascript/filesystem/README.md new file mode 100644 index 00000000..1ea0545b --- /dev/null +++ b/reference/sdk/javascript/filesystem/README.md @@ -0,0 +1,27 @@ +# @abox-dev/sdk + +## Enumerations + +- [FileType](enumerations/FileType.md) + +## Classes + +- [Filesystem](classes/Filesystem.md) + +## Interfaces + +- [EntryInfo](interfaces/EntryInfo.md) +- [FilesystemListOpts](interfaces/FilesystemListOpts.md) +- [FilesystemReadOpts](interfaces/FilesystemReadOpts.md) +- [FilesystemRequestOpts](interfaces/FilesystemRequestOpts.md) +- [FilesystemWriteOpts](interfaces/FilesystemWriteOpts.md) +- [WatchOpts](interfaces/WatchOpts.md) +- [WriteInfo](interfaces/WriteInfo.md) + +## Type Aliases + +- [WriteEntry](type-aliases/WriteEntry.md) + +## Functions + +- [mapEntryInfo](functions/mapEntryInfo.md) diff --git a/reference/sdk/javascript/filesystem/classes/Filesystem.md b/reference/sdk/javascript/filesystem/classes/Filesystem.md new file mode 100644 index 00000000..93a9db83 --- /dev/null +++ b/reference/sdk/javascript/filesystem/classes/Filesystem.md @@ -0,0 +1,462 @@ +[@abox-dev/sdk](../README.md) / Filesystem + +# Class: Filesystem + +Module for interacting with the sandbox filesystem. + +## Constructors + +### Constructor + +> **new Filesystem**(`transport`, `envdApi`, `connectionConfig`): `Filesystem` + +#### Parameters + +##### transport + +`Transport` + +##### envdApi + +`EnvdApiClient` + +##### connectionConfig + +`ConnectionConfig` + +#### Returns + +`Filesystem` + +## Methods + +### exists() + +> **exists**(`path`, `opts?`): `Promise`\<`boolean`\> + +Check if a file or a directory exists. + +#### Parameters + +##### path + +`string` + +path to a file or a directory + +##### opts? + +[`FilesystemRequestOpts`](../interfaces/FilesystemRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the file or directory exists, `false` otherwise + +*** + +### getInfo() + +> **getInfo**(`path`, `opts?`): `Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)\> + +Get information about a file or directory. + +#### Parameters + +##### path + +`string` + +path to a file or directory. + +##### opts? + +[`FilesystemRequestOpts`](../interfaces/FilesystemRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)\> + +information about the file or directory like name, type, and path. + +*** + +### list() + +> **list**(`path`, `opts?`): `Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)[]\> + +List entries in a directory. + +#### Parameters + +##### path + +`string` + +path to the directory. + +##### opts? + +[`FilesystemListOpts`](../interfaces/FilesystemListOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)[]\> + +list of entries in the sandbox filesystem directory. + +*** + +### makeDir() + +> **makeDir**(`path`, `opts?`): `Promise`\<`boolean`\> + +Create a new directory and all directories along the way if needed on the specified path. + +#### Parameters + +##### path + +`string` + +path to a new directory. For example '/dirA/dirB' when creating 'dirB'. + +##### opts? + +[`FilesystemRequestOpts`](../interfaces/FilesystemRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the directory was created, `false` if it already exists. + +*** + +### read() + +#### Call Signature + +> **read**(`path`, `opts?`): `Promise`\<`string`\> + +Read file content as a `string`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +##### Parameters + +###### path + +`string` + +path to the file. + +###### opts? + +[`FilesystemReadOpts`](../interfaces/FilesystemReadOpts.md) & `object` + +connection options. + +##### Returns + +`Promise`\<`string`\> + +file content as string + +#### Call Signature + +> **read**(`path`, `opts?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> + +Read file content as a `Uint8Array`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +##### Parameters + +###### path + +`string` + +path to the file. + +###### opts? + +[`FilesystemReadOpts`](../interfaces/FilesystemReadOpts.md) & `object` + +connection options. + +##### Returns + +`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> + +file content as `Uint8Array` + +#### Call Signature + +> **read**(`path`, `opts?`): `Promise`\<`Blob`\> + +Read file content as a `Blob`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +##### Parameters + +###### path + +`string` + +path to the file. + +###### opts? + +[`FilesystemReadOpts`](../interfaces/FilesystemReadOpts.md) & `object` + +connection options. + +##### Returns + +`Promise`\<`Blob`\> + +file content as `Blob` + +#### Call Signature + +> **read**(`path`, `opts?`): `Promise`\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\> + +Read file content as a `ReadableStream`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +The request timeout bounds only the initial handshake. The returned stream +holds a pooled connection until it is fully read, cancelled, errors, or the +idle timeout (`opts.streamIdleTimeoutMs`) fires—so consume it to the end or +cancel it (`opts.signal`). + +##### Parameters + +###### path + +`string` + +path to the file. + +###### opts? + +[`FilesystemReadOpts`](../interfaces/FilesystemReadOpts.md) & `object` + +connection options. + +##### Returns + +`Promise`\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\> + +file content as `ReadableStream` + +*** + +### remove() + +> **remove**(`path`, `opts?`): `Promise`\<`void`\> + +Remove a file or directory. + +#### Parameters + +##### path + +`string` + +path to a file or directory. + +##### opts? + +[`FilesystemRequestOpts`](../interfaces/FilesystemRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### rename() + +> **rename**(`oldPath`, `newPath`, `opts?`): `Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)\> + +Rename a file or directory. + +#### Parameters + +##### oldPath + +`string` + +path to the file or directory to rename. + +##### newPath + +`string` + +new path for the file or directory. + +##### opts? + +[`FilesystemRequestOpts`](../interfaces/FilesystemRequestOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`EntryInfo`](../interfaces/EntryInfo.md)\> + +information about renamed file or directory. + +*** + +### watchDir() + +> **watchDir**(`path`, `onEvent`, `opts?`): `Promise`\<`WatchHandle`\> + +Start watching a directory for filesystem events. + +#### Parameters + +##### path + +`string` + +path to directory to watch. + +##### onEvent + +(`event`) => `void` \| `Promise`\<`void`\> + +callback to call when an event in the directory occurs. + +##### opts? + +[`WatchOpts`](../interfaces/WatchOpts.md) & `object` + +connection options. + +#### Returns + +`Promise`\<`WatchHandle`\> + +`WatchHandle` object for stopping watching directory. + +*** + +### write() + +#### Call Signature + +> **write**(`path`, `data`, `opts?`): `Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)\> + +Write content to a file. + +Writing to a file that doesn't exist creates the file. + +Writing to a file that already exists overwrites the file. + +Writing to a file at path that doesn't exist creates the necessary directories. + +##### Parameters + +###### path + +`string` + +path to file. + +###### data + +`string` \| `Blob` \| `ReadableStream`\<`any`\> \| `ArrayBuffer` + +data to write to the file. Data can be a string, `ArrayBuffer`, `Blob`, or `ReadableStream`. + +###### opts? + +[`FilesystemWriteOpts`](../interfaces/FilesystemWriteOpts.md) + +connection options. + +##### Returns + +`Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)\> + +information about the written file + +#### Call Signature + +> **write**(`files`, `opts?`): `Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)[]\> + +Write content to a file. + +Writing to a file that doesn't exist creates the file. + +Writing to a file that already exists overwrites the file. + +Writing to a file at path that doesn't exist creates the necessary directories. + +##### Parameters + +###### files + +[`WriteEntry`](../type-aliases/WriteEntry.md)[] + +###### opts? + +[`FilesystemWriteOpts`](../interfaces/FilesystemWriteOpts.md) + +connection options. + +##### Returns + +`Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)[]\> + +information about the written file + +*** + +### writeFiles() + +> **writeFiles**(`files`, `opts?`): `Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)[]\> + +Write multiple files. + +Writing to a file that doesn't exist creates the file. + +Writing to a file that already exists overwrites the file. + +Writing to a file at path that doesn't exist creates the necessary directories. + +#### Parameters + +##### files + +[`WriteEntry`](../type-aliases/WriteEntry.md)[] + +list of files to write as `WriteEntry` objects, each containing `path` and `data`. + +##### opts? + +[`FilesystemWriteOpts`](../interfaces/FilesystemWriteOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`WriteInfo`](../interfaces/WriteInfo.md)[]\> + +information about the written files diff --git a/reference/sdk/javascript/filesystem/enumerations/FileType.md b/reference/sdk/javascript/filesystem/enumerations/FileType.md new file mode 100644 index 00000000..e89f48bb --- /dev/null +++ b/reference/sdk/javascript/filesystem/enumerations/FileType.md @@ -0,0 +1,29 @@ +[@abox-dev/sdk](../README.md) / FileType + +# Enumeration: FileType + +Sandbox filesystem object type. + +## Enumeration Members + +### DIR + +> **DIR**: `"dir"` + +Filesystem object is a directory. + +*** + +### FILE + +> **FILE**: `"file"` + +Filesystem object is a file. + +*** + +### SYMLINK + +> **SYMLINK**: `"symlink"` + +Filesystem object is a symlink. diff --git a/reference/sdk/javascript/filesystem/functions/mapEntryInfo.md b/reference/sdk/javascript/filesystem/functions/mapEntryInfo.md new file mode 100644 index 00000000..0c7c543b --- /dev/null +++ b/reference/sdk/javascript/filesystem/functions/mapEntryInfo.md @@ -0,0 +1,17 @@ +[@abox-dev/sdk](../README.md) / mapEntryInfo + +# Function: mapEntryInfo() + +> **mapEntryInfo**(`entry`): [`EntryInfo`](../interfaces/EntryInfo.md) + +Map a protobuf `EntryInfo` to the SDK `EntryInfo`. + +## Parameters + +### entry + +`EntryInfo` + +## Returns + +[`EntryInfo`](../interfaces/EntryInfo.md) diff --git a/reference/sdk/javascript/filesystem/interfaces/EntryInfo.md b/reference/sdk/javascript/filesystem/interfaces/EntryInfo.md new file mode 100644 index 00000000..c8c36420 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/EntryInfo.md @@ -0,0 +1,116 @@ +[@abox-dev/sdk](../README.md) / EntryInfo + +# Interface: EntryInfo + +Sandbox filesystem object information. + +## Extends + +- [`WriteInfo`](WriteInfo.md) + +## Properties + +### group + +> **group**: `string` + +Group owner of the filesystem object. + +*** + +### metadata? + +> `optional` **metadata?**: `Record`\<`string`, `string`\> + +User-defined metadata stored on the file as `user.agentbox.*` extended +attributes. On writes this reflects the metadata supplied on upload; on +reads (`getInfo`, `list`, `rename`) it reflects any `user.agentbox.*` xattr on +the file, including ones set out-of-band. `undefined` when none is set. + +#### Inherited from + +[`WriteInfo`](WriteInfo.md).[`metadata`](WriteInfo.md#metadata) + +*** + +### mode + +> **mode**: `number` + +File mode and permission bits. + +*** + +### modifiedTime? + +> `optional` **modifiedTime?**: `Date` + +Last modification time of the filesystem object. + +*** + +### name + +> **name**: `string` + +Name of the filesystem object. + +#### Inherited from + +[`WriteInfo`](WriteInfo.md).[`name`](WriteInfo.md#name) + +*** + +### owner + +> **owner**: `string` + +Owner of the filesystem object. + +*** + +### path + +> **path**: `string` + +Path to the filesystem object. + +#### Inherited from + +[`WriteInfo`](WriteInfo.md).[`path`](WriteInfo.md#path) + +*** + +### permissions + +> **permissions**: `string` + +String representation of file permissions (e.g. 'rwxr-xr-x'). + +*** + +### size + +> **size**: `number` + +Size of the filesystem object in bytes. + +*** + +### symlinkTarget? + +> `optional` **symlinkTarget?**: `string` + +If the filesystem object is a symlink, this is the target of the symlink. + +*** + +### type? + +> `optional` **type?**: [`FileType`](../enumerations/FileType.md) + +Type of the filesystem object. + +#### Inherited from + +[`WriteInfo`](WriteInfo.md).[`type`](WriteInfo.md#type) diff --git a/reference/sdk/javascript/filesystem/interfaces/FilesystemListOpts.md b/reference/sdk/javascript/filesystem/interfaces/FilesystemListOpts.md new file mode 100644 index 00000000..cfc75520 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/FilesystemListOpts.md @@ -0,0 +1,62 @@ +[@abox-dev/sdk](../README.md) / FilesystemListOpts + +# Interface: FilesystemListOpts + +Options for the sandbox filesystem operations. + +## Extends + +- [`FilesystemRequestOpts`](FilesystemRequestOpts.md) + +## Properties + +### depth? + +> `optional` **depth?**: `number` + +Depth of the directory to list. + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`requestTimeoutMs`](FilesystemRequestOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`signal`](FilesystemRequestOpts.md#signal) + +*** + +### user? + +> `optional` **user?**: `string` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`user`](FilesystemRequestOpts.md#user) diff --git a/reference/sdk/javascript/filesystem/interfaces/FilesystemReadOpts.md b/reference/sdk/javascript/filesystem/interfaces/FilesystemReadOpts.md new file mode 100644 index 00000000..b563ac42 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/FilesystemReadOpts.md @@ -0,0 +1,74 @@ +[@abox-dev/sdk](../README.md) / FilesystemReadOpts + +# Interface: FilesystemReadOpts + +Options for reading files from the sandbox filesystem. + +## Extends + +- [`FilesystemRequestOpts`](FilesystemRequestOpts.md) + +## Properties + +### gzip? + +> `optional` **gzip?**: `boolean` + +When true, the download will request gzip-encoded responses. + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`requestTimeoutMs`](FilesystemRequestOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`signal`](FilesystemRequestOpts.md#signal) + +*** + +### streamIdleTimeoutMs? + +> `optional` **streamIdleTimeoutMs?**: `number` + +Idle timeout for a streamed read (`format: 'stream'`) in **milliseconds**: +abort if no chunk arrives from the server within this window *while +reading*. It bounds only the wire — a slow or paused consumer never trips +it (a consumer that holds the stream but stops reading is reclaimed +server-side). Defaults to the request timeout (60s); pass `0` to disable. + +*** + +### user? + +> `optional` **user?**: `string` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`user`](FilesystemRequestOpts.md#user) diff --git a/reference/sdk/javascript/filesystem/interfaces/FilesystemRequestOpts.md b/reference/sdk/javascript/filesystem/interfaces/FilesystemRequestOpts.md new file mode 100644 index 00000000..03253035 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/FilesystemRequestOpts.md @@ -0,0 +1,57 @@ +[@abox-dev/sdk](../README.md) / FilesystemRequestOpts + +# Interface: FilesystemRequestOpts + +Options for the sandbox filesystem operations. + +## Extends + +- `Partial`\<`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\>\> + +## Extended by + +- [`FilesystemWriteOpts`](FilesystemWriteOpts.md) +- [`FilesystemReadOpts`](FilesystemReadOpts.md) +- [`FilesystemListOpts`](FilesystemListOpts.md) +- [`WatchOpts`](WatchOpts.md) + +## Properties + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +`Partial.requestTimeoutMs` + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +`Partial.signal` + +*** + +### user? + +> `optional` **user?**: `string` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. diff --git a/reference/sdk/javascript/filesystem/interfaces/FilesystemWriteOpts.md b/reference/sdk/javascript/filesystem/interfaces/FilesystemWriteOpts.md new file mode 100644 index 00000000..0233e466 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/FilesystemWriteOpts.md @@ -0,0 +1,95 @@ +[@abox-dev/sdk](../README.md) / FilesystemWriteOpts + +# Interface: FilesystemWriteOpts + +Options for writing files to the sandbox filesystem. + +## Extends + +- [`FilesystemRequestOpts`](FilesystemRequestOpts.md) + +## Properties + +### gzip? + +> `optional` **gzip?**: `boolean` + +When true, the upload will be gzip-compressed. Implies the +`application/octet-stream` upload. + +Requires envd 0.5.7 or later — when not supported by the sandbox's envd +version, the upload falls back to uncompressed `multipart/form-data`. + +*** + +### metadata? + +> `optional` **metadata?**: `Record`\<`string`, `string`\> + +User-defined metadata to persist on the uploaded file(s) as extended +attributes. Keys are lowercased by the sandbox, so they may differ in case +when read back. Invalid keys or values throw an `InvalidArgumentError`. +The same metadata is applied to every file in a multi-file upload. +Requires envd 0.6.2 or later. + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`requestTimeoutMs`](FilesystemRequestOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`signal`](FilesystemRequestOpts.md#signal) + +*** + +### useOctetStream? + +> `optional` **useOctetStream?**: `boolean` + +When true, the upload uses `application/octet-stream` instead of `multipart/form-data`. +Outside the browser, `ReadableStream` data is then streamed to the sandbox +instead of being buffered in memory. + +Defaults to `undefined`, which uses octet-stream when any entry is a +`ReadableStream` (so streamed uploads aren't buffered) and +`multipart/form-data` otherwise; browsers always use `multipart/form-data` +since they can't stream request bodies. Requires envd 0.5.7 or later — when +not supported by the sandbox's envd version, the upload falls back to +`multipart/form-data`. + +*** + +### user? + +> `optional` **user?**: `string` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`user`](FilesystemRequestOpts.md#user) diff --git a/reference/sdk/javascript/filesystem/interfaces/WatchOpts.md b/reference/sdk/javascript/filesystem/interfaces/WatchOpts.md new file mode 100644 index 00000000..ce8b552e --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/WatchOpts.md @@ -0,0 +1,122 @@ +[@abox-dev/sdk](../README.md) / WatchOpts + +# Interface: WatchOpts + +Options for watching a directory. + +## Extends + +- [`FilesystemRequestOpts`](FilesystemRequestOpts.md) + +## Properties + +### allowNetworkMounts? + +> `optional` **allowNetworkMounts?**: `boolean` + +Allow watching paths on network filesystem mounts (NFS, CIFS, SMB, FUSE), +which are rejected by default. Events on network mounts may be unreliable +or not delivered at all. + +Requires envd 0.6.4 or later. Watching with this option against an older sandbox +throws a `TemplateError`. + +*** + +### includeEntry? + +> `optional` **includeEntry?**: `boolean` + +Include the [EntryInfo](EntryInfo.md) of the affected entry in each FilesystemEvent. + +The entry is populated best-effort and may be `undefined` for events where the +entry no longer exists at the path (e.g. remove or rename-away events). + +Requires envd 0.6.3 or later. Watching with this option against an older sandbox +throws a `TemplateError`. + +*** + +### onExit? + +> `optional` **onExit?**: (`err?`) => `void` \| `Promise`\<`void`\> + +Callback to call when the watch operation stops. + +#### Parameters + +##### err? + +`Error` + +#### Returns + +`void` \| `Promise`\<`void`\> + +*** + +### recursive? + +> `optional` **recursive?**: `boolean` + +Watch the directory recursively + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`requestTimeoutMs`](FilesystemRequestOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`signal`](FilesystemRequestOpts.md#signal) + +*** + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the watch operation in **milliseconds**. +You can pass `0` to disable the timeout. + +#### Default + +```ts +60_000 // 60 seconds +``` + +*** + +### user? + +> `optional` **user?**: `string` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +#### Inherited from + +[`FilesystemRequestOpts`](FilesystemRequestOpts.md).[`user`](FilesystemRequestOpts.md#user) diff --git a/reference/sdk/javascript/filesystem/interfaces/WriteInfo.md b/reference/sdk/javascript/filesystem/interfaces/WriteInfo.md new file mode 100644 index 00000000..b41c6e18 --- /dev/null +++ b/reference/sdk/javascript/filesystem/interfaces/WriteInfo.md @@ -0,0 +1,44 @@ +[@abox-dev/sdk](../README.md) / WriteInfo + +# Interface: WriteInfo + +Sandbox filesystem object information. + +## Extended by + +- [`EntryInfo`](EntryInfo.md) + +## Properties + +### metadata? + +> `optional` **metadata?**: `Record`\<`string`, `string`\> + +User-defined metadata stored on the file as `user.agentbox.*` extended +attributes. On writes this reflects the metadata supplied on upload; on +reads (`getInfo`, `list`, `rename`) it reflects any `user.agentbox.*` xattr on +the file, including ones set out-of-band. `undefined` when none is set. + +*** + +### name + +> **name**: `string` + +Name of the filesystem object. + +*** + +### path + +> **path**: `string` + +Path to the filesystem object. + +*** + +### type? + +> `optional` **type?**: [`FileType`](../enumerations/FileType.md) + +Type of the filesystem object. diff --git a/reference/sdk/javascript/filesystem/type-aliases/WriteEntry.md b/reference/sdk/javascript/filesystem/type-aliases/WriteEntry.md new file mode 100644 index 00000000..77d55ded --- /dev/null +++ b/reference/sdk/javascript/filesystem/type-aliases/WriteEntry.md @@ -0,0 +1,17 @@ +[@abox-dev/sdk](../README.md) / WriteEntry + +# Type Alias: WriteEntry + +> **WriteEntry** = `object` + +## Properties + +### data + +> **data**: `string` \| `ArrayBuffer` \| `Blob` \| `ReadableStream` + +*** + +### path + +> **path**: `string` diff --git a/reference/sdk/javascript/logger/README.md b/reference/sdk/javascript/logger/README.md new file mode 100644 index 00000000..71c1dca7 --- /dev/null +++ b/reference/sdk/javascript/logger/README.md @@ -0,0 +1,15 @@ +# @abox-dev/sdk + +## Classes + +- [LogEntry](classes/LogEntry.md) +- [LogEntryEnd](classes/LogEntryEnd.md) +- [LogEntryStart](classes/LogEntryStart.md) + +## Type Aliases + +- [LogEntryLevel](type-aliases/LogEntryLevel.md) + +## Functions + +- [defaultBuildLogger](functions/defaultBuildLogger.md) diff --git a/reference/sdk/javascript/logger/classes/LogEntry.md b/reference/sdk/javascript/logger/classes/LogEntry.md new file mode 100644 index 00000000..172407e4 --- /dev/null +++ b/reference/sdk/javascript/logger/classes/LogEntry.md @@ -0,0 +1,62 @@ +[@abox-dev/sdk](../README.md) / LogEntry + +# Class: LogEntry + +Represents a single log entry from the template build process. + +## Extended by + +- [`LogEntryStart`](LogEntryStart.md) +- [`LogEntryEnd`](LogEntryEnd.md) + +## Constructors + +### Constructor + +> **new LogEntry**(`timestamp`, `level`, `message`): `LogEntry` + +#### Parameters + +##### timestamp + +`Date` + +##### level + +[`LogEntryLevel`](../type-aliases/LogEntryLevel.md) + +##### message + +`string` + +#### Returns + +`LogEntry` + +## Properties + +### level + +> `readonly` **level**: [`LogEntryLevel`](../type-aliases/LogEntryLevel.md) + +*** + +### message + +> `readonly` **message**: `string` + +*** + +### timestamp + +> `readonly` **timestamp**: `Date` + +## Methods + +### toString() + +> **toString**(): `string` + +#### Returns + +`string` diff --git a/reference/sdk/javascript/logger/classes/LogEntryEnd.md b/reference/sdk/javascript/logger/classes/LogEntryEnd.md new file mode 100644 index 00000000..f051cba7 --- /dev/null +++ b/reference/sdk/javascript/logger/classes/LogEntryEnd.md @@ -0,0 +1,77 @@ +[@abox-dev/sdk](../README.md) / LogEntryEnd + +# Class: LogEntryEnd + +Special log entry indicating the end of a build process. + +## Extends + +- [`LogEntry`](LogEntry.md) + +## Constructors + +### Constructor + +> **new LogEntryEnd**(`timestamp`, `message`): `LogEntryEnd` + +#### Parameters + +##### timestamp + +`Date` + +##### message + +`string` + +#### Returns + +`LogEntryEnd` + +#### Overrides + +[`LogEntry`](LogEntry.md).[`constructor`](LogEntry.md#constructor) + +## Properties + +### level + +> `readonly` **level**: [`LogEntryLevel`](../type-aliases/LogEntryLevel.md) + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`level`](LogEntry.md#level) + +*** + +### message + +> `readonly` **message**: `string` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`message`](LogEntry.md#message) + +*** + +### timestamp + +> `readonly` **timestamp**: `Date` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`timestamp`](LogEntry.md#timestamp) + +## Methods + +### toString() + +> **toString**(): `string` + +#### Returns + +`string` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`toString`](LogEntry.md#tostring) diff --git a/reference/sdk/javascript/logger/classes/LogEntryStart.md b/reference/sdk/javascript/logger/classes/LogEntryStart.md new file mode 100644 index 00000000..e636fbde --- /dev/null +++ b/reference/sdk/javascript/logger/classes/LogEntryStart.md @@ -0,0 +1,77 @@ +[@abox-dev/sdk](../README.md) / LogEntryStart + +# Class: LogEntryStart + +Special log entry indicating the start of a build process. + +## Extends + +- [`LogEntry`](LogEntry.md) + +## Constructors + +### Constructor + +> **new LogEntryStart**(`timestamp`, `message`): `LogEntryStart` + +#### Parameters + +##### timestamp + +`Date` + +##### message + +`string` + +#### Returns + +`LogEntryStart` + +#### Overrides + +[`LogEntry`](LogEntry.md).[`constructor`](LogEntry.md#constructor) + +## Properties + +### level + +> `readonly` **level**: [`LogEntryLevel`](../type-aliases/LogEntryLevel.md) + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`level`](LogEntry.md#level) + +*** + +### message + +> `readonly` **message**: `string` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`message`](LogEntry.md#message) + +*** + +### timestamp + +> `readonly` **timestamp**: `Date` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`timestamp`](LogEntry.md#timestamp) + +## Methods + +### toString() + +> **toString**(): `string` + +#### Returns + +`string` + +#### Inherited from + +[`LogEntry`](LogEntry.md).[`toString`](LogEntry.md#tostring) diff --git a/reference/sdk/javascript/logger/functions/defaultBuildLogger.md b/reference/sdk/javascript/logger/functions/defaultBuildLogger.md new file mode 100644 index 00000000..e1ffe00e --- /dev/null +++ b/reference/sdk/javascript/logger/functions/defaultBuildLogger.md @@ -0,0 +1,38 @@ +[@abox-dev/sdk](../README.md) / defaultBuildLogger + +# Function: defaultBuildLogger() + +> **defaultBuildLogger**(`options?`): (`logEntry`) => `void` + +Create a default build logger with animated timer display. + +## Parameters + +### options? + +Logger configuration options + +#### minLevel? + +[`LogEntryLevel`](../type-aliases/LogEntryLevel.md) + +Minimum log level to display (default: 'info') + +## Returns + +Logger function that accepts LogEntry instances + +(`logEntry`) => `void` + +## Example + +```ts +import { Template, defaultBuildLogger } from '@abox-dev/sdk' + +const template = Template().fromPythonImage() + +await Template.build(template, { + alias: 'my-template', + onBuildLogs: defaultBuildLogger({ minLevel: 'debug' }) +}) +``` diff --git a/reference/sdk/javascript/logger/type-aliases/LogEntryLevel.md b/reference/sdk/javascript/logger/type-aliases/LogEntryLevel.md new file mode 100644 index 00000000..d2848f6f --- /dev/null +++ b/reference/sdk/javascript/logger/type-aliases/LogEntryLevel.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / LogEntryLevel + +# Type Alias: LogEntryLevel + +> **LogEntryLevel** = `"debug"` \| `"info"` \| `"warn"` \| `"error"` + +Log entry severity levels. diff --git a/reference/sdk/javascript/ready-commands/README.md b/reference/sdk/javascript/ready-commands/README.md new file mode 100644 index 00000000..ffa78be2 --- /dev/null +++ b/reference/sdk/javascript/ready-commands/README.md @@ -0,0 +1,13 @@ +# @abox-dev/sdk + +## Classes + +- [ReadyCmd](classes/ReadyCmd.md) + +## Functions + +- [waitForFile](functions/waitForFile.md) +- [waitForPort](functions/waitForPort.md) +- [waitForProcess](functions/waitForProcess.md) +- [waitForTimeout](functions/waitForTimeout.md) +- [waitForURL](functions/waitForURL.md) diff --git a/reference/sdk/javascript/ready-commands/classes/ReadyCmd.md b/reference/sdk/javascript/ready-commands/classes/ReadyCmd.md new file mode 100644 index 00000000..1718566a --- /dev/null +++ b/reference/sdk/javascript/ready-commands/classes/ReadyCmd.md @@ -0,0 +1,31 @@ +[@abox-dev/sdk](../README.md) / ReadyCmd + +# Class: ReadyCmd + +Class for ready check commands. + +## Constructors + +### Constructor + +> **new ReadyCmd**(`cmd`): `ReadyCmd` + +#### Parameters + +##### cmd + +`string` + +#### Returns + +`ReadyCmd` + +## Methods + +### getCmd() + +> **getCmd**(): `string` + +#### Returns + +`string` diff --git a/reference/sdk/javascript/ready-commands/functions/waitForFile.md b/reference/sdk/javascript/ready-commands/functions/waitForFile.md new file mode 100644 index 00000000..36fc1fbf --- /dev/null +++ b/reference/sdk/javascript/ready-commands/functions/waitForFile.md @@ -0,0 +1,32 @@ +[@abox-dev/sdk](../README.md) / waitForFile + +# Function: waitForFile() + +> **waitForFile**(`filename`): [`ReadyCmd`](../classes/ReadyCmd.md) + +Wait for a file to exist. +Uses shell test command to check file existence. + +## Parameters + +### filename + +`string` + +Path to the file to wait for + +## Returns + +[`ReadyCmd`](../classes/ReadyCmd.md) + +ReadyCmd that checks for the file + +## Example + +```ts +import { Template, waitForFile } from '@abox-dev/sdk' + +const template = Template() + .fromBaseImage() + .setStartCmd('./init.sh', waitForFile('/tmp/ready')) +``` diff --git a/reference/sdk/javascript/ready-commands/functions/waitForPort.md b/reference/sdk/javascript/ready-commands/functions/waitForPort.md new file mode 100644 index 00000000..c0b9e504 --- /dev/null +++ b/reference/sdk/javascript/ready-commands/functions/waitForPort.md @@ -0,0 +1,32 @@ +[@abox-dev/sdk](../README.md) / waitForPort + +# Function: waitForPort() + +> **waitForPort**(`port`): [`ReadyCmd`](../classes/ReadyCmd.md) + +Wait for a port to be listening. +Uses `ss` command to check if a port is open and listening. + +## Parameters + +### port + +`number` + +Port number to wait for + +## Returns + +[`ReadyCmd`](../classes/ReadyCmd.md) + +ReadyCmd that checks for the port + +## Example + +```ts +import { Template, waitForPort } from '@abox-dev/sdk' + +const template = Template() + .fromPythonImage() + .setStartCmd('python -m http.server 8000', waitForPort(8000)) +``` diff --git a/reference/sdk/javascript/ready-commands/functions/waitForProcess.md b/reference/sdk/javascript/ready-commands/functions/waitForProcess.md new file mode 100644 index 00000000..f056ec5d --- /dev/null +++ b/reference/sdk/javascript/ready-commands/functions/waitForProcess.md @@ -0,0 +1,32 @@ +[@abox-dev/sdk](../README.md) / waitForProcess + +# Function: waitForProcess() + +> **waitForProcess**(`processName`): [`ReadyCmd`](../classes/ReadyCmd.md) + +Wait for a process with a specific name to be running. +Uses `pgrep` to check if a process exists. + +## Parameters + +### processName + +`string` + +Name of the process to wait for + +## Returns + +[`ReadyCmd`](../classes/ReadyCmd.md) + +ReadyCmd that checks for the process + +## Example + +```ts +import { Template, waitForProcess } from '@abox-dev/sdk' + +const template = Template() + .fromBaseImage() + .setStartCmd('./my-daemon', waitForProcess('my-daemon')) +``` diff --git a/reference/sdk/javascript/ready-commands/functions/waitForTimeout.md b/reference/sdk/javascript/ready-commands/functions/waitForTimeout.md new file mode 100644 index 00000000..09459886 --- /dev/null +++ b/reference/sdk/javascript/ready-commands/functions/waitForTimeout.md @@ -0,0 +1,32 @@ +[@abox-dev/sdk](../README.md) / waitForTimeout + +# Function: waitForTimeout() + +> **waitForTimeout**(`timeout`): [`ReadyCmd`](../classes/ReadyCmd.md) + +Wait for a specified timeout before considering the sandbox ready. +Uses `sleep` command to wait for a fixed duration. + +## Parameters + +### timeout + +`number` + +Time to wait in milliseconds (minimum: 1000ms / 1 second) + +## Returns + +[`ReadyCmd`](../classes/ReadyCmd.md) + +ReadyCmd that waits for the specified duration + +## Example + +```ts +import { Template, waitForTimeout } from '@abox-dev/sdk' + +const template = Template() + .fromNodeImage() + .setStartCmd('npm start', waitForTimeout(5000)) // Wait 5 seconds +``` diff --git a/reference/sdk/javascript/ready-commands/functions/waitForURL.md b/reference/sdk/javascript/ready-commands/functions/waitForURL.md new file mode 100644 index 00000000..467096a1 --- /dev/null +++ b/reference/sdk/javascript/ready-commands/functions/waitForURL.md @@ -0,0 +1,38 @@ +[@abox-dev/sdk](../README.md) / waitForURL + +# Function: waitForURL() + +> **waitForURL**(`url`, `statusCode?`): [`ReadyCmd`](../classes/ReadyCmd.md) + +Wait for a URL to return a specific HTTP status code. +Uses `curl` to make HTTP requests and check the response status. + +## Parameters + +### url + +`string` + +URL to check (e.g., 'http://localhost:3000/health') + +### statusCode? + +`number` = `200` + +Expected HTTP status code (default: 200) + +## Returns + +[`ReadyCmd`](../classes/ReadyCmd.md) + +ReadyCmd that checks the URL + +## Example + +```ts +import { Template, waitForURL } from '@abox-dev/sdk' + +const template = Template() + .fromNodeImage() + .setStartCmd('npm start', waitForURL('http://localhost:3000/health')) +``` diff --git a/reference/sdk/javascript/sandbox/README.md b/reference/sdk/javascript/sandbox/README.md new file mode 100644 index 00000000..59a95182 --- /dev/null +++ b/reference/sdk/javascript/sandbox/README.md @@ -0,0 +1,6 @@ +# @abox-dev/sdk + +## Modules + +- [index](index/README.md) +- [sandboxApi](sandboxApi/README.md) diff --git a/reference/sdk/javascript/sandbox/index/README.md b/reference/sdk/javascript/sandbox/index/README.md new file mode 100644 index 00000000..8c8662a8 --- /dev/null +++ b/reference/sdk/javascript/sandbox/index/README.md @@ -0,0 +1,11 @@ +[@abox-dev/sdk](../README.md) / index + +# index + +## Classes + +- [Sandbox](classes/Sandbox.md) + +## Interfaces + +- [SandboxUrlOpts](interfaces/SandboxUrlOpts.md) diff --git a/reference/sdk/javascript/sandbox/index/classes/Sandbox.md b/reference/sdk/javascript/sandbox/index/classes/Sandbox.md new file mode 100644 index 00000000..d98d7552 --- /dev/null +++ b/reference/sdk/javascript/sandbox/index/classes/Sandbox.md @@ -0,0 +1,1185 @@ +[@abox-dev/sdk](../../README.md) / [index](../README.md) / Sandbox + +# Class: Sandbox + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +Check the [sandbox documentation](https://docs.agentbox.ru/en/sdk/sandboxes/). + +Use [Sandbox.create](#create) to create a new sandbox. + +## Example + +```ts +import { Sandbox } from '@abox-dev/sdk' + +const sandbox = await Sandbox.create() +``` + +## Extends + +- [`SandboxApi`](../../sandboxApi/classes/SandboxApi.md) + +## Properties + +### commands + +> `readonly` **commands**: `Commands` + +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` + +Module for interacting with the sandbox filesystem + +*** + +### mcpPort + +> `protected` `readonly` **mcpPort**: `50005` = `50005` + +*** + +### pty + +> `readonly` **pty**: `Pty` + +Module for interacting with the sandbox pseudo-terminals + +*** + +### sandboxDomain + +> `readonly` **sandboxDomain**: `string` + +Domain where the sandbox is hosted. + +*** + +### sandboxId + +> `readonly` **sandboxId**: `string` + +Unique identifier of the sandbox. + +*** + +### trafficAccessToken? + +> `readonly` `optional` **trafficAccessToken?**: `string` + +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() + +> **connect**(`opts?`): `Promise`\<`Sandbox`\> + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +#### Parameters + +##### opts? + +[`SandboxConnectOpts`](../../sandboxApi/type-aliases/SandboxConnectOpts.md) + +connection options. + +#### Returns + +`Promise`\<`Sandbox`\> + +A running sandbox instance + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.pause() + +// Connect to the same sandbox. +const sameSandbox = await sandbox.connect() +``` + +*** + +### createSnapshot() + +> **createSnapshot**(`opts?`): `Promise`\<[`SnapshotInfo`](../../sandboxApi/interfaces/SnapshotInfo.md)\> + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshotId` with `Sandbox.create(snapshotId)` to create a new sandbox from the snapshot. + +#### Parameters + +##### opts? + +[`CreateSnapshotOpts`](../../sandboxApi/interfaces/CreateSnapshotOpts.md) + +snapshot creation options including optional name and connection options. + +#### Returns + +`Promise`\<[`SnapshotInfo`](../../sandboxApi/interfaces/SnapshotInfo.md)\> + +snapshot information including the snapshot ID. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.files.write('/app/state.json', '{"step": 1}') + +// Create a snapshot +const snapshot = await sandbox.createSnapshot({ name: 'my-snapshot' }) + +// Create a new sandbox from the snapshot +const newSandbox = await Sandbox.create(snapshot.snapshotId) +``` + +*** + +### downloadUrl() + +> **downloadUrl**(`path`, `opts?`): `Promise`\<`string`\> + +Get the URL to download a file from the sandbox. + +#### Parameters + +##### path + +`string` + +path to the file in the sandbox. + +##### opts? + +[`SandboxUrlOpts`](../interfaces/SandboxUrlOpts.md) + +download url options. + +#### Returns + +`Promise`\<`string`\> + +URL for downloading file. + +*** + +### fork() + +> **fork**(`opts?`): `Promise`\<(`Error` \| `Sandbox`)[]\> + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with its +full memory state, and resumed — its ID and expiration stay untouched) and +`count` new sandboxes are created from that snapshot. All forks boot from +the same snapshot, so the snapshot is captured once regardless of count. + +Each fork succeeds or fails independently — the returned array contains +one entry per requested fork, either a running Sandbox instance or +an `Error` describing why that fork failed to start +(`Promise.allSettled`-style). Per-fork error codes map to the same error +classes as other API errors (e.g. 429 to `RateLimitError`). + +#### Parameters + +##### opts? + +[`SandboxForkOpts`](../../sandboxApi/interfaces/SandboxForkOpts.md) + +fork options — `count`, `timeoutMs` and connection options. + +#### Returns + +`Promise`\<(`Error` \| `Sandbox`)[]\> + +array with one entry per requested fork — a sandbox instance or an error. + +#### Example + +```ts +const sandbox = await Sandbox.create() + +const [fork1, fork2] = await sandbox.fork({ count: 2 }) +if (fork1 instanceof Sandbox) { + await fork1.commands.run('echo "hello from fork"') +} +``` + +*** + +### getHost() + +> **getHost**(`port`): `string` + +Get the host address for the specified sandbox port. +You can then use this address to connect to the sandbox port from outside the sandbox via HTTP or WebSocket. + +#### Parameters + +##### port + +`number` + +number of the port in the sandbox. + +#### Returns + +`string` + +host address of the sandbox port. + +#### Example + +```ts +const sandbox = await Sandbox.create() +// Start an HTTP server +await sandbox.commands.run('python3 -m http.server 3000', { background: true }) +// Get the hostname of the HTTP server +const serverURL = sandbox.getHost(3000) +``` + +*** + +### getInfo() + +> **getInfo**(`opts?`): `Promise`\<[`SandboxInfo`](../../sandboxApi/interfaces/SandboxInfo.md)\> + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +#### Parameters + +##### opts? + +`Pick`\<[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md), `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<[`SandboxInfo`](../../sandboxApi/interfaces/SandboxInfo.md)\> + +information about the sandbox + +*** + +### getMcpToken() + +> **getMcpToken**(): `Promise`\<`string` \| `undefined`\> + +Get the MCP token for the sandbox. + +#### Returns + +`Promise`\<`string` \| `undefined`\> + +MCP token for the sandbox, or undefined if MCP is not enabled. + +*** + +### getMcpUrl() + +> **getMcpUrl**(): `string` + +Get the MCP URL for the sandbox. + +#### Returns + +`string` + +MCP URL for the sandbox. + +*** + +### getMetrics() + +> **getMetrics**(`opts?`): `Promise`\<[`SandboxMetrics`](../../sandboxApi/interfaces/SandboxMetrics.md)[]\> + +Get the metrics of the sandbox. + +#### Parameters + +##### opts? + +[`SandboxMetricsOpts`](../../sandboxApi/interfaces/SandboxMetricsOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`SandboxMetrics`](../../sandboxApi/interfaces/SandboxMetrics.md)[]\> + +List of sandbox metrics containing CPU, memory and disk usage information. + +*** + +### isRunning() + +> **isRunning**(`opts?`): `Promise`\<`boolean`\> + +Check if the sandbox is running. + +#### Parameters + +##### opts? + +`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox is running, `false` otherwise. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.isRunning() // Returns true + +await sandbox.kill() +await sandbox.isRunning() // Returns false +``` + +*** + +### kill() + +> **kill**(`opts?`): `Promise`\<`boolean`\> + +Kill the sandbox. + +#### Parameters + +##### opts? + +`Pick`\<[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md), `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was killed, `false` if the sandbox was not found. + +*** + +### listSnapshots() + +> **listSnapshots**(`opts?`): [`SnapshotPaginator`](../../sandboxApi/classes/SnapshotPaginator.md) + +List all snapshots created from this sandbox. + +#### Parameters + +##### opts? + +`Omit`\<[`SnapshotListOpts`](../../sandboxApi/interfaces/SnapshotListOpts.md), `"sandboxId"`\> + +list options. + +#### Returns + +[`SnapshotPaginator`](../../sandboxApi/classes/SnapshotPaginator.md) + +paginator for listing snapshots from this sandbox. + +*** + +### pause() + +> **pause**(`opts?`): `Promise`\<`boolean`\> + +Pause a sandbox by its ID. + +#### Parameters + +##### opts? + +[`SandboxPauseOpts`](../../sandboxApi/interfaces/SandboxPauseOpts.md) + +connection options, plus `keepMemory` to control the snapshot +kind. When `opts.keepMemory` is `false`, the in-memory state is dropped and +only the filesystem is persisted (a filesystem-only snapshot); resuming such +a sandbox cold-boots (reboots) it from disk, losing running processes and +open connections. Defaults to `true` (full memory snapshot). + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox got paused, `false` if the sandbox was already paused. + +#### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.pause() + +// filesystem-only snapshot (resume reboots the sandbox) +await sandbox.pause({ keepMemory: false }) +``` + +*** + +### setTimeout() + +> **setTimeout**(`timeoutMs`, `opts?`): `Promise`\<`void`\> + +Set the timeout of the sandbox. + +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.setTimeout`. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Parameters + +##### timeoutMs + +`number` + +timeout in **milliseconds**. + +##### opts? + +`Pick`\<[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md), `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### updateNetwork() + +> **updateNetwork**(`network`, `opts?`): `Promise`\<`void`\> + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +#### Parameters + +##### network + +[`SandboxNetworkUpdate`](../../sandboxApi/type-aliases/SandboxNetworkUpdate.md) + +new network configuration. + +##### opts? + +`Pick`\<[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md), `"requestTimeoutMs"` \| `"signal"`\> + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### uploadUrl() + +> **uploadUrl**(`path?`, `opts?`): `Promise`\<`string`\> + +Get the URL to upload a file to the sandbox. + +You have to send a POST request to this URL with the file as multipart/form-data. + +#### Parameters + +##### path? + +`string` + +path to the file in the sandbox. + +##### opts? + +[`SandboxUrlOpts`](../interfaces/SandboxUrlOpts.md) + +download url options. + +#### Returns + +`Promise`\<`string`\> + +URL for uploading file. + +*** + +### connect() + +> `static` **connect**\<`S`\>(`this`, `sandboxId`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +#### Type Parameters + +##### S + +`S` *extends* *typeof* `Sandbox` + +#### Parameters + +##### this + +`S` + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxConnectOpts`](../../sandboxApi/type-aliases/SandboxConnectOpts.md) + +connection options. + +#### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +A running sandbox instance + +#### Example + +```ts +const sandbox = await Sandbox.create() +const sandboxId = sandbox.sandboxId + +// Connect to the same sandbox. +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`](../../sandboxApi/type-aliases/SandboxConnectOpts.md) + +#### Returns + +`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`connectSandbox`](../../sandboxApi/classes/SandboxApi.md#connectsandbox) + +*** + +### create() + +#### Call Signature + +> `static` **create**\<`S`\>(`this`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the default `base` sandbox template. + +##### Type Parameters + +###### S + +`S` *extends* *typeof* `Sandbox` + +##### Parameters + +###### this + +`S` + +###### opts? + +[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md) + +connection options. + +##### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +##### Example + +```ts +const sandbox = await Sandbox.create() +``` + +##### Constructs + +Sandbox + +#### Call Signature + +> `static` **create**\<`S`\>(`this`, `template`, `opts?`): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the specified sandbox template. + +##### Type Parameters + +###### S + +`S` *extends* *typeof* `Sandbox` + +##### Parameters + +###### this + +`S` + +###### template + +`string` + +sandbox template name or ID. + +###### opts? + +[`SandboxOpts`](../../sandboxApi/interfaces/SandboxOpts.md) + +connection options. + +##### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +##### Example + +```ts +const sandbox = await Sandbox.create('') +``` + +##### Constructs + +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`](../../sandboxApi/interfaces/SandboxOpts.md) + +#### Returns + +`Promise`\<\{ `envdAccessToken`: `string` \| `undefined`; `envdVersion`: `string`; `sandboxDomain`: `string` \| `undefined`; `sandboxId`: `string`; `trafficAccessToken`: `string` \| `undefined`; \}\> + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`createSandbox`](../../sandboxApi/classes/SandboxApi.md#createsandbox) + +*** + +### createSnapshot() + +> `static` **createSnapshot**(`sandboxId`, `opts?`): `Promise`\<[`SnapshotInfo`](../../sandboxApi/interfaces/SnapshotInfo.md)\> + +Create a snapshot from a sandbox. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same state. +The snapshot is a persistent image that survives sandbox deletion. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID to create snapshot from. + +##### opts? + +[`CreateSnapshotOpts`](../../sandboxApi/interfaces/CreateSnapshotOpts.md) + +snapshot creation options including optional name and connection options. + +#### Returns + +`Promise`\<[`SnapshotInfo`](../../sandboxApi/interfaces/SnapshotInfo.md)\> + +snapshot information including the snapshot name that can be used with Sandbox.create(). + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`createSnapshot`](../../sandboxApi/classes/SandboxApi.md#createsnapshot) + +*** + +### deleteSnapshot() + +> `static` **deleteSnapshot**(`snapshotId`, `opts?`): `Promise`\<`boolean`\> + +Delete a snapshot. + +#### Parameters + +##### snapshotId + +`string` + +snapshot ID. + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the snapshot was deleted, `false` if it was not found. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`deleteSnapshot`](../../sandboxApi/classes/SandboxApi.md#deletesnapshot) + +*** + +### fork() + +> `static` **fork**\<`S`\>(`this`, `sandboxId`, `opts?`): `Promise`\<(`Error` \| `InstanceType`\<`S`\>)[]\> + +Fork a running sandbox specified by sandbox ID. + +The sandbox is checkpointed in place (briefly paused, snapshotted with its +full memory state, and resumed — its ID and expiration stay untouched) and +`count` new sandboxes are created from that snapshot. All forks boot from +the same snapshot, so the snapshot is captured once regardless of count. + +Each fork succeeds or fails independently — the returned array contains +one entry per requested fork, either a running Sandbox instance or +an `Error` describing why that fork failed to start +(`Promise.allSettled`-style). Per-fork error codes map to the same error +classes as other API errors (e.g. 429 to `RateLimitError`). + +#### Type Parameters + +##### S + +`S` *extends* *typeof* `Sandbox` + +#### Parameters + +##### this + +`S` + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxForkOpts`](../../sandboxApi/interfaces/SandboxForkOpts.md) + +fork options — `count`, `timeoutMs` and connection options. + +#### Returns + +`Promise`\<(`Error` \| `InstanceType`\<`S`\>)[]\> + +array with one entry per requested fork — a sandbox instance or an error. + +#### Example + +```ts +const sandbox = await Sandbox.create() + +const [fork1, fork2] = await Sandbox.fork(sandbox.sandboxId, { count: 2 }) +if (fork1 instanceof Sandbox) { + await fork1.commands.run('echo "hello from fork"') +} +``` + +*** + +### forkSandbox() + +> `protected` `static` **forkSandbox**(`sandboxId`, `timeoutMs`, `count`, `opts?`): `Promise`\<`SandboxForkResponse`[]\> + +#### Parameters + +##### sandboxId + +`string` + +##### timeoutMs + +`number` + +##### count + +`number` + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +#### Returns + +`Promise`\<`SandboxForkResponse`[]\> + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`forkSandbox`](../../sandboxApi/classes/SandboxApi.md#forksandbox) + +*** + +### getInfo() + +> `static` **getInfo**(`sandboxId`, `opts?`): `Promise`\<[`SandboxInfo`](../../sandboxApi/interfaces/SandboxInfo.md)\> + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`SandboxInfo`](../../sandboxApi/interfaces/SandboxInfo.md)\> + +sandbox information. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`getInfo`](../../sandboxApi/classes/SandboxApi.md#getinfo) + +*** + +### getMetrics() + +> `static` **getMetrics**(`sandboxId`, `opts?`): `Promise`\<[`SandboxMetrics`](../../sandboxApi/interfaces/SandboxMetrics.md)[]\> + +Get the metrics of the sandbox. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxMetricsOpts`](../../sandboxApi/interfaces/SandboxMetricsOpts.md) + +sandbox metrics options. + +#### Returns + +`Promise`\<[`SandboxMetrics`](../../sandboxApi/interfaces/SandboxMetrics.md)[]\> + +List of sandbox metrics containing CPU, memory and disk usage information. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`getMetrics`](../../sandboxApi/classes/SandboxApi.md#getmetrics) + +*** + +### kill() + +> `static` **kill**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Kill the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was found and killed, `false` otherwise. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`kill`](../../sandboxApi/classes/SandboxApi.md#kill) + +*** + +### list() + +> `static` **list**(`opts?`): [`SandboxPaginator`](../../sandboxApi/classes/SandboxPaginator.md) + +List sandboxes. + +By default (no `query.state` set in `opts`), returns sandboxes in both +`running` and `paused` states. To filter by state, pass +`opts.query.state = [...]`. + +#### Parameters + +##### opts? + +[`SandboxListOpts`](../../sandboxApi/interfaces/SandboxListOpts.md) + +connection options, plus optional `query` to filter by + metadata or state, and `limit` / `nextToken` for pagination. + +#### Returns + +[`SandboxPaginator`](../../sandboxApi/classes/SandboxPaginator.md) + +a [SandboxPaginator](../../sandboxApi/classes/SandboxPaginator.md) that yields pages of sandboxes + (running and paused by default). Iterate pages via + `await paginator.nextItems()` while `paginator.hasNext` is `true`. + +*** + +### listSnapshots() + +> `static` **listSnapshots**(`opts?`): [`SnapshotPaginator`](../../sandboxApi/classes/SnapshotPaginator.md) + +List all snapshots. + +#### Parameters + +##### opts? + +[`SnapshotListOpts`](../../sandboxApi/interfaces/SnapshotListOpts.md) + +list options including filters and pagination. + +#### Returns + +[`SnapshotPaginator`](../../sandboxApi/classes/SnapshotPaginator.md) + +paginator for listing snapshots. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`listSnapshots`](../../sandboxApi/classes/SandboxApi.md#listsnapshots) + +*** + +### pause() + +> `static` **pause**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Pause the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxPauseOpts`](../../sandboxApi/interfaces/SandboxPauseOpts.md) + +pause options, including `keepMemory` and connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox got paused, `false` if the sandbox was already paused. + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`pause`](../../sandboxApi/classes/SandboxApi.md#pause) + +*** + +### setTimeout() + +> `static` **setTimeout**(`sandboxId`, `timeoutMs`, `opts?`): `Promise`\<`void`\> + +Set the timeout of the specified sandbox. +After the timeout expires the sandbox will be automatically killed. + +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to [Sandbox.setTimeout](#settimeout-1). + +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### timeoutMs + +`number` + +timeout in **milliseconds**. + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`setTimeout`](../../sandboxApi/classes/SandboxApi.md#settimeout) + +*** + +### updateNetwork() + +> `static` **updateNetwork**(`sandboxId`, `network`, `opts?`): `Promise`\<`void`\> + +Update the network configuration of a running sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### network + +[`SandboxNetworkUpdate`](../../sandboxApi/type-aliases/SandboxNetworkUpdate.md) + +new network configuration. + +##### opts? + +[`SandboxApiOpts`](../../sandboxApi/interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +[`SandboxApi`](../../sandboxApi/classes/SandboxApi.md).[`updateNetwork`](../../sandboxApi/classes/SandboxApi.md#updatenetwork) diff --git a/reference/sdk/javascript/sandbox/index/interfaces/SandboxUrlOpts.md b/reference/sdk/javascript/sandbox/index/interfaces/SandboxUrlOpts.md new file mode 100644 index 00000000..5293c76b --- /dev/null +++ b/reference/sdk/javascript/sandbox/index/interfaces/SandboxUrlOpts.md @@ -0,0 +1,22 @@ +[@abox-dev/sdk](../../README.md) / [index](../README.md) / SandboxUrlOpts + +# Interface: SandboxUrlOpts + +Options for sandbox upload/download URL generation. + +## Properties + +### user? + +> `optional` **user?**: `string` + +User that will be used to access the file. + +*** + +### useSignatureExpiration? + +> `optional` **useSignatureExpiration?**: `number` + +Use signature expiration for the URL. +Optional parameter to set the expiration time for the signature in seconds. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/README.md b/reference/sdk/javascript/sandbox/sandboxApi/README.md new file mode 100644 index 00000000..05d6d2a9 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/README.md @@ -0,0 +1,47 @@ +[@abox-dev/sdk](../README.md) / sandboxApi + +# sandboxApi + +## Classes + +- [SandboxApi](classes/SandboxApi.md) +- [SandboxPaginator](classes/SandboxPaginator.md) +- [SnapshotPaginator](classes/SnapshotPaginator.md) + +## Interfaces + +- [CreateSnapshotOpts](interfaces/CreateSnapshotOpts.md) +- [SandboxApiOpts](interfaces/SandboxApiOpts.md) +- [SandboxForkOpts](interfaces/SandboxForkOpts.md) +- [SandboxIamOpts](interfaces/SandboxIamOpts.md) +- [SandboxIamToken](interfaces/SandboxIamToken.md) +- [SandboxInfo](interfaces/SandboxInfo.md) +- [SandboxListOpts](interfaces/SandboxListOpts.md) +- [SandboxMetrics](interfaces/SandboxMetrics.md) +- [SandboxMetricsOpts](interfaces/SandboxMetricsOpts.md) +- [SandboxOpts](interfaces/SandboxOpts.md) +- [SandboxPauseOpts](interfaces/SandboxPauseOpts.md) +- [SnapshotInfo](interfaces/SnapshotInfo.md) +- [SnapshotListOpts](interfaces/SnapshotListOpts.md) + +## Type Aliases + +- [GitHubMcpServer](type-aliases/GitHubMcpServer.md) +- [McpServer](type-aliases/McpServer.md) +- [SandboxConnectOpts](type-aliases/SandboxConnectOpts.md) +- [SandboxIamTokenType](type-aliases/SandboxIamTokenType.md) +- [SandboxInfoLifecycle](type-aliases/SandboxInfoLifecycle.md) +- [SandboxLifecycle](type-aliases/SandboxLifecycle.md) +- [SandboxNetworkInfo](type-aliases/SandboxNetworkInfo.md) +- [SandboxNetworkOpts](type-aliases/SandboxNetworkOpts.md) +- [SandboxNetworkRule](type-aliases/SandboxNetworkRule.md) +- [SandboxNetworkRuleInfo](type-aliases/SandboxNetworkRuleInfo.md) +- [SandboxNetworkRules](type-aliases/SandboxNetworkRules.md) +- [SandboxNetworkSelector](type-aliases/SandboxNetworkSelector.md) +- [SandboxNetworkSelectorContext](type-aliases/SandboxNetworkSelectorContext.md) +- [SandboxNetworkTransform](type-aliases/SandboxNetworkTransform.md) +- [SandboxNetworkTransformContext](type-aliases/SandboxNetworkTransformContext.md) +- [SandboxNetworkTransformResolver](type-aliases/SandboxNetworkTransformResolver.md) +- [SandboxNetworkUpdate](type-aliases/SandboxNetworkUpdate.md) +- [SandboxOnTimeout](type-aliases/SandboxOnTimeout.md) +- [SandboxState](type-aliases/SandboxState.md) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxApi.md b/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxApi.md new file mode 100644 index 00000000..1563dbda --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxApi.md @@ -0,0 +1,363 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxApi + +# Class: SandboxApi + +## Extends + +- `ClientFactory` + +## Extended by + +- [`Sandbox`](../../index/classes/Sandbox.md) + +## Constructors + +### Constructor + +> `protected` **new SandboxApi**(): `SandboxApi` + +#### Returns + +`SandboxApi` + +#### Overrides + +`ClientFactory.constructor` + +## Methods + +### 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`; \}\> + +*** + +### 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`; \}\> + +*** + +### createSnapshot() + +> `static` **createSnapshot**(`sandboxId`, `opts?`): `Promise`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md)\> + +Create a snapshot from a sandbox. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same state. +The snapshot is a persistent image that survives sandbox deletion. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID to create snapshot from. + +##### opts? + +[`CreateSnapshotOpts`](../interfaces/CreateSnapshotOpts.md) + +snapshot creation options including optional name and connection options. + +#### Returns + +`Promise`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md)\> + +snapshot information including the snapshot name that can be used with Sandbox.create(). + +*** + +### deleteSnapshot() + +> `static` **deleteSnapshot**(`snapshotId`, `opts?`): `Promise`\<`boolean`\> + +Delete a snapshot. + +#### Parameters + +##### snapshotId + +`string` + +snapshot ID. + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the snapshot was deleted, `false` if it was not found. + +*** + +### 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`[]\> + +*** + +### getInfo() + +> `static` **getInfo**(`sandboxId`, `opts?`): `Promise`\<[`SandboxInfo`](../interfaces/SandboxInfo.md)\> + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<[`SandboxInfo`](../interfaces/SandboxInfo.md)\> + +sandbox information. + +*** + +### getMetrics() + +> `static` **getMetrics**(`sandboxId`, `opts?`): `Promise`\<[`SandboxMetrics`](../interfaces/SandboxMetrics.md)[]\> + +Get the metrics of the sandbox. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxMetricsOpts`](../interfaces/SandboxMetricsOpts.md) + +sandbox metrics options. + +#### Returns + +`Promise`\<[`SandboxMetrics`](../interfaces/SandboxMetrics.md)[]\> + +List of sandbox metrics containing CPU, memory and disk usage information. + +*** + +### kill() + +> `static` **kill**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Kill the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was found and killed, `false` otherwise. + +*** + +### listSnapshots() + +> `static` **listSnapshots**(`opts?`): [`SnapshotPaginator`](SnapshotPaginator.md) + +List all snapshots. + +#### Parameters + +##### opts? + +[`SnapshotListOpts`](../interfaces/SnapshotListOpts.md) + +list options including filters and pagination. + +#### Returns + +[`SnapshotPaginator`](SnapshotPaginator.md) + +paginator for listing snapshots. + +*** + +### pause() + +> `static` **pause**(`sandboxId`, `opts?`): `Promise`\<`boolean`\> + +Pause the sandbox specified by sandbox ID. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### opts? + +[`SandboxPauseOpts`](../interfaces/SandboxPauseOpts.md) + +pause options, including `keepMemory` and connection options. + +#### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox got paused, `false` if the sandbox was already paused. + +*** + +### setTimeout() + +> `static` **setTimeout**(`sandboxId`, `timeoutMs`, `opts?`): `Promise`\<`void`\> + +Set the timeout of the specified sandbox. +After the timeout expires the sandbox will be automatically killed. + +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to Sandbox.setTimeout. + +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### timeoutMs + +`number` + +timeout in **milliseconds**. + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> + +*** + +### updateNetwork() + +> `static` **updateNetwork**(`sandboxId`, `network`, `opts?`): `Promise`\<`void`\> + +Update the network configuration of a running sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +#### Parameters + +##### sandboxId + +`string` + +sandbox ID. + +##### network + +[`SandboxNetworkUpdate`](../type-aliases/SandboxNetworkUpdate.md) + +new network configuration. + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +connection options. + +#### Returns + +`Promise`\<`void`\> diff --git a/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxPaginator.md b/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxPaginator.md new file mode 100644 index 00000000..75663e8e --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/classes/SandboxPaginator.md @@ -0,0 +1,153 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxPaginator + +# Class: SandboxPaginator + +Paginator for listing sandboxes. + +## Example + +```ts +const paginator = Sandbox.list() +while (paginator.hasNext) { + const sandboxes = await paginator.nextItems() + console.log(sandboxes) +} +``` + +## Extends + +- `Paginator`\<[`SandboxInfo`](../interfaces/SandboxInfo.md), [`SandboxApiOpts`](../interfaces/SandboxApiOpts.md)\> + +## Constructors + +### Constructor + +> **new SandboxPaginator**(`opts?`): `SandboxPaginator` + +#### Parameters + +##### opts? + +[`SandboxListOpts`](../interfaces/SandboxListOpts.md) + +#### Returns + +`SandboxPaginator` + +#### Overrides + +`Paginator.constructor` + +## Properties + +### limit? + +> `protected` `readonly` `optional` **limit?**: `number` + +#### Inherited from + +`Paginator.limit` + +*** + +### opts? + +> `protected` `readonly` `optional` **opts?**: [`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +#### Inherited from + +`Paginator.opts` + +## Accessors + +### hasNext + +#### Get Signature + +> **get** **hasNext**(): `boolean` + +Returns true if there are more items to fetch. + +##### Returns + +`boolean` + +#### Inherited from + +`Paginator.hasNext` + +*** + +### nextToken + +#### Get Signature + +> **get** **nextToken**(): `string` \| `undefined` + +Returns the next token to use for pagination. + +##### Returns + +`string` \| `undefined` + +#### Inherited from + +`Paginator.nextToken` + +## Methods + +### nextItems() + +> **nextItems**(`opts?`): `Promise`\<[`SandboxInfo`](../interfaces/SandboxInfo.md)[]\> + +Get the next page of items. + +#### Parameters + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +per-call connection options. When provided, this call uses +these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`, +`signal`) instead of the ones the paginator was constructed with. +Aborting a page via `signal` does not affect subsequent Paginator.nextItems +calls — pass a fresh signal each call you want to be cancellable. + +#### Returns + +`Promise`\<[`SandboxInfo`](../interfaces/SandboxInfo.md)[]\> + +List of items + +#### Throws + +Error if there are no more items to fetch. Call this method only if `hasNext` is `true`. + +#### 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/sandboxApi/classes/SnapshotPaginator.md b/reference/sdk/javascript/sandbox/sandboxApi/classes/SnapshotPaginator.md new file mode 100644 index 00000000..f08afceb --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/classes/SnapshotPaginator.md @@ -0,0 +1,153 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SnapshotPaginator + +# Class: SnapshotPaginator + +Paginator for listing snapshots. + +## Example + +```ts +const paginator = Sandbox.listSnapshots() +while (paginator.hasNext) { + const snapshots = await paginator.nextItems() + console.log(snapshots) +} +``` + +## Extends + +- `Paginator`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md), [`SandboxApiOpts`](../interfaces/SandboxApiOpts.md)\> + +## Constructors + +### Constructor + +> **new SnapshotPaginator**(`opts?`): `SnapshotPaginator` + +#### Parameters + +##### opts? + +[`SnapshotListOpts`](../interfaces/SnapshotListOpts.md) + +#### Returns + +`SnapshotPaginator` + +#### Overrides + +`Paginator.constructor` + +## Properties + +### limit? + +> `protected` `readonly` `optional` **limit?**: `number` + +#### Inherited from + +`Paginator.limit` + +*** + +### opts? + +> `protected` `readonly` `optional` **opts?**: [`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +#### Inherited from + +`Paginator.opts` + +## Accessors + +### hasNext + +#### Get Signature + +> **get** **hasNext**(): `boolean` + +Returns true if there are more items to fetch. + +##### Returns + +`boolean` + +#### Inherited from + +`Paginator.hasNext` + +*** + +### nextToken + +#### Get Signature + +> **get** **nextToken**(): `string` \| `undefined` + +Returns the next token to use for pagination. + +##### Returns + +`string` \| `undefined` + +#### Inherited from + +`Paginator.nextToken` + +## Methods + +### nextItems() + +> **nextItems**(`opts?`): `Promise`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md)[]\> + +Get the next page of items. + +#### Parameters + +##### opts? + +[`SandboxApiOpts`](../interfaces/SandboxApiOpts.md) + +per-call connection options. When provided, this call uses +these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`, +`signal`) instead of the ones the paginator was constructed with. +Aborting a page via `signal` does not affect subsequent Paginator.nextItems +calls — pass a fresh signal each call you want to be cancellable. + +#### Returns + +`Promise`\<[`SnapshotInfo`](../interfaces/SnapshotInfo.md)[]\> + +List of items + +#### Throws + +Error if there are no more items to fetch. Call this method only if `hasNext` is `true`. + +#### 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/sandboxApi/interfaces/CreateSnapshotOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/CreateSnapshotOpts.md new file mode 100644 index 00000000..c68278a5 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/CreateSnapshotOpts.md @@ -0,0 +1,115 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / CreateSnapshotOpts + +# Interface: CreateSnapshotOpts + +Options for creating a snapshot. + +## Extends + +- [`SandboxApiOpts`](SandboxApiOpts.md) + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### name? + +> `optional` **name?**: `string` + +Optional name for the snapshot template. +If a snapshot template with this name already exists, a new build will be assigned +to the existing template instead of creating a new one. + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`signal`](SandboxForkOpts.md#signal) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxApiOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxApiOpts.md new file mode 100644 index 00000000..4e7194be --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxApiOpts.md @@ -0,0 +1,111 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxApiOpts + +# Interface: SandboxApiOpts + +Options for request to the Sandbox API. + +## Extends + +- `Partial`\<`Pick`\<`ConnectionOpts`, `"apiKey"` \| `"apiHeaders"` \| `"debug"` \| `"domain"` \| `"requestTimeoutMs"` \| `"signal"`\>\> + +## Extended by + +- [`SandboxPauseOpts`](SandboxPauseOpts.md) +- [`SandboxMetricsOpts`](SandboxMetricsOpts.md) +- [`CreateSnapshotOpts`](CreateSnapshotOpts.md) + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`signal`](SandboxForkOpts.md#signal) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxForkOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxForkOpts.md new file mode 100644 index 00000000..c5880f34 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxForkOpts.md @@ -0,0 +1,205 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxForkOpts + +# Interface: SandboxForkOpts + +Options for forking a sandbox. + +## Extends + +- `ConnectionOpts` + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +`ConnectionOpts.apiHeaders` + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +`ConnectionOpts.apiKey` + +*** + +### 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` + +Number of forked sandboxes to create. + +All forks boot from the same snapshot — 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 returned array. + +#### Default + +```ts +1 +``` + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +`ConnectionOpts.domain` + +*** + +### logger? + +> `optional` **logger?**: `Logger` + +Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, console. + +#### Inherited from + +`ConnectionOpts.logger` + +*** + +### proxy? + +> `optional` **proxy?**: `string` + +Proxy URL to use for requests. In case of a sandbox it applies to all +requests made to the returned sandbox. + +#### Example + +```ts +'http://user:pass@127.0.0.1:8080' +``` + +#### Inherited from + +`ConnectionOpts.proxy` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +`ConnectionOpts.requestTimeoutMs` + +*** + +### 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` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +`ConnectionOpts.signal` + +*** + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the forked sandboxes in **milliseconds**. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Default + +```ts +300_000 // 5 minutes +``` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamOpts.md new file mode 100644 index 00000000..f9c6de9c --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamOpts.md @@ -0,0 +1,19 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxIamOpts + +# Interface: SandboxIamOpts + +Sandbox workload identity configuration. A non-empty `tokens` map enables +workload identity for the sandbox. + +## Properties + +### tokens? + +> `optional` **tokens?**: `Record`\<`string`, [`SandboxIamToken`](SandboxIamToken.md)\> + +Named workload-token definitions, keyed by a caller-chosen token name. +Each value contains the token `audience` and `tokenType`. + +A name is interpolated into the `'${agentbox.identity.tokens.}'` +placeholder a network transform resolves, so it cannot be empty or contain +`{`, `}` or control characters. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamToken.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamToken.md new file mode 100644 index 00000000..c1495ebf --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxIamToken.md @@ -0,0 +1,21 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxIamToken + +# Interface: SandboxIamToken + +Workload token definition for sandbox workload identity. + +## Properties + +### audience + +> **audience**: `string` + +Audience of the workload token, stored exactly as provided. + +*** + +### tokenType + +> **tokenType**: [`SandboxIamTokenType`](../type-aliases/SandboxIamTokenType.md) + +Workload token type. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxInfo.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxInfo.md new file mode 100644 index 00000000..17e9e51e --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxInfo.md @@ -0,0 +1,121 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxInfo + +# Interface: SandboxInfo + +Information about a sandbox. + +## Properties + +### allowInternetAccess? + +> `optional` **allowInternetAccess?**: `boolean` + +Whether internet access was explicitly enabled or disabled for the sandbox. + +*** + +### cpuCount + +> **cpuCount**: `number` + +Sandbox CPU count. + +*** + +### endAt + +> **endAt**: `Date` + +Sandbox expiration date. + +*** + +### envdVersion + +> **envdVersion**: `string` + +Envd version. + +*** + +### lifecycle? + +> `optional` **lifecycle?**: [`SandboxInfoLifecycle`](../type-aliases/SandboxInfoLifecycle.md) + +Sandbox lifecycle configuration. + +*** + +### memoryMB + +> **memoryMB**: `number` + +Sandbox Memory size in MiB. + +*** + +### metadata + +> **metadata**: `Record`\<`string`, `string`\> + +Saved sandbox metadata. + +*** + +### name? + +> `optional` **name?**: `string` + +Template name. + +*** + +### network? + +> `optional` **network?**: [`SandboxNetworkInfo`](../type-aliases/SandboxNetworkInfo.md) + +Sandbox network configuration. + +*** + +### sandboxDomain? + +> `optional` **sandboxDomain?**: `string` + +Sandbox domain. + +*** + +### sandboxId + +> **sandboxId**: `string` + +Sandbox ID. + +*** + +### startedAt + +> **startedAt**: `Date` + +Sandbox start time. + +*** + +### state + +> **state**: [`SandboxState`](../type-aliases/SandboxState.md) + +Sandbox state. + +#### String + +can be `running` or `paused` + +*** + +### templateId + +> **templateId**: `string` + +Template ID. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxListOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxListOpts.md new file mode 100644 index 00000000..686a64e5 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxListOpts.md @@ -0,0 +1,135 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxListOpts + +# Interface: SandboxListOpts + +## Extends + +- `Omit`\<[`SandboxApiOpts`](SandboxApiOpts.md), `"signal"`\> + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### limit? + +> `optional` **limit?**: `number` + +Number of sandboxes to return per page. + +#### Default + +```ts +100 +``` + +*** + +### nextToken? + +> `optional` **nextToken?**: `string` + +Token to the next page. + +*** + +### query? + +> `optional` **query?**: `object` + +Filter the list of sandboxes, e.g. by metadata `metadata:{"key": "value"}`, if there are multiple filters they are combined with AND. + +#### metadata? + +> `optional` **metadata?**: `Record`\<`string`, `string`\> + +#### state? + +> `optional` **state?**: [`SandboxState`](../type-aliases/SandboxState.md)[] + +Filter the list of sandboxes by state. + +##### Default + +```ts +['running', 'paused'] +``` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetrics.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetrics.md new file mode 100644 index 00000000..2a7601e1 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetrics.md @@ -0,0 +1,69 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxMetrics + +# Interface: SandboxMetrics + +Sandbox resource usage metrics. + +## Properties + +### cpuCount + +> **cpuCount**: `number` + +Number of CPU cores. + +*** + +### cpuUsedPct + +> **cpuUsedPct**: `number` + +CPU usage in percentage. + +*** + +### diskTotal + +> **diskTotal**: `number` + +Total disk space available in bytes. + +*** + +### diskUsed + +> **diskUsed**: `number` + +Used disk space in bytes. + +*** + +### memCache + +> **memCache**: `number` + +Cached memory (page cache) in bytes. + +*** + +### memTotal + +> **memTotal**: `number` + +Total memory available in bytes. + +*** + +### memUsed + +> **memUsed**: `number` + +Memory usage in bytes. + +*** + +### timestamp + +> **timestamp**: `Date` + +Timestamp of the metrics. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetricsOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetricsOpts.md new file mode 100644 index 00000000..01633cf2 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxMetricsOpts.md @@ -0,0 +1,121 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxMetricsOpts + +# Interface: SandboxMetricsOpts + +Options for request to the Sandbox API. + +## Extends + +- [`SandboxApiOpts`](SandboxApiOpts.md) + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### end? + +> `optional` **end?**: `Date` + +End time for the metrics, defaults to the current time + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`signal`](SandboxForkOpts.md#signal) + +*** + +### start? + +> `optional` **start?**: `Date` + +Start time for the metrics, defaults to the start of the sandbox diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxOpts.md new file mode 100644 index 00000000..cd87223e --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxOpts.md @@ -0,0 +1,310 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxOpts + +# Interface: SandboxOpts + +Options for creating a new Sandbox. + +## Extends + +- `ConnectionOpts` + +## Properties + +### allowInternetAccess? + +> `optional` **allowInternetAccess?**: `boolean` + +Allow sandbox to access the internet. If set to `False`, it works the same as setting network `denyOut` to `[0.0.0.0/0]`. + +#### Default + +```ts +true +``` + +*** + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +`ConnectionOpts.apiHeaders` + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +`ConnectionOpts.apiKey` + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +`ConnectionOpts.domain` + +*** + +### envs? + +> `optional` **envs?**: `Record`\<`string`, `string`\> + +Custom environment variables for the sandbox. + +Used when executing commands and code in the sandbox. +Can be overridden with the `envs` argument when executing commands or code. + +#### Default + +```ts +{} +``` + +*** + +### iam? + +> `optional` **iam?**: [`SandboxIamOpts`](SandboxIamOpts.md) + +Sandbox workload identity configuration. Providing a non-empty +`tokens` map enables workload identity for the sandbox. + +Registered tokens are exposed to [SandboxNetworkOpts.rules](../type-aliases/SandboxNetworkOpts.md#rules) +`transform` callbacks as `iam.tokens.` placeholders, which the egress +proxy resolves per request. + +#### Example + +```ts +const sandbox = await Sandbox.create({ + iam: { + tokens: { + aws: { + audience: 'sts.amazonaws.com', + tokenType: 'JWT-SVID', + }, + }, + }, +}) +``` + +*** + +### lifecycle? + +> `optional` **lifecycle?**: [`SandboxLifecycle`](../type-aliases/SandboxLifecycle.md) + +Sandbox lifecycle configuration. + +*** + +### logger? + +> `optional` **logger?**: `Logger` + +Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, console. + +#### Inherited from + +`ConnectionOpts.logger` + +*** + +### mcp? + +> `optional` **mcp?**: [`McpServer`](../type-aliases/McpServer.md) + +MCP server to enable in the sandbox + +#### Default + +```ts +undefined +``` + +*** + +### metadata? + +> `optional` **metadata?**: `Record`\<`string`, `string`\> + +Custom metadata for the sandbox. + +#### Default + +```ts +{} +``` + +*** + +### network? + +> `optional` **network?**: [`SandboxNetworkOpts`](../type-aliases/SandboxNetworkOpts.md) + +Sandbox network configuration + +*** + +### proxy? + +> `optional` **proxy?**: `string` + +Proxy URL to use for requests. In case of a sandbox it applies to all +requests made to the returned sandbox. + +#### Example + +```ts +'http://user:pass@127.0.0.1:8080' +``` + +#### Inherited from + +`ConnectionOpts.proxy` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +`ConnectionOpts.requestTimeoutMs` + +*** + +### sandboxUrl? + +> `optional` **sandboxUrl?**: `string` + +Sandbox URL. Used for local development + +#### Overrides + +`ConnectionOpts.sandboxUrl` + +*** + +### secure? + +> `optional` **secure?**: `boolean` + +Secure all traffic coming to the sandbox controller with auth token + +#### Default + +```ts +true +``` + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +`ConnectionOpts.signal` + +*** + +### template? + +> `optional` **template?**: `string` + +Sandbox template name or ID. + +#### Default + +'base' (or 'mcp-gateway' when `mcp` option is set) + +*** + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the sandbox in **milliseconds**. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Default + +```ts +300_000 // 5 minutes +``` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxPauseOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxPauseOpts.md new file mode 100644 index 00000000..0986bb40 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SandboxPauseOpts.md @@ -0,0 +1,123 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxPauseOpts + +# Interface: SandboxPauseOpts + +Options for pausing a sandbox. + +## Extends + +- [`SandboxApiOpts`](SandboxApiOpts.md) + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### keepMemory? + +> `optional` **keepMemory?**: `boolean` + +Whether to keep a full memory snapshot. + +When `false`, the in-memory state is dropped and only the filesystem is +persisted (a filesystem-only snapshot); resuming such a sandbox cold-boots +(reboots) it from disk, losing running processes and open connections. + +#### Default + +```ts +true +``` + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) + +*** + +### signal? + +> `optional` **signal?**: `AbortSignal` + +An optional `AbortSignal` that can be used to cancel the in-flight request. +When the signal is aborted, the underlying `fetch` is aborted and the +returned promise rejects with an `AbortError`. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`signal`](SandboxForkOpts.md#signal) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotInfo.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotInfo.md new file mode 100644 index 00000000..38e679ff --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotInfo.md @@ -0,0 +1,22 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SnapshotInfo + +# Interface: SnapshotInfo + +Information about a snapshot. + +## Properties + +### names + +> **names**: `string`[] + +Full names of the snapshot template including project slug and tag (e.g. project-slug/my-snapshot:v2). + +*** + +### snapshotId + +> **snapshotId**: `string` + +Snapshot identifier — template ID with tag, or namespaced name with tag (e.g. my-snapshot:latest). +Can be used with Sandbox.create() to create a new sandbox from this snapshot. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotListOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotListOpts.md new file mode 100644 index 00000000..dc69fbd9 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/interfaces/SnapshotListOpts.md @@ -0,0 +1,130 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SnapshotListOpts + +# Interface: SnapshotListOpts + +Options for listing snapshots. + +## Extends + +- `Omit`\<[`SandboxApiOpts`](SandboxApiOpts.md), `"signal"`\> + +## Properties + +### apiHeaders? + +> `optional` **apiHeaders?**: `Record`\<`string`, `string`\> + +Additional headers to send with AgentBox API requests. + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiHeaders`](SandboxForkOpts.md#apiheaders) + +*** + +### apiKey? + +> `optional` **apiKey?**: `string` + +AgentBox API key to use for authentication. + +#### Default + +```ts +AGENTBOX_API_KEY // environment variable +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`apiKey`](SandboxForkOpts.md#apikey) + +*** + +### 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` + +Domain to use for the API. + +#### Default + +AGENTBOX_DOMAIN // environment variable or `agentbox-runtime.ru` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`domain`](SandboxForkOpts.md#domain) + +*** + +### limit? + +> `optional` **limit?**: `number` + +Number of snapshots to return per page. + +#### Default + +```ts +100 +``` + +*** + +### name? + +> `optional` **name?**: `string` + +Filter snapshots by name or ID, optionally tag-qualified +(e.g. "my-snapshot", "my-project/my-snapshot" or "my-snapshot:v1"). + +*** + +### nextToken? + +> `optional` **nextToken?**: `string` + +Token to the next page. + +*** + +### requestTimeoutMs? + +> `optional` **requestTimeoutMs?**: `number` + +Timeout for requests to the API in **milliseconds**. + +#### Default + +```ts +60_000 // 60 seconds +``` + +#### Inherited from + +[`SandboxForkOpts`](SandboxForkOpts.md).[`requestTimeoutMs`](SandboxForkOpts.md#requesttimeoutms) + +*** + +### sandboxId? + +> `optional` **sandboxId?**: `string` + +Filter snapshots by source sandbox ID. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/GitHubMcpServer.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/GitHubMcpServer.md new file mode 100644 index 00000000..43047191 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/GitHubMcpServer.md @@ -0,0 +1,9 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / GitHubMcpServer + +# Type Alias: GitHubMcpServer + +> **GitHubMcpServer** = `object` + +## Index Signature + +\[`key`: `` `github/${string}` ``\]: `object` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/McpServer.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/McpServer.md new file mode 100644 index 00000000..e27cb627 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/McpServer.md @@ -0,0 +1,8 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / McpServer + +# Type Alias: McpServer + +> **McpServer** = `BaseMcpServer` \| [`GitHubMcpServer`](GitHubMcpServer.md) + +Extended MCP server configuration that includes base servers +and allows dynamic GitHub-based MCP servers with custom run and install commands. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxConnectOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxConnectOpts.md new file mode 100644 index 00000000..bdc6246f --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxConnectOpts.md @@ -0,0 +1,23 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxConnectOpts + +# Type Alias: SandboxConnectOpts + +> **SandboxConnectOpts** = `ConnectionOpts` & `object` + +Options for connecting to a Sandbox. + +## Type Declaration + +### timeoutMs? + +> `optional` **timeoutMs?**: `number` + +Timeout for the sandbox in **milliseconds**. +For running sandboxes, the timeout will update only if the new timeout is longer than the existing one. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +#### Default + +```ts +300_000 // 5 minutes +``` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxIamTokenType.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxIamTokenType.md new file mode 100644 index 00000000..81fa1a4f --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxIamTokenType.md @@ -0,0 +1,9 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxIamTokenType + +# Type Alias: SandboxIamTokenType + +> **SandboxIamTokenType** = `"JWT-SVID"` \| `string` & `object` + +Workload token type. `'JWT-SVID'` is the only type the API accepts in this +version; the set is defined server-side and may grow, so any string is +allowed. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxInfoLifecycle.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxInfoLifecycle.md new file mode 100644 index 00000000..e6a35134 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxInfoLifecycle.md @@ -0,0 +1,21 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxInfoLifecycle + +# Type Alias: SandboxInfoLifecycle + +> **SandboxInfoLifecycle** = `object` + +## Properties + +### autoResume + +> **autoResume**: `boolean` + +Whether the sandbox can auto-resume. + +*** + +### onTimeout + +> **onTimeout**: `"pause"` \| `"kill"` + +Action to take when sandbox timeout is reached. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxLifecycle.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxLifecycle.md new file mode 100644 index 00000000..e1c4ac9d --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxLifecycle.md @@ -0,0 +1,30 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxLifecycle + +# Type Alias: SandboxLifecycle + +> **SandboxLifecycle** = `object` + +## Properties + +### autoResume? + +> `optional` **autoResume?**: `boolean` + +Auto-resume enabled flag. + +Leave unset to let the API pick the behavior. Set `false` to opt out +explicitly and keep auto-resume off even if the API's default changes. +Can be `true` only when `onTimeout` is `pause`. Not supported when +`keepMemory` is `false` (a filesystem-only snapshot must be resumed +explicitly via `connect()`). + +*** + +### onTimeout + +> **onTimeout**: [`SandboxOnTimeout`](SandboxOnTimeout.md) + +Action to take when sandbox timeout is reached. Accepts either `'pause'` / +`'kill'`, or `{ action, keepMemory }` to also control the pause snapshot kind. +Omitted from the create request when unset, leaving the API's default +(currently `kill`) in effect. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkInfo.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkInfo.md new file mode 100644 index 00000000..40cc0564 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkInfo.md @@ -0,0 +1,39 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkInfo + +# Type Alias: SandboxNetworkInfo + +> **SandboxNetworkInfo** = `object` + +Network configuration as returned by the sandbox info endpoint. Mirrors +[SandboxNetworkOpts](SandboxNetworkOpts.md) but with `allowOut`/`denyOut` always materialized +to plain string arrays. + +## Properties + +### allowOut? + +> `optional` **allowOut?**: `string`[] + +*** + +### allowPublicTraffic? + +> `optional` **allowPublicTraffic?**: `boolean` + +*** + +### denyOut? + +> `optional` **denyOut?**: `string`[] + +*** + +### maskRequestHost? + +> `optional` **maskRequestHost?**: `string` + +*** + +### rules? + +> `optional` **rules?**: `Record`\<`string`, [`SandboxNetworkRuleInfo`](SandboxNetworkRuleInfo.md)[]\> diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkOpts.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkOpts.md new file mode 100644 index 00000000..e0b30c1e --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkOpts.md @@ -0,0 +1,108 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkOpts + +# Type Alias: SandboxNetworkOpts + +> **SandboxNetworkOpts** = `object` + +## Properties + +### allowOut? + +> `optional` **allowOut?**: [`SandboxNetworkSelector`](SandboxNetworkSelector.md) + +Allow outbound traffic from the sandbox to the specified addresses. +If `allowOut` is not specified, all outbound traffic is allowed. + +Accepts either a static array of CIDR blocks, IP addresses, or hostnames, +or a callback that receives `{ allTraffic, rules }` and returns the same. +`allTraffic` is `'0.0.0.0/0'`; `rules` is a `Map` view of +[SandboxNetworkOpts.rules](#rules). + +Examples: +- Static list: `["1.1.1.1", "8.8.8.0/24"]` +- Allow only rule-registered hosts: + `({ rules }) => [...rules.keys()]` + +*** + +### allowPublicTraffic? + +> `optional` **allowPublicTraffic?**: `boolean` + +Specify if the sandbox URLs should be accessible only with authentication. + +#### Default + +```ts +true +``` + +*** + +### denyOut? + +> `optional` **denyOut?**: [`SandboxNetworkSelector`](SandboxNetworkSelector.md) + +Deny outbound traffic from the sandbox to the specified addresses. + +Accepts the same shapes as [allowOut](#allowout). + +Examples: +- Static list: `["1.1.1.1", "8.8.8.0/24"]` +- Block all egress: `({ allTraffic }) => [allTraffic]` + +*** + +### maskRequestHost? + +> `optional` **maskRequestHost?**: `string` + +Specify host mask which will be used for all sandbox requests in the header. +You can use the ${PORT} variable that will be replaced with the actual port number of the service. + +#### Default + +```ts +${PORT}-sandboxid.agentbox-runtime.ru +``` + +*** + +### rules? + +> `optional` **rules?**: [`SandboxNetworkRules`](SandboxNetworkRules.md) + +Per-domain transform rules applied to matching egress HTTP/HTTPS +requests. Keys are domains (e.g. `"api.example.com"`); values are +ordered lists of rules. + +Registering a host here does not allow egress on its own — the host must +also appear in [allowOut](#allowout). Hosts registered here are exposed to the +`allowOut`/`denyOut` callbacks via `rules`. + +A rule's `transform` can also be a callback receiving a +[SandboxNetworkTransformContext](SandboxNetworkTransformContext.md), which is how a workload identity +token from [SandboxOpts.iam](../interfaces/SandboxOpts.md#iam) gets injected without the SDK ever +seeing its value. + +#### Example + +```ts +await Sandbox.create({ + network: { + allowOut: ({ rules }) => [...rules.keys()], + rules: { + 'api.openai.com': [ + { transform: { headers: { Authorization: `Bearer ${token}` } } }, + ], + 'api.internal.example.com': [ + { + transform: ({ iam }) => ({ + headers: { Authorization: `Bearer ${iam.tokens.aws}` }, + }), + }, + ], + }, + }, +}) +``` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRule.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRule.md new file mode 100644 index 00000000..bb6c28e6 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRule.md @@ -0,0 +1,29 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkRule + +# Type Alias: SandboxNetworkRule + +> **SandboxNetworkRule** = `object` + +Per-domain rule applied to egress requests. + +## Properties + +### transform? + +> `optional` **transform?**: [`SandboxNetworkTransform`](SandboxNetworkTransform.md) \| [`SandboxNetworkTransformResolver`](SandboxNetworkTransformResolver.md) + +Transform applied to requests matching this rule. + +Accepts either a static object or a callback that receives a +[SandboxNetworkTransformContext](SandboxNetworkTransformContext.md) of placeholder strings — use the +callback to inject a workload identity token the proxy mints per request. + +#### Example + +```ts +{ + transform: ({ iam }) => ({ + headers: { Authorization: `Bearer ${iam.tokens.aws}` }, + }), +} +``` diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRuleInfo.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRuleInfo.md new file mode 100644 index 00000000..91b438f6 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRuleInfo.md @@ -0,0 +1,15 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkRuleInfo + +# Type Alias: SandboxNetworkRuleInfo + +> **SandboxNetworkRuleInfo** = `object` + +Per-domain rule as returned by the sandbox info endpoint. Mirrors +[SandboxNetworkRule](SandboxNetworkRule.md) but with `transform` always materialized to the +static [SandboxNetworkTransform](SandboxNetworkTransform.md) shape — no callback variant. + +## Properties + +### transform? + +> `optional` **transform?**: [`SandboxNetworkTransform`](SandboxNetworkTransform.md) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRules.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRules.md new file mode 100644 index 00000000..d22cfaee --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkRules.md @@ -0,0 +1,10 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkRules + +# Type Alias: SandboxNetworkRules + +> **SandboxNetworkRules** = `Record`\<`string`, [`SandboxNetworkRule`](SandboxNetworkRule.md)[]\> \| `Map`\<`string`, [`SandboxNetworkRule`](SandboxNetworkRule.md)[]\> + +Map of host (or CIDR / IP) to ordered list of rules applied to outbound +requests for that host. Accepts either a plain object or a `Map`. +Registering a host here does not allow egress on its own — the host must +also appear in [SandboxNetworkOpts.allowOut](SandboxNetworkOpts.md#allowout). diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelector.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelector.md new file mode 100644 index 00000000..4137c482 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelector.md @@ -0,0 +1,9 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkSelector + +# Type Alias: SandboxNetworkSelector + +> **SandboxNetworkSelector** = `string`[] \| ((`ctx`) => `string`[]) + +Egress rule list, either a static array of CIDR blocks / IP addresses / +hostnames, or a callback that receives `{ allTraffic, rules }` and returns +the same. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelectorContext.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelectorContext.md new file mode 100644 index 00000000..32d4d5d0 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkSelectorContext.md @@ -0,0 +1,24 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkSelectorContext + +# Type Alias: SandboxNetworkSelectorContext + +> **SandboxNetworkSelectorContext** = `object` + +Context passed to [SandboxNetworkOpts.allowOut](SandboxNetworkOpts.md#allowout) and +[SandboxNetworkOpts.denyOut](SandboxNetworkOpts.md#denyout) when they are defined as functions. + +## Properties + +### allTraffic + +> **allTraffic**: `string` + +All traffic sentinel — equivalent to `'0.0.0.0/0'`. + +*** + +### rules + +> **rules**: `Map`\<`string`, [`SandboxNetworkRule`](SandboxNetworkRule.md)[]\> + +Rules registered in [SandboxNetworkOpts.rules](SandboxNetworkOpts.md#rules). diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransform.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransform.md new file mode 100644 index 00000000..e97f1669 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransform.md @@ -0,0 +1,16 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkTransform + +# Type Alias: SandboxNetworkTransform + +> **SandboxNetworkTransform** = `object` + +Transform applied to egress requests matching a [SandboxNetworkRule](SandboxNetworkRule.md). + +## Properties + +### headers? + +> `optional` **headers?**: `Record`\<`string`, `string`\> + +Headers to inject into the outbound request. Values override any headers +already present on the request. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformContext.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformContext.md new file mode 100644 index 00000000..d37a1762 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformContext.md @@ -0,0 +1,33 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkTransformContext + +# Type Alias: SandboxNetworkTransformContext + +> **SandboxNetworkTransformContext** = `object` + +Context passed to a [SandboxNetworkRule](SandboxNetworkRule.md) `transform` callback. Its +values are literal placeholder strings that the egress proxy resolves per +request, so the secret itself never leaves the platform. + +## Properties + +### iam + +> **iam**: `object` + +Workload identity placeholders. + +#### tokens + +> **tokens**: `Record`\<`string`, `string`\> + +Placeholder for each workload token registered in +[SandboxOpts.iam](../interfaces/SandboxOpts.md#iam), keyed by token name. `tokens.aws` is the string +`'${agentbox.identity.tokens.aws}'`, which the egress proxy replaces with a +freshly minted token when it forwards the request. + +Reading a name that is not registered throws +InvalidArgumentError — the proxy never turns an unregistered name +into a token, so a typo would surface as a confusing auth failure at the +destination. The four names the runtime reads off any object it +serializes, awaits or coerces (`toJSON`, `then`, `toString`, `valueOf`) +throw on use rather than on the read. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformResolver.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformResolver.md new file mode 100644 index 00000000..5639f4b9 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkTransformResolver.md @@ -0,0 +1,18 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkTransformResolver + +# Type Alias: SandboxNetworkTransformResolver + +> **SandboxNetworkTransformResolver** = (`ctx`) => [`SandboxNetworkTransform`](SandboxNetworkTransform.md) + +Callback form of [SandboxNetworkRule.transform](SandboxNetworkRule.md#transform). Invoked once while the +request is being built, with a context of placeholder strings. + +## Parameters + +### ctx + +[`SandboxNetworkTransformContext`](SandboxNetworkTransformContext.md) + +## Returns + +[`SandboxNetworkTransform`](SandboxNetworkTransform.md) diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkUpdate.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkUpdate.md new file mode 100644 index 00000000..65bdb8bc --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxNetworkUpdate.md @@ -0,0 +1,45 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxNetworkUpdate + +# Type Alias: SandboxNetworkUpdate + +> **SandboxNetworkUpdate** = `object` + +Subset of [SandboxNetworkOpts](SandboxNetworkOpts.md) accepted by [SandboxApi.updateNetwork](../classes/SandboxApi.md#updatenetwork). +The update endpoint replaces all egress rules atomically — fields that are +omitted are cleared on the server. + +## Properties + +### allowInternetAccess? + +> `optional` **allowInternetAccess?**: `boolean` + +Allow sandbox to access the internet. When set to `false`, it behaves the +same as specifying `denyOut: ['0.0.0.0/0']` in the network config. + +*** + +### allowOut? + +> `optional` **allowOut?**: [`SandboxNetworkSelector`](SandboxNetworkSelector.md) + +See [SandboxNetworkOpts.allowOut](SandboxNetworkOpts.md#allowout). + +*** + +### denyOut? + +> `optional` **denyOut?**: [`SandboxNetworkSelector`](SandboxNetworkSelector.md) + +See [SandboxNetworkOpts.denyOut](SandboxNetworkOpts.md#denyout). + +*** + +### rules? + +> `optional` **rules?**: [`SandboxNetworkRules`](SandboxNetworkRules.md) + +See [SandboxNetworkOpts.rules](SandboxNetworkOpts.md#rules). A `transform` callback works here +too, but the update payload carries no `iam` config, so token names cannot +be checked against the sandbox's registered tokens — every name resolves to +its placeholder and a typo only surfaces at the destination. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxOnTimeout.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxOnTimeout.md new file mode 100644 index 00000000..1dc1f44c --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxOnTimeout.md @@ -0,0 +1,66 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxOnTimeout + +# Type Alias: SandboxOnTimeout + +> **SandboxOnTimeout** = `"pause"` \| `"kill"` \| \{ `action`: `"pause"`; `keepMemory?`: `boolean`; \} \| \{ `action`: `"kill"`; \} + +What happens when the sandbox timeout is reached. Either the bare action +(`'pause'` / `'kill'`), or an object form that also controls the pause +snapshot kind via `keepMemory`. + +The object form is a discriminated union on `action`: `keepMemory` is only +accepted alongside `action: 'pause'`. Passing `keepMemory` with +`action: 'kill'` is a compile-time type error. + +## Union Members + +`"pause"` + +*** + +`"kill"` + +*** + +### Type Literal + +\{ `action`: `"pause"`; `keepMemory?`: `boolean`; \} + +#### action + +> **action**: `"pause"` + +Auto-pause the sandbox when the timeout is reached. + +#### keepMemory? + +> `optional` **keepMemory?**: `boolean` + +Whether the timeout auto-pause keeps a full memory snapshot. + +When `false`, the auto-pause drops the in-memory state and persists only +the filesystem (a filesystem-only snapshot); resuming such a sandbox +cold-boots (reboots) it from disk, losing running processes and open +connections. + +Cannot be combined with `autoResume`: auto-resume wakes a paused sandbox +on inbound traffic by restoring its memory snapshot in place, so the +request that woke it hits an already-running process. A filesystem-only +snapshot has no memory to restore — resuming cold-boots it — so it can't +be woken transparently by traffic and must be resumed explicitly via +`connect()`. + +Left unset, the flag is omitted from the create request and the API's own +default (currently enabled) applies. + +*** + +### Type Literal + +\{ `action`: `"kill"`; \} + +#### action + +> **action**: `"kill"` + +Kill the sandbox when the timeout is reached. diff --git a/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxState.md b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxState.md new file mode 100644 index 00000000..ff4ec740 --- /dev/null +++ b/reference/sdk/javascript/sandbox/sandboxApi/type-aliases/SandboxState.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../../README.md) / [sandboxApi](../README.md) / SandboxState + +# Type Alias: SandboxState + +> **SandboxState** = `"running"` \| `"paused"` + +State of the sandbox. diff --git a/reference/sdk/javascript/templates/README.md b/reference/sdk/javascript/templates/README.md new file mode 100644 index 00000000..978affec --- /dev/null +++ b/reference/sdk/javascript/templates/README.md @@ -0,0 +1,27 @@ +# @abox-dev/sdk + +## Classes + +- [TemplateBase](classes/TemplateBase.md) + +## Interfaces + +- [TemplateBuilder](interfaces/TemplateBuilder.md) + +## Type Aliases + +- [BuildInfo](type-aliases/BuildInfo.md) +- [BuildOptions](type-aliases/BuildOptions.md) +- [BuildStatusReason](type-aliases/BuildStatusReason.md) +- [CopyItem](type-aliases/CopyItem.md) +- [GetBuildStatusOptions](type-aliases/GetBuildStatusOptions.md) +- [McpServerName](type-aliases/McpServerName.md) +- [TemplateBuildStatus](type-aliases/TemplateBuildStatus.md) +- [TemplateBuildStatusResponse](type-aliases/TemplateBuildStatusResponse.md) +- [TemplateClass](type-aliases/TemplateClass.md) +- [TemplateTag](type-aliases/TemplateTag.md) +- [TemplateTagInfo](type-aliases/TemplateTagInfo.md) + +## Variables + +- [Template](variables/Template.md) diff --git a/reference/sdk/javascript/templates/classes/TemplateBase.md b/reference/sdk/javascript/templates/classes/TemplateBase.md new file mode 100644 index 00000000..5fa512f8 --- /dev/null +++ b/reference/sdk/javascript/templates/classes/TemplateBase.md @@ -0,0 +1,1746 @@ +[@abox-dev/sdk](../README.md) / TemplateBase + +# Class: TemplateBase + +Builder for AgentBox sandbox templates, and the entrypoint for the template API. + +Exposed as [Template](../variables/Template.md), which can be called as a factory. + +## Extends + +- `ClientFactory` + +## Implements + +- `TemplateFromImage` +- [`TemplateBuilder`](../interfaces/TemplateBuilder.md) +- `TemplateFinal` + +## Constructors + +### Constructor + +> **new TemplateBase**(`options?`): `TemplateBase` + +#### Parameters + +##### options? + +`TemplateOptions` + +#### Returns + +`TemplateBase` + +#### Overrides + +`ClientFactory.constructor` + +## Methods + +### addMcpServer() + +> **addMcpServer**(`servers`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Install MCP servers using mcp-gateway. +Note: Requires a base image with mcp-gateway pre-installed (e.g., mcp-gateway). + +#### Parameters + +##### servers + +keyof McpServer \| keyof McpServer[] + +MCP server name(s) + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Throws + +If the base template is not mcp-gateway + +#### Example + +```ts +template.addMcpServer('exa') +template.addMcpServer(['brave', 'firecrawl', 'duckduckgo']) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`addMcpServer`](../interfaces/TemplateBuilder.md#addmcpserver) + +*** + +### aptInstall() + +> **aptInstall**(`packages`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Install Debian/Ubuntu packages using apt-get. + +#### Parameters + +##### packages + +`string` \| `string`[] + +Package name(s) + +##### options? + +###### fixMissing? + +`boolean` + +###### noInstallRecommends? + +`boolean` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.aptInstall('vim') +template.aptInstall(['git', 'curl', 'wget']) +template.aptInstall(['vim'], { noInstallRecommends: true }) +template.aptInstall(['vim'], { fixMissing: true }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`aptInstall`](../interfaces/TemplateBuilder.md#aptinstall) + +*** + +### betaDevContainerPrebuild() + +> **betaDevContainerPrebuild**(`devcontainerDirectory`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Prebuild a devcontainer from the specified directory. + +#### Parameters + +##### devcontainerDirectory + +`string` + +Path to the devcontainer directory + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .betaDevContainerPrebuild('/my-devcontainer') +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`betaDevContainerPrebuild`](../interfaces/TemplateBuilder.md#betadevcontainerprebuild) + +*** + +### betaSetDevContainerStart() + +> **betaSetDevContainerStart**(`devcontainerDirectory`): `TemplateFinal` + +Start a devcontainer from the specified directory. + +#### Parameters + +##### devcontainerDirectory + +`string` + +Path to the devcontainer directory + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .startDevcontainer('/my-devcontainer') + +// Prebuild and start +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .betaDevContainerPrebuild('/my-devcontainer') + // Other instructions... + .betaSetDevContainerStart('/my-devcontainer') +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`betaSetDevContainerStart`](../interfaces/TemplateBuilder.md#betasetdevcontainerstart) + +*** + +### bunInstall() + +> **bunInstall**(`packages?`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Install Bun packages using bun. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for package.json + +##### options? + +Install options + +###### dev? + +`boolean` + +###### g? + +`boolean` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.bunInstall('express') +template.bunInstall(['lodash', 'axios']) +template.bunInstall('tsx', { g: true }) +template.bunInstall('typescript', { dev: true }) +template.bunInstall() // Installs from package.json +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`bunInstall`](../interfaces/TemplateBuilder.md#buninstall) + +*** + +### copy() + +> **copy**(`src`, `dest`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Copy files or directories into the template. + +#### Parameters + +##### src + +`PathLike` \| `PathLike`[] + +Source path(s) + +##### dest + +`PathLike` + +Destination path + +##### options? + +Copy options + +###### forceUpload? + +`true` + +###### gzip? + +`boolean` + +###### mode? + +`number` + +###### resolveSymlinks? + +`boolean` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.copy('requirements.txt', '/home/user/') +template.copy(['app.ts', 'config.ts'], '/app/', { mode: 0o755 }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`copy`](../interfaces/TemplateBuilder.md#copy) + +*** + +### copyItems() + +> **copyItems**(`items`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Copy multiple items with individual options. + +#### Parameters + +##### items + +[`CopyItem`](../type-aliases/CopyItem.md)[] + +Array of copy items + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.copyItems([ + { src: 'app.ts', dest: '/app/' }, + { src: 'config.ts', dest: '/app/', mode: 0o644 } +]) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`copyItems`](../interfaces/TemplateBuilder.md#copyitems) + +*** + +### fromAlpineImage() + +> **fromAlpineImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from an Alpine-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'3.24'` + +Alpine variant (default: '3.24') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromAlpineImage('3.24') +``` + +#### Implementation of + +`TemplateFromImage.fromAlpineImage` + +*** + +### fromArchImage() + +> **fromArchImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from an Arch Linux-based Docker image. + +Defaults to `latest`: Arch is a rolling release and template provisioning +runs `pacman -Syu`, so pinning a tag would not change the built result. + +#### Parameters + +##### variant? + +`string` = `'latest'` + +Arch Linux variant (default: 'latest') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromArchImage('base-devel') +``` + +#### Implementation of + +`TemplateFromImage.fromArchImage` + +*** + +### fromAWSRegistry() + +> **fromAWSRegistry**(`image`, `credentials`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Docker image in AWS ECR. + +#### Parameters + +##### image + +`string` + +Full ECR image path + +##### credentials + +AWS credentials + +###### accessKeyId + +`string` + +###### region + +`string` + +###### secretAccessKey + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromAWSRegistry( + '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest', + { + accessKeyId: 'AKIA...', + secretAccessKey: '...', + region: 'us-west-2' + } +) +``` + +#### Implementation of + +`TemplateFromImage.fromAWSRegistry` + +*** + +### fromBaseImage() + +> **fromBaseImage**(): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from AgentBox's pinned default base image. + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromBaseImage() +``` + +#### Implementation of + +`TemplateFromImage.fromBaseImage` + +*** + +### fromBunImage() + +> **fromBunImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Bun-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'latest'` + +Bun variant (default: 'latest') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromBunImage('1.3') +``` + +#### Implementation of + +`TemplateFromImage.fromBunImage` + +*** + +### fromDebianImage() + +> **fromDebianImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Debian-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'stable'` + +Debian variant (default: 'stable') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromDebianImage('bookworm') +``` + +#### Implementation of + +`TemplateFromImage.fromDebianImage` + +*** + +### fromDockerfile() + +> **fromDockerfile**(`dockerfileContentOrPath`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Parse a Dockerfile and convert it to Template SDK format. + +#### Parameters + +##### dockerfileContentOrPath + +`string` + +Dockerfile content or path + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromDockerfile('Dockerfile') +Template().fromDockerfile('FROM python:3\nRUN pip install numpy') +``` + +#### Implementation of + +`TemplateFromImage.fromDockerfile` + +*** + +### fromFedoraImage() + +> **fromFedoraImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Fedora-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'44'` + +Fedora variant (default: '44') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromFedoraImage('44') +``` + +#### Implementation of + +`TemplateFromImage.fromFedoraImage` + +*** + +### fromGCPRegistry() + +> **fromGCPRegistry**(`image`, `credentials`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Docker image in Google Container Registry. + +#### Parameters + +##### image + +`string` + +Full GCR/GAR image path + +##### credentials + +GCP service account credentials + +###### serviceAccountJSON + +`string` \| `object` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromGCPRegistry( + 'gcr.io/myproject/myimage:latest', + { serviceAccountJSON: 'path/to/service-account.json' } +) +``` + +#### Implementation of + +`TemplateFromImage.fromGCPRegistry` + +*** + +### fromImage() + +> **fromImage**(`baseImage`, `credentials?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a custom Docker image. + +#### Parameters + +##### baseImage + +`string` + +Docker image name + +##### credentials? + +Optional credentials for private registries + +###### password + +`string` + +###### username + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromImage('python:3') + +// With credentials (optional) +Template().fromImage('myregistry.com/myimage:latest', { + username: 'user', + password: 'pass' +}) +``` + +#### Implementation of + +`TemplateFromImage.fromImage` + +*** + +### fromNodeImage() + +> **fromNodeImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Node.js-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'lts'` + +Node.js variant (default: 'lts') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromNodeImage('24') +``` + +#### Implementation of + +`TemplateFromImage.fromNodeImage` + +*** + +### fromPythonImage() + +> **fromPythonImage**(`version?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from a Python-based Docker image. + +#### Parameters + +##### version? + +`string` = `'3'` + +Python version (default: '3') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromPythonImage('3') +``` + +#### Implementation of + +`TemplateFromImage.fromPythonImage` + +*** + +### fromTemplate() + +> **fromTemplate**(`template`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from an existing AgentBox template. + +#### Parameters + +##### template + +`string` + +AgentBox template ID or alias + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromTemplate('my-base-template') +``` + +#### Implementation of + +`TemplateFromImage.fromTemplate` + +*** + +### fromUbuntuImage() + +> **fromUbuntuImage**(`variant?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Start from an Ubuntu-based Docker image. + +#### Parameters + +##### variant? + +`string` = `'latest'` + +Ubuntu variant (default: 'latest') + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +Template().fromUbuntuImage('24.04') +``` + +#### Implementation of + +`TemplateFromImage.fromUbuntuImage` + +*** + +### gitClone() + +> **gitClone**(`url`, `path?`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Clone a Git repository. + +#### Parameters + +##### url + +`string` + +Repository URL + +##### path? + +`PathLike` + +Optional destination path + +##### options? + +Clone options + +###### branch? + +`string` + +###### depth? + +`number` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.gitClone('https://github.com/user/repo.git', '/app/repo') +template.gitClone('https://github.com/user/repo.git', undefined, { + branch: 'main', + depth: 1 +}) +template.gitClone('https://github.com/user/repo.git', '/app/repo', { + user: 'root' +}) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`gitClone`](../interfaces/TemplateBuilder.md#gitclone) + +*** + +### makeDir() + +> **makeDir**(`path`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Create directories. + +#### Parameters + +##### path + +`PathLike` \| `PathLike`[] + +Directory path(s) + +##### options? + +Directory options + +###### mode? + +`number` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.makeDir('/app/data', { mode: 0o755 }) +template.makeDir(['/app/logs', '/app/cache']) +template.makeDir('/app/data', { mode: 0o755, user: 'root' }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`makeDir`](../interfaces/TemplateBuilder.md#makedir) + +*** + +### makeSymlink() + +> **makeSymlink**(`src`, `dest`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Create a symbolic link. + +#### Parameters + +##### src + +`PathLike` + +Source path (target) + +##### dest + +`PathLike` + +Destination path (symlink location) + +##### options? + +Symlink options + +###### force? + +`boolean` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.makeSymlink('/usr/bin/python3', '/usr/bin/python') +template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { user: 'root' }) +template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { force: true }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`makeSymlink`](../interfaces/TemplateBuilder.md#makesymlink) + +*** + +### npmInstall() + +> **npmInstall**(`packages?`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Install Node.js packages using npm. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for package.json + +##### options? + +Install options + +###### dev? + +`boolean` + +###### g? + +`boolean` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.npmInstall('express') +template.npmInstall(['lodash', 'axios']) +template.npmInstall('tsx', { g: true }) +template.npmInstall('typescript', { dev: true }) +template.npmInstall() // Installs from package.json +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`npmInstall`](../interfaces/TemplateBuilder.md#npminstall) + +*** + +### pipInstall() + +> **pipInstall**(`packages?`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Install Python packages using pip. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for current directory + +##### options? + +Install options + +###### g? + +`boolean` + +Install globally as root (default: true). Set to false for user-only installation with --user flag + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.pipInstall('numpy') // Installs globally (default) +template.pipInstall(['pandas', 'scikit-learn']) +template.pipInstall('numpy', { g: false }) // Install for user only +template.pipInstall() // Installs from current directory +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`pipInstall`](../interfaces/TemplateBuilder.md#pipinstall) + +*** + +### remove() + +> **remove**(`path`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Remove files or directories. + +#### Parameters + +##### path + +`PathLike` \| `PathLike`[] + +Path(s) to remove + +##### options? + +Remove options + +###### force? + +`boolean` + +###### recursive? + +`boolean` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.remove('/tmp/cache', { recursive: true, force: true }) +template.remove('/tmp/cache', { recursive: true, force: true, user: 'root' }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`remove`](../interfaces/TemplateBuilder.md#remove) + +*** + +### rename() + +> **rename**(`src`, `dest`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Rename or move a file or directory. + +#### Parameters + +##### src + +`PathLike` + +Source path + +##### dest + +`PathLike` + +Destination path + +##### options? + +Rename options + +###### force? + +`boolean` + +###### user? + +`string` + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.rename('/tmp/old.txt', '/tmp/new.txt') +template.rename('/tmp/old.txt', '/tmp/new.txt', { user: 'root' }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`rename`](../interfaces/TemplateBuilder.md#rename) + +*** + +### runCmd() + +#### Call Signature + +> **runCmd**(`command`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Run a shell command. + +##### Parameters + +###### command + +`string` + +Command string + +###### options? + +Command options + +###### user? + +`string` + +##### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +##### Example + +```ts +template.runCmd('apt-get update') +template.runCmd(['pip install numpy', 'pip install pandas']) +template.runCmd('apt-get install vim', { user: 'root' }) +``` + +##### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`runCmd`](../interfaces/TemplateBuilder.md#runcmd) + +#### Call Signature + +> **runCmd**(`commands`, `options?`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Run multiple shell commands. + +##### Parameters + +###### commands + +`string`[] + +Array of command strings + +###### options? + +Command options + +###### user? + +`string` + +##### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +##### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`runCmd`](../interfaces/TemplateBuilder.md#runcmd) + +*** + +### setEnvs() + +> **setEnvs**(`envs`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Set environment variables. +Note: Environment variables defined here are available only during template build. + +#### Parameters + +##### envs + +`Record`\<`string`, `string`\> + +Environment variables + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.setEnvs({ NODE_ENV: 'production', PORT: '8080' }) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`setEnvs`](../interfaces/TemplateBuilder.md#setenvs) + +*** + +### setReadyCmd() + +> **setReadyCmd**(`readyCommand`): `TemplateFinal` + +Set or update the ready check command. + +#### Parameters + +##### readyCommand + +`string` \| `ReadyCmd` + +Command to check readiness + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +// Using a string command +template.setReadyCmd('curl http://localhost:8000/health') + +// Using ReadyCmd helpers +import { waitForPort, waitForFile, waitForProcess } from '@abox-dev/sdk' + +template.setReadyCmd(waitForPort(3000)) + +template.setReadyCmd(waitForFile('/tmp/ready')) + +template.setReadyCmd(waitForProcess('nginx')) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`setReadyCmd`](../interfaces/TemplateBuilder.md#setreadycmd) + +*** + +### setStartCmd() + +> **setStartCmd**(`startCommand`, `readyCommand`): `TemplateFinal` + +Set the start command and ready check. + +#### Parameters + +##### startCommand + +`string` + +Command to run on startup + +##### readyCommand + +`string` \| `ReadyCmd` + +Command to check readiness + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +// Using a string command +template.setStartCmd( + 'node app.js', + 'curl http://localhost:8000/health' +) + +// Using ReadyCmd helpers +import { waitForPort, waitForURL } from '@abox-dev/sdk' + +template.setStartCmd( + 'python -m http.server 8000', + waitForPort(8000) +) + +template.setStartCmd( + 'npm start', + waitForURL('http://localhost:3000/health', 200) +) +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`setStartCmd`](../interfaces/TemplateBuilder.md#setstartcmd) + +*** + +### setUser() + +> **setUser**(`user`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Set the user for subsequent commands. + +#### Parameters + +##### user + +`string` + +Username + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.setUser('root') +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`setUser`](../interfaces/TemplateBuilder.md#setuser) + +*** + +### setWorkdir() + +> **setWorkdir**(`workdir`): [`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +Set the working directory. + +#### Parameters + +##### workdir + +`PathLike` + +Working directory path + +#### Returns + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md) + +#### Example + +```ts +template.setWorkdir('/app') +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`setWorkdir`](../interfaces/TemplateBuilder.md#setworkdir) + +*** + +### skipCache() + +> **skipCache**(): `this` + +Skip cache for all subsequent build instructions from this point. + +#### Returns + +`this` + +#### Example + +```ts +Template().skipCache().fromPythonImage('3') +``` + +#### Implementation of + +[`TemplateBuilder`](../interfaces/TemplateBuilder.md).[`skipCache`](../interfaces/TemplateBuilder.md#skipcache) + +*** + +### assignTags() + +> `static` **assignTags**(`targetName`, `tags`, `options?`): `Promise`\<[`TemplateTagInfo`](../type-aliases/TemplateTagInfo.md)\> + +Assign tag(s) to an existing template build. + +#### Parameters + +##### targetName + +`string` + +Template name in 'name:tag' format (the source build to tag from) + +##### tags + +`string` \| `string`[] + +Tag or tags to assign + +##### options? + +`ConnectionOpts` + +Authentication options + +#### Returns + +`Promise`\<[`TemplateTagInfo`](../type-aliases/TemplateTagInfo.md)\> + +Tag info with buildId and assigned tags + +#### Example + +```ts +// Assign a single tag +await Template.assignTags('my-template:v1.0', 'production') + +// Assign multiple tags +await Template.assignTags('my-template:v1.0', ['production', 'stable']) +``` + +*** + +### build() + +> `static` **build**(`template`, `name`, `options?`): `Promise`\<[`BuildInfo`](../type-aliases/BuildInfo.md)\> + +Build and deploy a template to AgentBox infrastructure. + +#### Parameters + +##### template + +[`TemplateClass`](../type-aliases/TemplateClass.md) + +The template to build + +##### name + +`string` + +Template name in 'name' or 'name:tag' format + +##### options? + +[`BuildOptions`](../type-aliases/BuildOptions.md) + +Optional build configuration options + +#### Returns + +`Promise`\<[`BuildInfo`](../type-aliases/BuildInfo.md)\> + +#### Example + +```ts +const template = Template().fromPythonImage('3') + +// Build with single tag in name +await Template.build(template, 'my-python-env:v1.0') + +// Build with multiple tags +await Template.build(template, 'my-python-env', { tags: ['v1.0', 'stable'] }) +``` + +*** + +### buildInBackground() + +> `static` **buildInBackground**(`template`, `name`, `options?`): `Promise`\<[`BuildInfo`](../type-aliases/BuildInfo.md)\> + +Build and deploy a template to AgentBox infrastructure without waiting for completion. + +#### Parameters + +##### template + +[`TemplateClass`](../type-aliases/TemplateClass.md) + +The template to build + +##### name + +`string` + +Template name in 'name' or 'name:tag' format + +##### options? + +[`BuildOptions`](../type-aliases/BuildOptions.md) + +Optional build configuration options + +#### Returns + +`Promise`\<[`BuildInfo`](../type-aliases/BuildInfo.md)\> + +#### Example + +```ts +const template = Template().fromPythonImage('3') + +// Build with single tag in name +const data = await Template.buildInBackground(template, 'my-python-env:v1.0') + +// Build with multiple tags +const data = await Template.buildInBackground(template, 'my-python-env', { tags: ['v1.0', 'stable'] }) +``` + +*** + +### exists() + +> `static` **exists**(`name`, `options?`): `Promise`\<`boolean`\> + +Check if a template with the given name exists. + +#### Parameters + +##### name + +`string` + +Template name to check + +##### options? + +`ConnectionOpts` + +Authentication options + +#### Returns + +`Promise`\<`boolean`\> + +True if the name exists, false otherwise + +#### Example + +```ts +const exists = await Template.exists('my-python-env') +if (exists) { + console.log('Template exists!') +} +``` + +*** + +### getBuildStatus() + +> `static` **getBuildStatus**(`data`, `options?`): `Promise`\<[`TemplateBuildStatusResponse`](../type-aliases/TemplateBuildStatusResponse.md)\> + +Get the status of a build. + +#### Parameters + +##### data + +`Pick`\<[`BuildInfo`](../type-aliases/BuildInfo.md), `"templateId"` \| `"buildId"`\> + +Build identifiers + +##### options? + +[`GetBuildStatusOptions`](../type-aliases/GetBuildStatusOptions.md) + +Authentication options + +#### Returns + +`Promise`\<[`TemplateBuildStatusResponse`](../type-aliases/TemplateBuildStatusResponse.md)\> + +#### Example + +```ts +const status = await Template.getBuildStatus(data, { logsOffset: 0 }) +``` + +*** + +### getTags() + +> `static` **getTags**(`templateId`, `options?`): `Promise`\<[`TemplateTag`](../type-aliases/TemplateTag.md)[]\> + +Get all tags for a template. + +#### Parameters + +##### templateId + +`string` + +Template ID or name + +##### options? + +`ConnectionOpts` + +Authentication options + +#### Returns + +`Promise`\<[`TemplateTag`](../type-aliases/TemplateTag.md)[]\> + +Array of tag details including tag name, buildId, and creation date + +#### Example + +```ts +const tags = await Template.getTags('my-template') +for (const tag of tags) { + console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`) +} +``` + +*** + +### removeTags() + +> `static` **removeTags**(`name`, `tags`, `options?`): `Promise`\<`void`\> + +Remove tag(s) from a template. + +#### Parameters + +##### name + +`string` + +Template name + +##### tags + +`string` \| `string`[] + +Tag or tags to remove + +##### options? + +`ConnectionOpts` + +Authentication options + +#### Returns + +`Promise`\<`void`\> + +#### Example + +```ts +// Remove a single tag +await Template.removeTags('my-template', 'production') + +// Remove multiple tags from a template +await Template.removeTags('my-template', ['production', 'staging']) +``` + +*** + +### toDockerfile() + +> `static` **toDockerfile**(`template`): `string` + +Convert a template to Dockerfile format. +Note: Templates based on other AgentBox templates cannot be converted to Dockerfile. + +#### Parameters + +##### template + +[`TemplateClass`](../type-aliases/TemplateClass.md) + +The template to convert + +#### Returns + +`string` + +Dockerfile string representation + +#### Throws + +Error if the template is based on another AgentBox template + +*** + +### toJSON() + +> `static` **toJSON**(`template`, `computeHashes?`): `Promise`\<`string`\> + +Convert a template to JSON representation. + +#### Parameters + +##### template + +[`TemplateClass`](../type-aliases/TemplateClass.md) + +The template to convert + +##### computeHashes? + +`boolean` = `true` + +Whether to compute file hashes for cache invalidation + +#### Returns + +`Promise`\<`string`\> + +JSON string representation of the template diff --git a/reference/sdk/javascript/templates/interfaces/TemplateBuilder.md b/reference/sdk/javascript/templates/interfaces/TemplateBuilder.md new file mode 100644 index 00000000..930f3b9d --- /dev/null +++ b/reference/sdk/javascript/templates/interfaces/TemplateBuilder.md @@ -0,0 +1,850 @@ +[@abox-dev/sdk](../README.md) / TemplateBuilder + +# Interface: TemplateBuilder + +Main builder state for constructing templates. +Provides methods for customizing the template environment. + +## Methods + +### addMcpServer() + +> **addMcpServer**(`servers`): `TemplateBuilder` + +Install MCP servers using mcp-gateway. +Note: Requires a base image with mcp-gateway pre-installed (e.g., mcp-gateway). + +#### Parameters + +##### servers + +keyof McpServer \| keyof McpServer[] + +MCP server name(s) + +#### Returns + +`TemplateBuilder` + +#### Throws + +If the base template is not mcp-gateway + +#### Example + +```ts +template.addMcpServer('exa') +template.addMcpServer(['brave', 'firecrawl', 'duckduckgo']) +``` + +*** + +### aptInstall() + +> **aptInstall**(`packages`, `options?`): `TemplateBuilder` + +Install Debian/Ubuntu packages using apt-get. + +#### Parameters + +##### packages + +`string` \| `string`[] + +Package name(s) + +##### options? + +###### fixMissing? + +`boolean` + +###### noInstallRecommends? + +`boolean` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.aptInstall('vim') +template.aptInstall(['git', 'curl', 'wget']) +template.aptInstall(['vim'], { noInstallRecommends: true }) +template.aptInstall(['vim'], { fixMissing: true }) +``` + +*** + +### betaDevContainerPrebuild() + +> **betaDevContainerPrebuild**(`devcontainerDirectory`): `TemplateBuilder` + +Prebuild a devcontainer from the specified directory. + +#### Parameters + +##### devcontainerDirectory + +`string` + +Path to the devcontainer directory + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .betaDevContainerPrebuild('/my-devcontainer') +``` + +*** + +### betaSetDevContainerStart() + +> **betaSetDevContainerStart**(`devcontainerDirectory`): `TemplateFinal` + +Start a devcontainer from the specified directory. + +#### Parameters + +##### devcontainerDirectory + +`string` + +Path to the devcontainer directory + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .startDevcontainer('/my-devcontainer') + +// Prebuild and start +template + .gitClone('https://myrepo.com/project.git', '/my-devcontainer') + .betaDevContainerPrebuild('/my-devcontainer') + // Other instructions... + .betaSetDevContainerStart('/my-devcontainer') +``` + +*** + +### bunInstall() + +> **bunInstall**(`packages?`, `options?`): `TemplateBuilder` + +Install Bun packages using bun. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for package.json + +##### options? + +Install options + +###### dev? + +`boolean` + +###### g? + +`boolean` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.bunInstall('express') +template.bunInstall(['lodash', 'axios']) +template.bunInstall('tsx', { g: true }) +template.bunInstall('typescript', { dev: true }) +template.bunInstall() // Installs from package.json +``` + +*** + +### copy() + +> **copy**(`src`, `dest`, `options?`): `TemplateBuilder` + +Copy files or directories into the template. + +#### Parameters + +##### src + +`PathLike` \| `PathLike`[] + +Source path(s) + +##### dest + +`PathLike` + +Destination path + +##### options? + +Copy options + +###### forceUpload? + +`true` + +###### gzip? + +`boolean` + +###### mode? + +`number` + +###### resolveSymlinks? + +`boolean` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.copy('requirements.txt', '/home/user/') +template.copy(['app.ts', 'config.ts'], '/app/', { mode: 0o755 }) +``` + +*** + +### copyItems() + +> **copyItems**(`items`): `TemplateBuilder` + +Copy multiple items with individual options. + +#### Parameters + +##### items + +[`CopyItem`](../type-aliases/CopyItem.md)[] + +Array of copy items + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.copyItems([ + { src: 'app.ts', dest: '/app/' }, + { src: 'config.ts', dest: '/app/', mode: 0o644 } +]) +``` + +*** + +### gitClone() + +> **gitClone**(`url`, `path?`, `options?`): `TemplateBuilder` + +Clone a Git repository. + +#### Parameters + +##### url + +`string` + +Repository URL + +##### path? + +`PathLike` + +Optional destination path + +##### options? + +Clone options + +###### branch? + +`string` + +###### depth? + +`number` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.gitClone('https://github.com/user/repo.git', '/app/repo') +template.gitClone('https://github.com/user/repo.git', undefined, { + branch: 'main', + depth: 1 +}) +template.gitClone('https://github.com/user/repo.git', '/app/repo', { + user: 'root' +}) +``` + +*** + +### makeDir() + +> **makeDir**(`path`, `options?`): `TemplateBuilder` + +Create directories. + +#### Parameters + +##### path + +`PathLike` \| `PathLike`[] + +Directory path(s) + +##### options? + +Directory options + +###### mode? + +`number` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.makeDir('/app/data', { mode: 0o755 }) +template.makeDir(['/app/logs', '/app/cache']) +template.makeDir('/app/data', { mode: 0o755, user: 'root' }) +``` + +*** + +### makeSymlink() + +> **makeSymlink**(`src`, `dest`, `options?`): `TemplateBuilder` + +Create a symbolic link. + +#### Parameters + +##### src + +`PathLike` + +Source path (target) + +##### dest + +`PathLike` + +Destination path (symlink location) + +##### options? + +Symlink options + +###### force? + +`boolean` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.makeSymlink('/usr/bin/python3', '/usr/bin/python') +template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { user: 'root' }) +template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { force: true }) +``` + +*** + +### npmInstall() + +> **npmInstall**(`packages?`, `options?`): `TemplateBuilder` + +Install Node.js packages using npm. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for package.json + +##### options? + +Install options + +###### dev? + +`boolean` + +###### g? + +`boolean` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.npmInstall('express') +template.npmInstall(['lodash', 'axios']) +template.npmInstall('tsx', { g: true }) +template.npmInstall('typescript', { dev: true }) +template.npmInstall() // Installs from package.json +``` + +*** + +### pipInstall() + +> **pipInstall**(`packages?`, `options?`): `TemplateBuilder` + +Install Python packages using pip. + +#### Parameters + +##### packages? + +`string` \| `string`[] + +Package name(s) or undefined for current directory + +##### options? + +Install options + +###### g? + +`boolean` + +Install globally as root (default: true). Set to false for user-only installation with --user flag + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.pipInstall('numpy') // Installs globally (default) +template.pipInstall(['pandas', 'scikit-learn']) +template.pipInstall('numpy', { g: false }) // Install for user only +template.pipInstall() // Installs from current directory +``` + +*** + +### remove() + +> **remove**(`path`, `options?`): `TemplateBuilder` + +Remove files or directories. + +#### Parameters + +##### path + +`PathLike` \| `PathLike`[] + +Path(s) to remove + +##### options? + +Remove options + +###### force? + +`boolean` + +###### recursive? + +`boolean` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.remove('/tmp/cache', { recursive: true, force: true }) +template.remove('/tmp/cache', { recursive: true, force: true, user: 'root' }) +``` + +*** + +### rename() + +> **rename**(`src`, `dest`, `options?`): `TemplateBuilder` + +Rename or move a file or directory. + +#### Parameters + +##### src + +`PathLike` + +Source path + +##### dest + +`PathLike` + +Destination path + +##### options? + +Rename options + +###### force? + +`boolean` + +###### user? + +`string` + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.rename('/tmp/old.txt', '/tmp/new.txt') +template.rename('/tmp/old.txt', '/tmp/new.txt', { user: 'root' }) +``` + +*** + +### runCmd() + +#### Call Signature + +> **runCmd**(`command`, `options?`): `TemplateBuilder` + +Run a shell command. + +##### Parameters + +###### command + +`string` + +Command string + +###### options? + +Command options + +###### user? + +`string` + +##### Returns + +`TemplateBuilder` + +##### Example + +```ts +template.runCmd('apt-get update') +template.runCmd(['pip install numpy', 'pip install pandas']) +template.runCmd('apt-get install vim', { user: 'root' }) +``` + +#### Call Signature + +> **runCmd**(`commands`, `options?`): `TemplateBuilder` + +Run multiple shell commands. + +##### Parameters + +###### commands + +`string`[] + +Array of command strings + +###### options? + +Command options + +###### user? + +`string` + +##### Returns + +`TemplateBuilder` + +#### Call Signature + +> **runCmd**(`commandOrCommands`, `options?`): `TemplateBuilder` + +Run command(s). + +##### Parameters + +###### commandOrCommands + +`string` \| `string`[] + +Command or commands + +###### options? + +Command options + +###### user? + +`string` + +##### Returns + +`TemplateBuilder` + +*** + +### setEnvs() + +> **setEnvs**(`envs`): `TemplateBuilder` + +Set environment variables. +Note: Environment variables defined here are available only during template build. + +#### Parameters + +##### envs + +`Record`\<`string`, `string`\> + +Environment variables + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.setEnvs({ NODE_ENV: 'production', PORT: '8080' }) +``` + +*** + +### setReadyCmd() + +> **setReadyCmd**(`readyCommand`): `TemplateFinal` + +Set or update the ready check command. + +#### Parameters + +##### readyCommand + +`string` \| `ReadyCmd` + +Command to check readiness + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +// Using a string command +template.setReadyCmd('curl http://localhost:8000/health') + +// Using ReadyCmd helpers +import { waitForPort, waitForFile, waitForProcess } from '@abox-dev/sdk' + +template.setReadyCmd(waitForPort(3000)) + +template.setReadyCmd(waitForFile('/tmp/ready')) + +template.setReadyCmd(waitForProcess('nginx')) +``` + +*** + +### setStartCmd() + +> **setStartCmd**(`startCommand`, `readyCommand`): `TemplateFinal` + +Set the start command and ready check. + +#### Parameters + +##### startCommand + +`string` + +Command to run on startup + +##### readyCommand + +`string` \| `ReadyCmd` + +Command to check readiness + +#### Returns + +`TemplateFinal` + +#### Example + +```ts +// Using a string command +template.setStartCmd( + 'node app.js', + 'curl http://localhost:8000/health' +) + +// Using ReadyCmd helpers +import { waitForPort, waitForURL } from '@abox-dev/sdk' + +template.setStartCmd( + 'python -m http.server 8000', + waitForPort(8000) +) + +template.setStartCmd( + 'npm start', + waitForURL('http://localhost:3000/health', 200) +) +``` + +*** + +### setUser() + +> **setUser**(`user`): `TemplateBuilder` + +Set the user for subsequent commands. + +#### Parameters + +##### user + +`string` + +Username + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.setUser('root') +``` + +*** + +### setWorkdir() + +> **setWorkdir**(`workdir`): `TemplateBuilder` + +Set the working directory. + +#### Parameters + +##### workdir + +`PathLike` + +Working directory path + +#### Returns + +`TemplateBuilder` + +#### Example + +```ts +template.setWorkdir('/app') +``` + +*** + +### skipCache() + +> **skipCache**(): `this` + +Skip cache for all subsequent build instructions from this point. + +#### Returns + +`this` + +#### Example + +```ts +template.skipCache().runCmd('apt-get update') +``` diff --git a/reference/sdk/javascript/templates/type-aliases/BuildInfo.md b/reference/sdk/javascript/templates/type-aliases/BuildInfo.md new file mode 100644 index 00000000..9005f935 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/BuildInfo.md @@ -0,0 +1,39 @@ +[@abox-dev/sdk](../README.md) / BuildInfo + +# Type Alias: BuildInfo + +> **BuildInfo** = `object` + +Information about a built template. + +## Properties + +### buildId + +> **buildId**: `string` + +Build identifier. + +*** + +### name + +> **name**: `string` + +Name of the template. + +*** + +### tags + +> **tags**: `string`[] + +Tags assigned to this build. + +*** + +### templateId + +> **templateId**: `string` + +Template identifier. diff --git a/reference/sdk/javascript/templates/type-aliases/BuildOptions.md b/reference/sdk/javascript/templates/type-aliases/BuildOptions.md new file mode 100644 index 00000000..71082e59 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/BuildOptions.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / BuildOptions + +# Type Alias: BuildOptions + +> **BuildOptions** = `ConnectionOpts` & `BasicBuildOptions` + +Options for building a template with authentication. diff --git a/reference/sdk/javascript/templates/type-aliases/BuildStatusReason.md b/reference/sdk/javascript/templates/type-aliases/BuildStatusReason.md new file mode 100644 index 00000000..dfec550e --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/BuildStatusReason.md @@ -0,0 +1,31 @@ +[@abox-dev/sdk](../README.md) / BuildStatusReason + +# Type Alias: BuildStatusReason + +> **BuildStatusReason** = `object` + +Reason for the current build status (typically for errors). + +## Properties + +### logEntries + +> **logEntries**: `LogEntry`[] + +Log entries related to the status reason. + +*** + +### message + +> **message**: `string` + +Message with the status reason. + +*** + +### step? + +> `optional` **step?**: `string` + +Step that failed. diff --git a/reference/sdk/javascript/templates/type-aliases/CopyItem.md b/reference/sdk/javascript/templates/type-aliases/CopyItem.md new file mode 100644 index 00000000..30acf148 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/CopyItem.md @@ -0,0 +1,49 @@ +[@abox-dev/sdk](../README.md) / CopyItem + +# Type Alias: CopyItem + +> **CopyItem** = `object` + +Configuration for a single file/directory copy operation. + +## Properties + +### dest + +> **dest**: `PathLike` + +*** + +### forceUpload? + +> `optional` **forceUpload?**: `true` + +*** + +### gzip? + +> `optional` **gzip?**: `boolean` + +*** + +### mode? + +> `optional` **mode?**: `number` + +*** + +### resolveSymlinks? + +> `optional` **resolveSymlinks?**: `boolean` + +*** + +### src + +> **src**: `PathLike` \| `PathLike`[] + +*** + +### user? + +> `optional` **user?**: `string` diff --git a/reference/sdk/javascript/templates/type-aliases/GetBuildStatusOptions.md b/reference/sdk/javascript/templates/type-aliases/GetBuildStatusOptions.md new file mode 100644 index 00000000..9735a343 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/GetBuildStatusOptions.md @@ -0,0 +1,13 @@ +[@abox-dev/sdk](../README.md) / GetBuildStatusOptions + +# Type Alias: GetBuildStatusOptions + +> **GetBuildStatusOptions** = `ConnectionOpts` & `object` + +Options for getting build status. + +## Type Declaration + +### logsOffset? + +> `optional` **logsOffset?**: `number` diff --git a/reference/sdk/javascript/templates/type-aliases/McpServerName.md b/reference/sdk/javascript/templates/type-aliases/McpServerName.md new file mode 100644 index 00000000..63d4df08 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/McpServerName.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / McpServerName + +# Type Alias: McpServerName + +> **McpServerName** = keyof `McpServer` + +MCP server names that can be installed. diff --git a/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatus.md b/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatus.md new file mode 100644 index 00000000..a4e62a35 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatus.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / TemplateBuildStatus + +# Type Alias: TemplateBuildStatus + +> **TemplateBuildStatus** = `"building"` \| `"waiting"` \| `"ready"` \| `"error"` + +Status of a template build. diff --git a/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatusResponse.md b/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatusResponse.md new file mode 100644 index 00000000..23a04de6 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/TemplateBuildStatusResponse.md @@ -0,0 +1,47 @@ +[@abox-dev/sdk](../README.md) / TemplateBuildStatusResponse + +# Type Alias: TemplateBuildStatusResponse + +> **TemplateBuildStatusResponse** = `object` + +Response from getting build status. + +## Properties + +### buildID + +> **buildID**: `string` + +Build identifier. + +*** + +### logEntries + +> **logEntries**: `LogEntry`[] + +Build log entries. + +*** + +### reason? + +> `optional` **reason?**: [`BuildStatusReason`](BuildStatusReason.md) + +Reason for the current status (typically for errors). + +*** + +### status + +> **status**: [`TemplateBuildStatus`](TemplateBuildStatus.md) + +Current status of the build. + +*** + +### templateID + +> **templateID**: `string` + +Template identifier. diff --git a/reference/sdk/javascript/templates/type-aliases/TemplateClass.md b/reference/sdk/javascript/templates/type-aliases/TemplateClass.md new file mode 100644 index 00000000..2fedcda3 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/TemplateClass.md @@ -0,0 +1,7 @@ +[@abox-dev/sdk](../README.md) / TemplateClass + +# Type Alias: TemplateClass + +> **TemplateClass** = [`TemplateBuilder`](../interfaces/TemplateBuilder.md) \| `TemplateFinal` + +Type representing a template in any state (builder or final). diff --git a/reference/sdk/javascript/templates/type-aliases/TemplateTag.md b/reference/sdk/javascript/templates/type-aliases/TemplateTag.md new file mode 100644 index 00000000..4907f1bd --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/TemplateTag.md @@ -0,0 +1,31 @@ +[@abox-dev/sdk](../README.md) / TemplateTag + +# Type Alias: TemplateTag + +> **TemplateTag** = `object` + +Detailed information about a single template tag. + +## Properties + +### buildId + +> **buildId**: `string` + +Build identifier associated with this tag. + +*** + +### createdAt + +> **createdAt**: `Date` + +When this tag was assigned. + +*** + +### tag + +> **tag**: `string` + +Name of the tag. diff --git a/reference/sdk/javascript/templates/type-aliases/TemplateTagInfo.md b/reference/sdk/javascript/templates/type-aliases/TemplateTagInfo.md new file mode 100644 index 00000000..b87e3465 --- /dev/null +++ b/reference/sdk/javascript/templates/type-aliases/TemplateTagInfo.md @@ -0,0 +1,23 @@ +[@abox-dev/sdk](../README.md) / TemplateTagInfo + +# Type Alias: TemplateTagInfo + +> **TemplateTagInfo** = `object` + +Information about assigned template tags. + +## Properties + +### buildId + +> **buildId**: `string` + +Build identifier associated with this tag. + +*** + +### tags + +> **tags**: `string`[] + +Assigned tags of the template. diff --git a/reference/sdk/javascript/templates/variables/Template.md b/reference/sdk/javascript/templates/variables/Template.md new file mode 100644 index 00000000..13f29856 --- /dev/null +++ b/reference/sdk/javascript/templates/variables/Template.md @@ -0,0 +1,36 @@ +[@abox-dev/sdk](../README.md) / Template + +# Variable: Template + +> `const` **Template**: `CallableTemplate`\<*typeof* [`TemplateBase`](../classes/TemplateBase.md)\> + +Builder and API entrypoint for AgentBox sandbox templates. + +`Template` is the [TemplateBase](../classes/TemplateBase.md) class, wrapped so it can also be +called as a factory returning a builder. The statics (`Template.build`, +`Template.exists`, …) resolve their connection options off the class they are +called on — so a subclass can bind its own defaults. + +## Param + +**options** + +Optional builder options, e.g. the file context path used to + resolve relative paths passed to `copy` + +## Returns + +A template builder + +## Example + +```ts +import { Template } from '@abox-dev/sdk' + +const template = Template() + .fromPythonImage('3') + .copy('requirements.txt', '/app/') + .pipInstall() + +await Template.build(template, 'my-python-app:v1.0') +``` diff --git a/reference/sdk/python/code-interpreter-async.md b/reference/sdk/python/code-interpreter-async.md new file mode 100644 index 00000000..40e8734c --- /dev/null +++ b/reference/sdk/python/code-interpreter-async.md @@ -0,0 +1,421 @@ +## `agentbox_code_interpreter.code_interpreter_async` + +**Classes:** + +- [**AsyncSandbox**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox) – AgentBox cloud sandbox is a secure and isolated cloud environment. + +**Attributes:** + +- [**logger**](#agentbox_code_interpreter.code_interpreter_async.logger) – + +### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox` + +Bases: [AsyncSandbox](#agentbox.AsyncSandbox) + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/). + +Use the `AsyncSandbox.create()` to create a new sandbox. + +Example: +```python +from agentbox_code_interpreter import AsyncSandbox +sandbox = await AsyncSandbox.create() +``` + +**Functions:** + +- [**connect**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.connect) – Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +- [**create**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create) – Create a new sandbox. +- [**create_code_context**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create_code_context) – Creates a new context to run code in. +- [**create_snapshot**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create_snapshot) – Create a snapshot of the sandbox's current state. +- [**delete_snapshot**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.delete_snapshot) – Delete a snapshot. +- [**fork**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.fork) – Fork the sandbox. +- [**get_info**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_info) – Get sandbox information like sandbox ID, template, metadata, started at/end at date. +- [**get_mcp_token**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_mcp_token) – Get the MCP token for the sandbox. +- [**get_metrics**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_metrics) – Get the metrics of the current sandbox. +- [**is_running**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.is_running) – Check if the sandbox is running. +- [**kill**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.kill) – Kill the sandbox specified by sandbox ID. +- [**list**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list) – List sandboxes. +- [**list_code_contexts**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list_code_contexts) – List all contexts. +- [**list_snapshots**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list_snapshots) – List snapshots for this sandbox. +- [**pause**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.pause) – Pause the sandbox. +- [**remove_code_context**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.remove_code_context) – Removes a context. +- [**restart_code_context**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.restart_code_context) – Restart a context. +- [**run_code**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.run_code) – +- [**set_timeout**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.set_timeout) – Set the timeout of the specified sandbox. +- [**update_network**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.update_network) – Update the network configuration of the sandbox. + +**Attributes:** + +- [**commands**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.commands) ([Commands](#agentbox.sandbox_async.commands.command.Commands)) – Module for running commands in the sandbox. +- [**default_template**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.default_template) – +- [**files**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.files) ([Filesystem](#agentbox.sandbox_async.filesystem.filesystem.Filesystem)) – Module for interacting with the sandbox filesystem. +- [**pty**](#agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.pty) ([Pty](#agentbox.sandbox_async.commands.pty.Pty)) – Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.commands` + +```python +commands: Commands +``` + +Module for running commands in the sandbox. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.connect` + +```python +connect(timeout=None, **opts) +``` + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +:param timeout: Timeout for the sandbox in **seconds** + For running sandboxes, the timeout will update only if the new timeout is longer than the existing one. +:return: A running sandbox instance + +@example +```python +sandbox = await AsyncSandbox.create() +await sandbox.pause() + +# Another code block +same_sandbox = await sandbox.connect() +``` + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create` + +```python +create( + template=None, + timeout=None, + metadata=None, + envs=None, + secure=True, + allow_internet_access=True, + mcp=None, + network=None, + iam=None, + lifecycle=None, + logger=None, + **opts +) +``` + +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. + +:param template: Sandbox template name or ID +:param timeout: Timeout for the sandbox in **seconds**, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. +:param metadata: Custom metadata for the sandbox +:param envs: Custom environment variables for the sandbox +:param secure: Envd is secured with access token and cannot be used without it, defaults to `True`. +:param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`. +:param mcp: MCP server to enable in the sandbox +:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``). +:param iam: Sandbox workload identity configuration. Each token contains ``audience`` and ``token_type``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request +:param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}`` +:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted. + +:return: A Sandbox instance for the new sandbox + +Use this method instead of using the constructor to create a new sandbox. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create_code_context` + +```python +create_code_context(cwd=None, language=None, request_timeout=None) +``` + +Creates a new context to run code in. + +:param cwd: Set the current working directory for the context, defaults to `/home/user` +:param language: Language of the context. If not specified, defaults to Python +:param request_timeout: Timeout for the request in **milliseconds** + +:return: Context object + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.create_snapshot` + +```python +create_snapshot(name=None, **opts) +``` + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshot_id` with `AsyncSandbox.create(snapshot_id)` to create a new sandbox from the snapshot. + +:param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one. + +:return: Snapshot information including the snapshot ID and names + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.default_template` + +```python +default_template = DEFAULT_TEMPLATE +``` + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.delete_snapshot` + +```python +delete_snapshot(snapshot_id, **opts) +``` + +Delete a snapshot. + +:param snapshot_id: Snapshot ID +:return: `True` if the snapshot was deleted, `False` if it was not found + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.files` + +```python +files: Filesystem +``` + +Module for interacting with the sandbox filesystem. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.fork` + +```python +fork(timeout=None, count=None, **opts) +``` + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with +its full memory state, and resumed — its ID and expiration stay +untouched) and `count` new sandboxes are created from that snapshot. +All forks boot from the same snapshot, so the snapshot is captured once +regardless of count. + +Each fork succeeds or fails independently — the returned list contains +one entry per requested fork, either a running `AsyncSandbox` instance +or an exception describing why that fork failed to start. Per-fork +error codes map to the same exception classes as other API errors +(e.g. 429 to `RateLimitException`). + +:param timeout: Timeout for the forked sandboxes in **seconds**, defaults to 300 seconds +:param count: Number of forked sandboxes to create, defaults to 1 + +:return: List with one entry per requested fork — a sandbox instance or an exception + +@example +```python +sandbox = await AsyncSandbox.create() + +fork1, fork2 = await sandbox.fork(count=2) +``` + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_info` + +```python +get_info(**opts) +``` + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +:return: Sandbox info + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_mcp_token` + +```python +get_mcp_token() +``` + +Get the MCP token for the sandbox. + +:return: MCP token for the sandbox, or None if MCP is not enabled. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.get_metrics` + +```python +get_metrics(start=None, end=None, **opts) +``` + +Get the metrics of the current sandbox. + +:param start: Start time for the metrics, defaults to the start of the sandbox +:param end: End time for the metrics, defaults to the current time + +:return: List of sandbox metrics containing CPU, memory and disk usage information + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.is_running` + +```python +is_running(request_timeout=None) +``` + +Check if the sandbox is running. + +:param request_timeout: Timeout for the request in **seconds** + +:return: `True` if the sandbox is running, `False` otherwise + +Example +```python +sandbox = await AsyncSandbox.create() +await sandbox.is_running() # Returns True + +await sandbox.kill() +await sandbox.is_running() # Returns False +``` + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.kill` + +```python +kill(**opts) +``` + +Kill the sandbox specified by sandbox ID. + +:return: `True` if the sandbox was killed, `False` if the sandbox was not found + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list` + +```python +list(query=None, limit=None, next_token=None, **opts) +``` + +List sandboxes. + +By default (no `query.state` set), returns sandboxes in both `running` +and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`. + +:param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])` +:param limit: Maximum number of sandboxes to return per page +:param next_token: Token for pagination + +:return: An `AsyncSandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `await paginator.next_items()` while `paginator.has_next` is True. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list_code_contexts` + +```python +list_code_contexts() +``` + +List all contexts. + +:return: List of contexts. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.list_snapshots` + +```python +list_snapshots(limit=None, next_token=None, name=None, **opts) +``` + +List snapshots for this sandbox. + +:param limit: Maximum number of snapshots to return per page +:param next_token: Token for pagination +:param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-project/my-snapshot" or "my-snapshot:v1") + +:return: Paginator for listing snapshots + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.pause` + +```python +pause(keep_memory=True, **opts) +``` + +Pause the sandbox. + +:param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot). + +:return: `True` if the sandbox got paused, `False` if the sandbox was already paused + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.pty` + +```python +pty: Pty +``` + +Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.remove_code_context` + +```python +remove_code_context(context) +``` + +Removes a context. + +:param context: Context to remove. Can be a Context object or a context ID string. + +:return: None + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.restart_code_context` + +```python +restart_code_context(context) +``` + +Restart a context. + +:param context: Context to restart. Can be a Context object or a context ID string. + +:return: None + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.run_code` + +```python +run_code( + code, + language=None, + context=None, + on_stdout=None, + on_stderr=None, + on_result=None, + on_error=None, + envs=None, + timeout=None, + request_timeout=None, +) +``` + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.set_timeout` + +```python +set_timeout(timeout, **opts) +``` + +Set the timeout of the specified sandbox. +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.set_timeout`. + +The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. + +:param timeout: Timeout for the sandbox in **seconds** + +#### `agentbox_code_interpreter.code_interpreter_async.AsyncSandbox.update_network` + +```python +update_network(network, **opts) +``` + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +:param network: New network configuration. + +### `agentbox_code_interpreter.code_interpreter_async.logger` + +```python +logger = logging.getLogger(__name__) +``` + diff --git a/reference/sdk/python/code-interpreter-sync.md b/reference/sdk/python/code-interpreter-sync.md new file mode 100644 index 00000000..46ec1a5e --- /dev/null +++ b/reference/sdk/python/code-interpreter-sync.md @@ -0,0 +1,422 @@ +## `agentbox_code_interpreter.code_interpreter_sync` + +**Classes:** + +- [**Sandbox**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox) – AgentBox cloud sandbox is a secure and isolated cloud environment. + +**Attributes:** + +- [**logger**](#agentbox_code_interpreter.code_interpreter_sync.logger) – + +### `agentbox_code_interpreter.code_interpreter_sync.Sandbox` + +Bases: [Sandbox](#agentbox.Sandbox) + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +See the [Code Interpreter guide](https://docs.agentbox.ru/en/sdk/code-interpreter/). + +Use the `Sandbox.create()` to create a new sandbox. + +Example: +```python +from agentbox_code_interpreter import Sandbox + +sandbox = Sandbox.create() +``` + +**Functions:** + +- [**connect**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.connect) – Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +- [**create**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.create) – Create a new sandbox. +- [**create_code_context**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.create_code_context) – Creates a new context to run code in. +- [**create_snapshot**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.create_snapshot) – Create a snapshot of the sandbox's current state. +- [**delete_snapshot**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.delete_snapshot) – Delete a snapshot. +- [**fork**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.fork) – Fork the sandbox. +- [**get_info**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_info) – Get sandbox information like sandbox ID, template, metadata, started at/end at date. +- [**get_mcp_token**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_mcp_token) – Get the MCP token for the sandbox. +- [**get_metrics**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_metrics) – Get the metrics of the current sandbox. +- [**is_running**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.is_running) – Check if the sandbox is running. +- [**kill**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.kill) – Kill the sandbox specified by sandbox ID. +- [**list**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.list) – List sandboxes. +- [**list_code_contexts**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.list_code_contexts) – List all contexts. +- [**list_snapshots**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.list_snapshots) – List snapshots for this sandbox. +- [**pause**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.pause) – Pause the sandbox. +- [**remove_code_context**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.remove_code_context) – Removes a context. +- [**restart_code_context**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.restart_code_context) – Restart a context. +- [**run_code**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.run_code) – +- [**set_timeout**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.set_timeout) – Set the timeout of the sandbox. +- [**update_network**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.update_network) – Update the network configuration of the sandbox. + +**Attributes:** + +- [**commands**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.commands) ([Commands](#agentbox.sandbox_sync.commands.command.Commands)) – Module for running commands in the sandbox. +- [**default_template**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.default_template) – +- [**files**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.files) ([Filesystem](#agentbox.sandbox_sync.filesystem.filesystem.Filesystem)) – Module for interacting with the sandbox filesystem. +- [**pty**](#agentbox_code_interpreter.code_interpreter_sync.Sandbox.pty) ([Pty](#agentbox.sandbox_sync.commands.pty.Pty)) – Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.commands` + +```python +commands: Commands +``` + +Module for running commands in the sandbox. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.connect` + +```python +connect(timeout=None, **opts) +``` + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +:param timeout: Timeout for the sandbox in **seconds**. + For running sandboxes, the timeout will update only if the new timeout is longer than the existing one. +:return: A running sandbox instance + +@example +```python +sandbox = Sandbox.create() +sandbox.pause() + +# Another code block +same_sandbox = sandbox.connect() +``` + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.create` + +```python +create( + template=None, + timeout=None, + metadata=None, + envs=None, + secure=True, + allow_internet_access=True, + mcp=None, + network=None, + iam=None, + lifecycle=None, + logger=None, + **opts +) +``` + +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. + +:param template: Sandbox template name or ID +:param timeout: Timeout for the sandbox in **seconds**, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. +:param metadata: Custom metadata for the sandbox +:param envs: Custom environment variables for the sandbox +:param secure: Envd is secured with access token and cannot be used without it, defaults to `True`. +:param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`. +:param mcp: MCP server to enable in the sandbox +:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``). +:param iam: Sandbox workload identity configuration. Each token contains ``audience`` and ``token_type``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request +:param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}`` +:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted. + +:return: A Sandbox instance for the new sandbox + +Use this method instead of using the constructor to create a new sandbox. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.create_code_context` + +```python +create_code_context(cwd=None, language=None, request_timeout=None) +``` + +Creates a new context to run code in. + +:param cwd: Set the current working directory for the context, defaults to `/home/user` +:param language: Language of the context. If not specified, defaults to Python +:param request_timeout: Timeout for the request in **milliseconds** + +:return: Context object + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.create_snapshot` + +```python +create_snapshot(name=None, **opts) +``` + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshot_id` with `Sandbox.create(snapshot_id)` to create a new sandbox from the snapshot. + +:param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one. + +:return: Snapshot information including the snapshot ID and names + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.default_template` + +```python +default_template = DEFAULT_TEMPLATE +``` + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.delete_snapshot` + +```python +delete_snapshot(snapshot_id, **opts) +``` + +Delete a snapshot. + +:param snapshot_id: Snapshot ID +:return: `True` if the snapshot was deleted, `False` if it was not found + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.files` + +```python +files: Filesystem +``` + +Module for interacting with the sandbox filesystem. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.fork` + +```python +fork(timeout=None, count=None, **opts) +``` + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with +its full memory state, and resumed — its ID and expiration stay +untouched) and `count` new sandboxes are created from that snapshot. +All forks boot from the same snapshot, so the snapshot is captured once +regardless of count. + +Each fork succeeds or fails independently — the returned list contains +one entry per requested fork, either a running `Sandbox` instance +or an exception describing why that fork failed to start. Per-fork +error codes map to the same exception classes as other API errors +(e.g. 429 to `RateLimitException`). + +:param timeout: Timeout for the forked sandboxes in **seconds**, defaults to 300 seconds +:param count: Number of forked sandboxes to create, defaults to 1 + +:return: List with one entry per requested fork — a sandbox instance or an exception + +@example +```python +sandbox = Sandbox.create() + +fork1, fork2 = sandbox.fork(count=2) +``` + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_info` + +```python +get_info(**opts) +``` + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +:return: Sandbox info + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_mcp_token` + +```python +get_mcp_token() +``` + +Get the MCP token for the sandbox. + +:return: MCP token for the sandbox, or None if MCP is not enabled. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.get_metrics` + +```python +get_metrics(start=None, end=None, **opts) +``` + +Get the metrics of the current sandbox. + +:param start: Start time for the metrics, defaults to the start of the sandbox +:param end: End time for the metrics, defaults to the current time + +:return: List of sandbox metrics containing CPU, memory and disk usage information + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.is_running` + +```python +is_running(request_timeout=None) +``` + +Check if the sandbox is running. + +:param request_timeout: Timeout for the request in **seconds** + +:return: `True` if the sandbox is running, `False` otherwise + +Example +```python +sandbox = Sandbox.create() +sandbox.is_running() # Returns True + +sandbox.kill() +sandbox.is_running() # Returns False +``` + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.kill` + +```python +kill(**opts) +``` + +Kill the sandbox specified by sandbox ID. + +:return: `True` if the sandbox was killed, `False` if the sandbox was not found + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.list` + +```python +list(query=None, limit=None, next_token=None, **opts) +``` + +List sandboxes. + +By default (no `query.state` set), returns sandboxes in both `running` +and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`. + +:param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])` +:param limit: Maximum number of sandboxes to return per page +:param next_token: Token for pagination + +:return: A `SandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `paginator.next_items()` while `paginator.has_next` is True. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.list_code_contexts` + +```python +list_code_contexts() +``` + +List all contexts. + +:return: List of contexts. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.list_snapshots` + +```python +list_snapshots(limit=None, next_token=None, name=None, **opts) +``` + +List snapshots for this sandbox. + +:param limit: Maximum number of snapshots to return per page +:param next_token: Token for pagination +:param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-project/my-snapshot" or "my-snapshot:v1") + +:return: Paginator for listing snapshots + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.pause` + +```python +pause(keep_memory=True, **opts) +``` + +Pause the sandbox. + +:param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot). + +:return: `True` if the sandbox got paused, `False` if the sandbox was already paused + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.pty` + +```python +pty: Pty +``` + +Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.remove_code_context` + +```python +remove_code_context(context) +``` + +Removes a context. + +:param context: Context to remove. Can be a Context object or a context ID string. + +:return: None + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.restart_code_context` + +```python +restart_code_context(context) +``` + +Restart a context. + +:param context: Context to restart. Can be a Context object or a context ID string. + +:return: None + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.run_code` + +```python +run_code( + code, + language=None, + context=None, + on_stdout=None, + on_stderr=None, + on_result=None, + on_error=None, + envs=None, + timeout=None, + request_timeout=None, +) +``` + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.set_timeout` + +```python +set_timeout(timeout, **opts) +``` + +Set the timeout of the sandbox. +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.set_timeout`. + +The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. + +:param timeout: Timeout for the sandbox in **seconds** + +#### `agentbox_code_interpreter.code_interpreter_sync.Sandbox.update_network` + +```python +update_network(network, **opts) +``` + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +:param network: New network configuration. + +### `agentbox_code_interpreter.code_interpreter_sync.logger` + +```python +logger = logging.getLogger(__name__) +``` + diff --git a/reference/sdk/python/exceptions.md b/reference/sdk/python/exceptions.md new file mode 100644 index 00000000..a339d7b7 --- /dev/null +++ b/reference/sdk/python/exceptions.md @@ -0,0 +1,109 @@ +## `agentbox.exceptions` + +**Classes:** + +- [**AuthenticationException**](#agentbox.exceptions.AuthenticationException) – Raised when authentication fails. +- [**BuildException**](#agentbox.exceptions.BuildException) – Raised when the build fails. +- [**FileNotFoundException**](#agentbox.exceptions.FileNotFoundException) – Raised when a file or directory is not found inside a sandbox. +- [**FileUploadException**](#agentbox.exceptions.FileUploadException) – Raised when the file upload fails. +- [**InvalidArgumentException**](#agentbox.exceptions.InvalidArgumentException) – Raised when an invalid argument is provided. +- [**NotEnoughSpaceException**](#agentbox.exceptions.NotEnoughSpaceException) – Raised when there is not enough disk space. +- [**RateLimitException**](#agentbox.exceptions.RateLimitException) – Raised when the API rate limit is exceeded. +- [**SandboxException**](#agentbox.exceptions.SandboxException) – Base class for all sandbox errors. +- [**SandboxNotFoundException**](#agentbox.exceptions.SandboxNotFoundException) – Raised when a sandbox is not found (e.g. it doesn't exist or is no longer running). +- [**TemplateException**](#agentbox.exceptions.TemplateException) – Exception raised when the template uses old envd version. It isn't compatible with the new SDK. +- [**TimeoutException**](#agentbox.exceptions.TimeoutException) – Raised when a timeout occurs. + +**Functions:** + +- [**format_request_timeout_error**](#agentbox.exceptions.format_request_timeout_error) – +- [**format_sandbox_timeout_exception**](#agentbox.exceptions.format_sandbox_timeout_exception) – + +### `agentbox.exceptions.AuthenticationException` + +Bases: [Exception](#Exception) + +Raised when authentication fails. + +### `agentbox.exceptions.BuildException` + +Bases: [Exception](#Exception) + +Raised when the build fails. + +### `agentbox.exceptions.FileNotFoundException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when a file or directory is not found inside a sandbox. + +### `agentbox.exceptions.FileUploadException` + +Bases: [BuildException](#agentbox.exceptions.BuildException) + +Raised when the file upload fails. + +### `agentbox.exceptions.InvalidArgumentException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when an invalid argument is provided. + +### `agentbox.exceptions.NotEnoughSpaceException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when there is not enough disk space. + +### `agentbox.exceptions.RateLimitException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when the API rate limit is exceeded. + +### `agentbox.exceptions.SandboxException` + +Bases: [Exception](#Exception) + +Base class for all sandbox errors. + +Raised when a general sandbox exception occurs. + +### `agentbox.exceptions.SandboxNotFoundException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when a sandbox is not found (e.g. it doesn't exist or is no longer running). + +### `agentbox.exceptions.TemplateException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Exception raised when the template uses old envd version. It isn't compatible with the new SDK. + +### `agentbox.exceptions.TimeoutException` + +Bases: [SandboxException](#agentbox.exceptions.SandboxException) + +Raised when a timeout occurs. + +The `unavailable` exception type is caused by sandbox timeout. + +The `canceled` exception type is caused by exceeding request timeout. + +The `deadline_exceeded` exception type is caused by exceeding the timeout for process, watch, etc. + +The `unknown` exception type is sometimes caused by the sandbox timeout when the request is not processed correctly. + +### `agentbox.exceptions.format_request_timeout_error` + +```python +format_request_timeout_error() +``` + +### `agentbox.exceptions.format_sandbox_timeout_exception` + +```python +format_sandbox_timeout_exception(message) +``` + diff --git a/reference/sdk/python/logger.md b/reference/sdk/python/logger.md new file mode 100644 index 00000000..4f1a6bfc --- /dev/null +++ b/reference/sdk/python/logger.md @@ -0,0 +1,249 @@ +## `agentbox.template.logger` + +**Classes:** + +- [**DefaultBuildLogger**](#agentbox.template.logger.DefaultBuildLogger) – +- [**DefaultBuildLoggerInitialState**](#agentbox.template.logger.DefaultBuildLoggerInitialState) – +- [**LogEntry**](#agentbox.template.logger.LogEntry) – Represents a single log entry from the template build process. +- [**LogEntryEnd**](#agentbox.template.logger.LogEntryEnd) – Special log entry indicating the end of a build process. +- [**LogEntryStart**](#agentbox.template.logger.LogEntryStart) – Special log entry indicating the start of a build process. + +**Functions:** + +- [**default_build_logger**](#agentbox.template.logger.default_build_logger) – Create a default build logger with animated timer display. +- [**set_interval**](#agentbox.template.logger.set_interval) – Returns a stop function that can be called to cancel the interval. + +**Attributes:** + +- [**DEFAULT_LEVEL**](#agentbox.template.logger.DEFAULT_LEVEL) ([LogEntryLevel](#agentbox.template.logger.LogEntryLevel)) – Colored labels for each log level. +- [**LogEntryLevel**](#agentbox.template.logger.LogEntryLevel) – +- [**TIMER_UPDATE_INTERVAL_MS**](#agentbox.template.logger.TIMER_UPDATE_INTERVAL_MS) – Default minimum log level to display. +- [**level_order**](#agentbox.template.logger.level_order) – +- [**levels**](#agentbox.template.logger.levels) ([Dict](#typing.Dict)[[LogEntryLevel](#agentbox.template.logger.LogEntryLevel), [tuple](#tuple)[[str](#str), [Style](#rich.style.Style)]]) – Numeric ordering of log levels for comparison (lower = less severe). + +### `agentbox.template.logger.DEFAULT_LEVEL` + +```python +DEFAULT_LEVEL: LogEntryLevel = 'info' +``` + +Colored labels for each log level. + +### `agentbox.template.logger.DefaultBuildLogger` + +```python +DefaultBuildLogger(min_level=None) +``` + +**Functions:** + +- [**logger**](#agentbox.template.logger.DefaultBuildLogger.logger) – + +#### `agentbox.template.logger.DefaultBuildLogger.logger` + +```python +logger(log) +``` + +### `agentbox.template.logger.DefaultBuildLoggerInitialState` + +Bases: [TypedDict](#typing.TypedDict) + +**Attributes:** + +- [**animation_frame**](#agentbox.template.logger.DefaultBuildLoggerInitialState.animation_frame) ([int](#int)) – +- [**start_time**](#agentbox.template.logger.DefaultBuildLoggerInitialState.start_time) ([float](#float)) – +- [**timer**](#agentbox.template.logger.DefaultBuildLoggerInitialState.timer) ([Optional](#typing.Optional)[[Callable](#typing.Callable)[[], None]]) – + +#### `agentbox.template.logger.DefaultBuildLoggerInitialState.animation_frame` + +```python +animation_frame: int +``` + +#### `agentbox.template.logger.DefaultBuildLoggerInitialState.start_time` + +```python +start_time: float +``` + +#### `agentbox.template.logger.DefaultBuildLoggerInitialState.timer` + +```python +timer: Optional[Callable[[], None]] +``` + +### `agentbox.template.logger.LogEntry` + +```python +LogEntry(timestamp, level, message) +``` + +Represents a single log entry from the template build process. + +**Attributes:** + +- [**level**](#agentbox.template.logger.LogEntry.level) ([LogEntryLevel](#agentbox.template.logger.LogEntryLevel)) – +- [**message**](#agentbox.template.logger.LogEntry.message) ([str](#str)) – +- [**timestamp**](#agentbox.template.logger.LogEntry.timestamp) ([datetime](#datetime.datetime)) – + +#### `agentbox.template.logger.LogEntry.level` + +```python +level: LogEntryLevel +``` + +#### `agentbox.template.logger.LogEntry.message` + +```python +message: str +``` + +#### `agentbox.template.logger.LogEntry.timestamp` + +```python +timestamp: datetime +``` + +### `agentbox.template.logger.LogEntryEnd` + +```python +LogEntryEnd(timestamp, level, message) +``` + +Bases: [LogEntry](#agentbox.template.logger.LogEntry) + +Special log entry indicating the end of a build process. + +**Attributes:** + +- [**level**](#agentbox.template.logger.LogEntryEnd.level) ([LogEntryLevel](#agentbox.template.logger.LogEntryLevel)) – +- [**message**](#agentbox.template.logger.LogEntryEnd.message) ([str](#str)) – +- [**timestamp**](#agentbox.template.logger.LogEntryEnd.timestamp) ([datetime](#datetime.datetime)) – + +#### `agentbox.template.logger.LogEntryEnd.level` + +```python +level: LogEntryLevel = field(default='debug', init=False) +``` + +#### `agentbox.template.logger.LogEntryEnd.message` + +```python +message: str +``` + +#### `agentbox.template.logger.LogEntryEnd.timestamp` + +```python +timestamp: datetime +``` + +### `agentbox.template.logger.LogEntryLevel` + +```python +LogEntryLevel = Literal['debug', 'info', 'warn', 'error'] +``` + +### `agentbox.template.logger.LogEntryStart` + +```python +LogEntryStart(timestamp, level, message) +``` + +Bases: [LogEntry](#agentbox.template.logger.LogEntry) + +Special log entry indicating the start of a build process. + +**Attributes:** + +- [**level**](#agentbox.template.logger.LogEntryStart.level) ([LogEntryLevel](#agentbox.template.logger.LogEntryLevel)) – +- [**message**](#agentbox.template.logger.LogEntryStart.message) ([str](#str)) – +- [**timestamp**](#agentbox.template.logger.LogEntryStart.timestamp) ([datetime](#datetime.datetime)) – + +#### `agentbox.template.logger.LogEntryStart.level` + +```python +level: LogEntryLevel = field(default='debug', init=False) +``` + +#### `agentbox.template.logger.LogEntryStart.message` + +```python +message: str +``` + +#### `agentbox.template.logger.LogEntryStart.timestamp` + +```python +timestamp: datetime +``` + +### `agentbox.template.logger.TIMER_UPDATE_INTERVAL_MS` + +```python +TIMER_UPDATE_INTERVAL_MS = 150 +``` + +Default minimum log level to display. + +### `agentbox.template.logger.default_build_logger` + +```python +default_build_logger(min_level=None) +``` + +Create a default build logger with animated timer display. + +:param min_level: Minimum log level to display (default: 'info') + +:return: Logger function that accepts LogEntry instances + +Example +```python +from agentbox import Template, default_build_logger + +template = Template().from_python_image() + +# Use with build - implementation would be in build_async module +# await Template.build(template, +# alias='my-template', +# on_build_logs=default_build_logger(min_level='debug') +# ) +``` + +### `agentbox.template.logger.level_order` + +```python +level_order = {'debug': 0, 'info': 1, 'warn': 2, 'error': 3} +``` + +### `agentbox.template.logger.levels` + +```python +levels: Dict[LogEntryLevel, tuple[str, Style]] = { + "error": ("ERROR", Style(color="red")), + "warn": ("WARN ", Style(color="#FF4400")), + "info": ("INFO ", Style(color="#FF8800")), + "debug": ("DEBUG", Style(color="bright_black")), +} + +``` + +Numeric ordering of log levels for comparison (lower = less severe). + +### `agentbox.template.logger.set_interval` + +```python +set_interval(func, interval) +``` + +Returns a stop function that can be called to cancel the interval. + +Similar to JavaScript's setInterval. + +:param func: Function to execute at each interval +:param interval: Interval duration in **seconds** + +:return: Stop function that can be called to cancel the interval + diff --git a/reference/sdk/python/ready-commands.md b/reference/sdk/python/ready-commands.md new file mode 100644 index 00000000..9feb465c --- /dev/null +++ b/reference/sdk/python/ready-commands.md @@ -0,0 +1,158 @@ +## `agentbox.template.readycmd` + +**Classes:** + +- [**ReadyCmd**](#agentbox.template.readycmd.ReadyCmd) – Wrapper class for ready check commands. + +**Functions:** + +- [**wait_for_file**](#agentbox.template.readycmd.wait_for_file) – Wait for a file to exist. +- [**wait_for_port**](#agentbox.template.readycmd.wait_for_port) – Wait for a port to be listening. +- [**wait_for_process**](#agentbox.template.readycmd.wait_for_process) – Wait for a process with a specific name to be running. +- [**wait_for_timeout**](#agentbox.template.readycmd.wait_for_timeout) – Wait for a specified timeout before considering the sandbox ready. +- [**wait_for_url**](#agentbox.template.readycmd.wait_for_url) – Wait for a URL to return a specific HTTP status code. + +### `agentbox.template.readycmd.ReadyCmd` + +```python +ReadyCmd(cmd) +``` + +Wrapper class for ready check commands. + +**Functions:** + +- [**get_cmd**](#agentbox.template.readycmd.ReadyCmd.get_cmd) – + +#### `agentbox.template.readycmd.ReadyCmd.get_cmd` + +```python +get_cmd() +``` + +### `agentbox.template.readycmd.wait_for_file` + +```python +wait_for_file(filename) +``` + +Wait for a file to exist. + +Uses shell test command to check file existence. + +:param filename: Path to the file to wait for + +:return: ReadyCmd that checks for the file + +Example +```python +from agentbox import Template, wait_for_file + +template = ( + Template() + .from_base_image() + .set_start_cmd('./init.sh', wait_for_file('/tmp/ready')) +) +``` + +### `agentbox.template.readycmd.wait_for_port` + +```python +wait_for_port(port) +``` + +Wait for a port to be listening. + +Uses `ss` command to check if a port is open and listening. + +:param port: Port number to wait for + +:return: ReadyCmd that checks for the port + +Example +```python +from agentbox import Template, wait_for_port + +template = ( + Template() + .from_python_image() + .set_start_cmd('python -m http.server 8000', wait_for_port(8000)) +) +``` + +### `agentbox.template.readycmd.wait_for_process` + +```python +wait_for_process(process_name) +``` + +Wait for a process with a specific name to be running. + +Uses `pgrep` to check if a process exists. + +:param process_name: Name of the process to wait for + +:return: ReadyCmd that checks for the process + +Example +```python +from agentbox import Template, wait_for_process + +template = ( + Template() + .from_base_image() + .set_start_cmd('./my-daemon', wait_for_process('my-daemon')) +) +``` + +### `agentbox.template.readycmd.wait_for_timeout` + +```python +wait_for_timeout(timeout) +``` + +Wait for a specified timeout before considering the sandbox ready. + +Uses `sleep` command to wait for a fixed duration. + +:param timeout: Time to wait in **milliseconds** (minimum: 1000ms / 1 second) + +:return: ReadyCmd that waits for the specified duration + +Example +```python +from agentbox import Template, wait_for_timeout + +template = ( + Template() + .from_node_image() + .set_start_cmd('npm start', wait_for_timeout(5000)) # Wait 5 seconds +) +``` + +### `agentbox.template.readycmd.wait_for_url` + +```python +wait_for_url(url, status_code=200) +``` + +Wait for a URL to return a specific HTTP status code. + +Uses `curl` to make HTTP requests and check the response status. + +:param url: URL to check (e.g., 'http://localhost:3000/health') +:param status_code: Expected HTTP status code (default: 200) + +:return: ReadyCmd that checks the URL + +Example +```python +from agentbox import Template, wait_for_url + +template = ( + Template() + .from_node_image() + .set_start_cmd('npm start', wait_for_url('http://localhost:3000/health')) +) +``` + diff --git a/reference/sdk/python/sandbox-async.md b/reference/sdk/python/sandbox-async.md new file mode 100644 index 00000000..283edd61 --- /dev/null +++ b/reference/sdk/python/sandbox-async.md @@ -0,0 +1,351 @@ +## `agentbox.sandbox_async.main` + +**Classes:** + +- [**AsyncSandbox**](#agentbox.sandbox_async.main.AsyncSandbox) – AgentBox cloud sandbox is a secure and isolated cloud environment. + +**Attributes:** + +- [**logger**](#agentbox.sandbox_async.main.logger) – + +### `agentbox.sandbox_async.main.AsyncSandbox` + +```python +AsyncSandbox(**opts) +``` + +Bases: [SandboxApi](#agentbox.sandbox_async.sandbox_api.SandboxApi) + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +See the sandbox documentation at https://docs.agentbox.ru/en/sdk/sandboxes/. + +Use the `AsyncSandbox.create()` to create a new sandbox. + +Example: +```python +from agentbox import AsyncSandbox + +sandbox = await AsyncSandbox.create() +``` + +**Functions:** + +- [**connect**](#agentbox.sandbox_async.main.AsyncSandbox.connect) – Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +- [**create**](#agentbox.sandbox_async.main.AsyncSandbox.create) – Create a new sandbox. +- [**create_snapshot**](#agentbox.sandbox_async.main.AsyncSandbox.create_snapshot) – Create a snapshot of the sandbox's current state. +- [**delete_snapshot**](#agentbox.sandbox_async.main.AsyncSandbox.delete_snapshot) – Delete a snapshot. +- [**fork**](#agentbox.sandbox_async.main.AsyncSandbox.fork) – Fork the sandbox. +- [**get_info**](#agentbox.sandbox_async.main.AsyncSandbox.get_info) – Get sandbox information like sandbox ID, template, metadata, started at/end at date. +- [**get_mcp_token**](#agentbox.sandbox_async.main.AsyncSandbox.get_mcp_token) – Get the MCP token for the sandbox. +- [**get_metrics**](#agentbox.sandbox_async.main.AsyncSandbox.get_metrics) – Get the metrics of the current sandbox. +- [**is_running**](#agentbox.sandbox_async.main.AsyncSandbox.is_running) – Check if the sandbox is running. +- [**kill**](#agentbox.sandbox_async.main.AsyncSandbox.kill) – Kill the sandbox specified by sandbox ID. +- [**list**](#agentbox.sandbox_async.main.AsyncSandbox.list) – List sandboxes. +- [**list_snapshots**](#agentbox.sandbox_async.main.AsyncSandbox.list_snapshots) – List snapshots for this sandbox. +- [**pause**](#agentbox.sandbox_async.main.AsyncSandbox.pause) – Pause the sandbox. +- [**set_timeout**](#agentbox.sandbox_async.main.AsyncSandbox.set_timeout) – Set the timeout of the specified sandbox. +- [**update_network**](#agentbox.sandbox_async.main.AsyncSandbox.update_network) – Update the network configuration of the sandbox. + +**Attributes:** + +- [**commands**](#agentbox.sandbox_async.main.AsyncSandbox.commands) ([Commands](#agentbox.sandbox_async.commands.command.Commands)) – Module for running commands in the sandbox. +- [**files**](#agentbox.sandbox_async.main.AsyncSandbox.files) ([Filesystem](#agentbox.sandbox_async.filesystem.filesystem.Filesystem)) – Module for interacting with the sandbox filesystem. +- [**pty**](#agentbox.sandbox_async.main.AsyncSandbox.pty) ([Pty](#agentbox.sandbox_async.commands.pty.Pty)) – Module for interacting with the sandbox pseudo-terminal. + +Applications should use `AsyncSandbox.create()` or `AsyncSandbox.connect()`. + +#### `agentbox.sandbox_async.main.AsyncSandbox.commands` + +```python +commands: Commands +``` + +Module for running commands in the sandbox. + +#### `agentbox.sandbox_async.main.AsyncSandbox.connect` + +```python +connect(timeout=None, **opts) +``` + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +:param timeout: Timeout for the sandbox in **seconds** + For running sandboxes, the timeout will update only if the new timeout is longer than the existing one. +:return: A running sandbox instance + +@example +```python +sandbox = await AsyncSandbox.create() +await sandbox.pause() + +# Another code block +same_sandbox = await sandbox.connect() +``` + +#### `agentbox.sandbox_async.main.AsyncSandbox.create` + +```python +create( + template=None, + timeout=None, + metadata=None, + envs=None, + secure=True, + allow_internet_access=True, + mcp=None, + network=None, + iam=None, + lifecycle=None, + logger=None, + **opts +) +``` + +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. + +:param template: Sandbox template name or ID +:param timeout: Timeout for the sandbox in **seconds**, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. +:param metadata: Custom metadata for the sandbox +:param envs: Custom environment variables for the sandbox +:param secure: Envd is secured with access token and cannot be used without it, defaults to `True`. +:param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`. +:param mcp: MCP server to enable in the sandbox +:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``). +:param iam: Sandbox workload identity configuration. Each token contains ``audience`` and ``token_type``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request +:param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}`` +:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted. + +:return: A Sandbox instance for the new sandbox + +Use this method instead of using the constructor to create a new sandbox. + +#### `agentbox.sandbox_async.main.AsyncSandbox.create_snapshot` + +```python +create_snapshot(name=None, **opts) +``` + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshot_id` with `AsyncSandbox.create(snapshot_id)` to create a new sandbox from the snapshot. + +:param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one. + +:return: Snapshot information including the snapshot ID and names + +#### `agentbox.sandbox_async.main.AsyncSandbox.delete_snapshot` + +```python +delete_snapshot(snapshot_id, **opts) +``` + +Delete a snapshot. + +:param snapshot_id: Snapshot ID +:return: `True` if the snapshot was deleted, `False` if it was not found + +#### `agentbox.sandbox_async.main.AsyncSandbox.files` + +```python +files: Filesystem +``` + +Module for interacting with the sandbox filesystem. + +#### `agentbox.sandbox_async.main.AsyncSandbox.fork` + +```python +fork(timeout=None, count=None, **opts) +``` + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with +its full memory state, and resumed — its ID and expiration stay +untouched) and `count` new sandboxes are created from that snapshot. +All forks boot from the same snapshot, so the snapshot is captured once +regardless of count. + +Each fork succeeds or fails independently — the returned list contains +one entry per requested fork, either a running `AsyncSandbox` instance +or an exception describing why that fork failed to start. Per-fork +error codes map to the same exception classes as other API errors +(e.g. 429 to `RateLimitException`). + +:param timeout: Timeout for the forked sandboxes in **seconds**, defaults to 300 seconds +:param count: Number of forked sandboxes to create, defaults to 1 + +:return: List with one entry per requested fork — a sandbox instance or an exception + +@example +```python +sandbox = await AsyncSandbox.create() + +fork1, fork2 = await sandbox.fork(count=2) +``` + +#### `agentbox.sandbox_async.main.AsyncSandbox.get_info` + +```python +get_info(**opts) +``` + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +:return: Sandbox info + +#### `agentbox.sandbox_async.main.AsyncSandbox.get_mcp_token` + +```python +get_mcp_token() +``` + +Get the MCP token for the sandbox. + +:return: MCP token for the sandbox, or None if MCP is not enabled. + +#### `agentbox.sandbox_async.main.AsyncSandbox.get_metrics` + +```python +get_metrics(start=None, end=None, **opts) +``` + +Get the metrics of the current sandbox. + +:param start: Start time for the metrics, defaults to the start of the sandbox +:param end: End time for the metrics, defaults to the current time + +:return: List of sandbox metrics containing CPU, memory and disk usage information + +#### `agentbox.sandbox_async.main.AsyncSandbox.is_running` + +```python +is_running(request_timeout=None) +``` + +Check if the sandbox is running. + +:param request_timeout: Timeout for the request in **seconds** + +:return: `True` if the sandbox is running, `False` otherwise + +Example +```python +sandbox = await AsyncSandbox.create() +await sandbox.is_running() # Returns True + +await sandbox.kill() +await sandbox.is_running() # Returns False +``` + +#### `agentbox.sandbox_async.main.AsyncSandbox.kill` + +```python +kill(**opts) +``` + +Kill the sandbox specified by sandbox ID. + +:return: `True` if the sandbox was killed, `False` if the sandbox was not found + +#### `agentbox.sandbox_async.main.AsyncSandbox.list` + +```python +list(query=None, limit=None, next_token=None, **opts) +``` + +List sandboxes. + +By default (no `query.state` set), returns sandboxes in both `running` +and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`. + +:param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])` +:param limit: Maximum number of sandboxes to return per page +:param next_token: Token for pagination + +:return: An `AsyncSandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `await paginator.next_items()` while `paginator.has_next` is True. + +#### `agentbox.sandbox_async.main.AsyncSandbox.list_snapshots` + +```python +list_snapshots(limit=None, next_token=None, name=None, **opts) +``` + +List snapshots for this sandbox. + +:param limit: Maximum number of snapshots to return per page +:param next_token: Token for pagination +:param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-project/my-snapshot" or "my-snapshot:v1") + +:return: Paginator for listing snapshots + +#### `agentbox.sandbox_async.main.AsyncSandbox.pause` + +```python +pause(keep_memory=True, **opts) +``` + +Pause the sandbox. + +:param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot). + +:return: `True` if the sandbox got paused, `False` if the sandbox was already paused + +#### `agentbox.sandbox_async.main.AsyncSandbox.pty` + +```python +pty: Pty +``` + +Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox.sandbox_async.main.AsyncSandbox.set_timeout` + +```python +set_timeout(timeout, **opts) +``` + +Set the timeout of the specified sandbox. +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.set_timeout`. + +The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. + +:param timeout: Timeout for the sandbox in **seconds** + +#### `agentbox.sandbox_async.main.AsyncSandbox.update_network` + +```python +update_network(network, **opts) +``` + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +:param network: New network configuration. + +### `agentbox.sandbox_async.main.logger` + +```python +logger = logging.getLogger(__name__) +``` + diff --git a/reference/sdk/python/sandbox-sync.md b/reference/sdk/python/sandbox-sync.md new file mode 100644 index 00000000..9bf54ef9 --- /dev/null +++ b/reference/sdk/python/sandbox-sync.md @@ -0,0 +1,351 @@ +## `agentbox.sandbox_sync.main` + +**Classes:** + +- [**Sandbox**](#agentbox.sandbox_sync.main.Sandbox) – AgentBox cloud sandbox is a secure and isolated cloud environment. + +**Attributes:** + +- [**logger**](#agentbox.sandbox_sync.main.logger) – + +### `agentbox.sandbox_sync.main.Sandbox` + +```python +Sandbox(**opts) +``` + +Bases: [SandboxApi](#agentbox.sandbox_sync.sandbox_api.SandboxApi) + +AgentBox cloud sandbox is a secure and isolated cloud environment. + +The sandbox allows you to: +- Access Linux OS +- Create, list, and delete files and directories +- Run commands +- Run isolated code +- Access the internet + +See the sandbox documentation at https://docs.agentbox.ru/en/sdk/sandboxes/. + +Use the `Sandbox.create()` to create a new sandbox. + +Example: +```python +from agentbox import Sandbox + +sandbox = Sandbox.create() +``` + +**Functions:** + +- [**connect**](#agentbox.sandbox_sync.main.Sandbox.connect) – Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +- [**create**](#agentbox.sandbox_sync.main.Sandbox.create) – Create a new sandbox. +- [**create_snapshot**](#agentbox.sandbox_sync.main.Sandbox.create_snapshot) – Create a snapshot of the sandbox's current state. +- [**delete_snapshot**](#agentbox.sandbox_sync.main.Sandbox.delete_snapshot) – Delete a snapshot. +- [**fork**](#agentbox.sandbox_sync.main.Sandbox.fork) – Fork the sandbox. +- [**get_info**](#agentbox.sandbox_sync.main.Sandbox.get_info) – Get sandbox information like sandbox ID, template, metadata, started at/end at date. +- [**get_mcp_token**](#agentbox.sandbox_sync.main.Sandbox.get_mcp_token) – Get the MCP token for the sandbox. +- [**get_metrics**](#agentbox.sandbox_sync.main.Sandbox.get_metrics) – Get the metrics of the current sandbox. +- [**is_running**](#agentbox.sandbox_sync.main.Sandbox.is_running) – Check if the sandbox is running. +- [**kill**](#agentbox.sandbox_sync.main.Sandbox.kill) – Kill the sandbox specified by sandbox ID. +- [**list**](#agentbox.sandbox_sync.main.Sandbox.list) – List sandboxes. +- [**list_snapshots**](#agentbox.sandbox_sync.main.Sandbox.list_snapshots) – List snapshots for this sandbox. +- [**pause**](#agentbox.sandbox_sync.main.Sandbox.pause) – Pause the sandbox. +- [**set_timeout**](#agentbox.sandbox_sync.main.Sandbox.set_timeout) – Set the timeout of the sandbox. +- [**update_network**](#agentbox.sandbox_sync.main.Sandbox.update_network) – Update the network configuration of the sandbox. + +**Attributes:** + +- [**commands**](#agentbox.sandbox_sync.main.Sandbox.commands) ([Commands](#agentbox.sandbox_sync.commands.command.Commands)) – Module for running commands in the sandbox. +- [**files**](#agentbox.sandbox_sync.main.Sandbox.files) ([Filesystem](#agentbox.sandbox_sync.filesystem.filesystem.Filesystem)) – Module for interacting with the sandbox filesystem. +- [**pty**](#agentbox.sandbox_sync.main.Sandbox.pty) ([Pty](#agentbox.sandbox_sync.commands.pty.Pty)) – Module for interacting with the sandbox pseudo-terminal. + +Applications should use `Sandbox.create()` or `Sandbox.connect()`. + +#### `agentbox.sandbox_sync.main.Sandbox.commands` + +```python +commands: Commands +``` + +Module for running commands in the sandbox. + +#### `agentbox.sandbox_sync.main.Sandbox.connect` + +```python +connect(timeout=None, **opts) +``` + +Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. +Sandbox must be either running or be paused. + +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +:param timeout: Timeout for the sandbox in **seconds**. + For running sandboxes, the timeout will update only if the new timeout is longer than the existing one. +:return: A running sandbox instance + +@example +```python +sandbox = Sandbox.create() +sandbox.pause() + +# Another code block +same_sandbox = sandbox.connect() +``` + +#### `agentbox.sandbox_sync.main.Sandbox.create` + +```python +create( + template=None, + timeout=None, + metadata=None, + envs=None, + secure=True, + allow_internet_access=True, + mcp=None, + network=None, + iam=None, + lifecycle=None, + logger=None, + **opts +) +``` + +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. + +:param template: Sandbox template name or ID +:param timeout: Timeout for the sandbox in **seconds**, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. +:param metadata: Custom metadata for the sandbox +:param envs: Custom environment variables for the sandbox +:param secure: Envd is secured with access token and cannot be used without it, defaults to `True`. +:param allow_internet_access: Allow sandbox to access the internet, defaults to `True`. If set to `False`, it works the same as setting network `deny_out` to `[0.0.0.0/0]`. +:param mcp: MCP server to enable in the sandbox +:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``). +:param iam: Sandbox workload identity configuration. Each token contains ``audience`` and ``token_type``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request +:param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}`` +:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted. + +:return: A Sandbox instance for the new sandbox + +Use this method instead of using the constructor to create a new sandbox. + +#### `agentbox.sandbox_sync.main.Sandbox.create_snapshot` + +```python +create_snapshot(name=None, **opts) +``` + +Create a snapshot of the sandbox's current state. + +The sandbox will be paused while the snapshot is being created. +The snapshot can be used to create new sandboxes with the same filesystem and state. +Snapshots are persistent and survive sandbox deletion. + +Use the returned `snapshot_id` with `Sandbox.create(snapshot_id)` to create a new sandbox from the snapshot. + +:param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one. + +:return: Snapshot information including the snapshot ID and names + +#### `agentbox.sandbox_sync.main.Sandbox.delete_snapshot` + +```python +delete_snapshot(snapshot_id, **opts) +``` + +Delete a snapshot. + +:param snapshot_id: Snapshot ID +:return: `True` if the snapshot was deleted, `False` if it was not found + +#### `agentbox.sandbox_sync.main.Sandbox.files` + +```python +files: Filesystem +``` + +Module for interacting with the sandbox filesystem. + +#### `agentbox.sandbox_sync.main.Sandbox.fork` + +```python +fork(timeout=None, count=None, **opts) +``` + +Fork the sandbox. + +The sandbox is checkpointed in place (briefly paused, snapshotted with +its full memory state, and resumed — its ID and expiration stay +untouched) and `count` new sandboxes are created from that snapshot. +All forks boot from the same snapshot, so the snapshot is captured once +regardless of count. + +Each fork succeeds or fails independently — the returned list contains +one entry per requested fork, either a running `Sandbox` instance +or an exception describing why that fork failed to start. Per-fork +error codes map to the same exception classes as other API errors +(e.g. 429 to `RateLimitException`). + +:param timeout: Timeout for the forked sandboxes in **seconds**, defaults to 300 seconds +:param count: Number of forked sandboxes to create, defaults to 1 + +:return: List with one entry per requested fork — a sandbox instance or an exception + +@example +```python +sandbox = Sandbox.create() + +fork1, fork2 = sandbox.fork(count=2) +``` + +#### `agentbox.sandbox_sync.main.Sandbox.get_info` + +```python +get_info(**opts) +``` + +Get sandbox information like sandbox ID, template, metadata, started at/end at date. + +:return: Sandbox info + +#### `agentbox.sandbox_sync.main.Sandbox.get_mcp_token` + +```python +get_mcp_token() +``` + +Get the MCP token for the sandbox. + +:return: MCP token for the sandbox, or None if MCP is not enabled. + +#### `agentbox.sandbox_sync.main.Sandbox.get_metrics` + +```python +get_metrics(start=None, end=None, **opts) +``` + +Get the metrics of the current sandbox. + +:param start: Start time for the metrics, defaults to the start of the sandbox +:param end: End time for the metrics, defaults to the current time + +:return: List of sandbox metrics containing CPU, memory and disk usage information + +#### `agentbox.sandbox_sync.main.Sandbox.is_running` + +```python +is_running(request_timeout=None) +``` + +Check if the sandbox is running. + +:param request_timeout: Timeout for the request in **seconds** + +:return: `True` if the sandbox is running, `False` otherwise + +Example +```python +sandbox = Sandbox.create() +sandbox.is_running() # Returns True + +sandbox.kill() +sandbox.is_running() # Returns False +``` + +#### `agentbox.sandbox_sync.main.Sandbox.kill` + +```python +kill(**opts) +``` + +Kill the sandbox specified by sandbox ID. + +:return: `True` if the sandbox was killed, `False` if the sandbox was not found + +#### `agentbox.sandbox_sync.main.Sandbox.list` + +```python +list(query=None, limit=None, next_token=None, **opts) +``` + +List sandboxes. + +By default (no `query.state` set), returns sandboxes in both `running` +and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`. + +:param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])` +:param limit: Maximum number of sandboxes to return per page +:param next_token: Token for pagination + +:return: A `SandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `paginator.next_items()` while `paginator.has_next` is True. + +#### `agentbox.sandbox_sync.main.Sandbox.list_snapshots` + +```python +list_snapshots(limit=None, next_token=None, name=None, **opts) +``` + +List snapshots for this sandbox. + +:param limit: Maximum number of snapshots to return per page +:param next_token: Token for pagination +:param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-project/my-snapshot" or "my-snapshot:v1") + +:return: Paginator for listing snapshots + +#### `agentbox.sandbox_sync.main.Sandbox.pause` + +```python +pause(keep_memory=True, **opts) +``` + +Pause the sandbox. + +:param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot). + +:return: `True` if the sandbox got paused, `False` if the sandbox was already paused + +#### `agentbox.sandbox_sync.main.Sandbox.pty` + +```python +pty: Pty +``` + +Module for interacting with the sandbox pseudo-terminal. + +#### `agentbox.sandbox_sync.main.Sandbox.set_timeout` + +```python +set_timeout(timeout, **opts) +``` + +Set the timeout of the sandbox. +This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.set_timeout`. + +The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. + +:param timeout: Timeout for the sandbox in **seconds** + +#### `agentbox.sandbox_sync.main.Sandbox.update_network` + +```python +update_network(network, **opts) +``` + +Update the network configuration of the sandbox. + +Replaces the current egress configuration atomically — fields that are +omitted are cleared on the server. + +:param network: New network configuration. + +### `agentbox.sandbox_sync.main.logger` + +```python +logger = logging.getLogger(__name__) +``` + diff --git a/reference/sdk/python/templates-async.md b/reference/sdk/python/templates-async.md new file mode 100644 index 00000000..b6175682 --- /dev/null +++ b/reference/sdk/python/templates-async.md @@ -0,0 +1,540 @@ +## `agentbox.template_async.main` + +**Classes:** + +- [**AsyncTemplate**](#agentbox.template_async.main.AsyncTemplate) – Asynchronous template builder for AgentBox sandboxes. + +### `agentbox.template_async.main.AsyncTemplate` + +Bases: [TemplateBase](#agentbox.template.main.TemplateBase) + +Asynchronous template builder for AgentBox sandboxes. + +**Functions:** + +- [**assign_tags**](#agentbox.template_async.main.AsyncTemplate.assign_tags) – Assign tag(s) to an existing template build. +- [**build**](#agentbox.template_async.main.AsyncTemplate.build) – Build and deploy a template to AgentBox infrastructure. +- [**build_in_background**](#agentbox.template_async.main.AsyncTemplate.build_in_background) – Build and deploy a template to AgentBox infrastructure without waiting for completion. +- [**exists**](#agentbox.template_async.main.AsyncTemplate.exists) – Check if a template with the given name exists. +- [**from_alpine_image**](#agentbox.template_async.main.AsyncTemplate.from_alpine_image) – Start template from an Alpine base image. +- [**from_arch_image**](#agentbox.template_async.main.AsyncTemplate.from_arch_image) – Start template from an Arch Linux base image. +- [**from_aws_registry**](#agentbox.template_async.main.AsyncTemplate.from_aws_registry) – Start template from an AWS ECR registry image. +- [**from_base_image**](#agentbox.template_async.main.AsyncTemplate.from_base_image) – Start template from the pinned AgentBox base image. +- [**from_bun_image**](#agentbox.template_async.main.AsyncTemplate.from_bun_image) – Start template from a Bun base image. +- [**from_debian_image**](#agentbox.template_async.main.AsyncTemplate.from_debian_image) – Start template from a Debian base image. +- [**from_dockerfile**](#agentbox.template_async.main.AsyncTemplate.from_dockerfile) – Parse a Dockerfile and convert it to Template SDK format. +- [**from_fedora_image**](#agentbox.template_async.main.AsyncTemplate.from_fedora_image) – Start template from a Fedora base image. +- [**from_gcp_registry**](#agentbox.template_async.main.AsyncTemplate.from_gcp_registry) – Start template from a GCP Artifact Registry or Container Registry image. +- [**from_image**](#agentbox.template_async.main.AsyncTemplate.from_image) – Start template from a Docker image. +- [**from_node_image**](#agentbox.template_async.main.AsyncTemplate.from_node_image) – Start template from a Node.js base image. +- [**from_python_image**](#agentbox.template_async.main.AsyncTemplate.from_python_image) – Start template from a Python base image. +- [**from_template**](#agentbox.template_async.main.AsyncTemplate.from_template) – Start template from an existing AgentBox template. +- [**from_ubuntu_image**](#agentbox.template_async.main.AsyncTemplate.from_ubuntu_image) – Start template from an Ubuntu base image. +- [**get_build_status**](#agentbox.template_async.main.AsyncTemplate.get_build_status) – Get the status of a build. +- [**get_tags**](#agentbox.template_async.main.AsyncTemplate.get_tags) – Get all tags for a template. +- [**remove_tags**](#agentbox.template_async.main.AsyncTemplate.remove_tags) – Remove tag(s) from a template. +- [**skip_cache**](#agentbox.template_async.main.AsyncTemplate.skip_cache) – Skip cache for all subsequent build instructions from this point. +- [**to_dockerfile**](#agentbox.template_async.main.AsyncTemplate.to_dockerfile) – Convert a template to Dockerfile format. +- [**to_json**](#agentbox.template_async.main.AsyncTemplate.to_json) – Convert a template to JSON representation. + +#### `agentbox.template_async.main.AsyncTemplate.assign_tags` + +```python +assign_tags(target_name, tags, **opts) +``` + +Assign tag(s) to an existing template build. + +:param target_name: Template name in 'name:tag' format (the source build to tag from) +:param tags: Tag or tags to assign +:return: TemplateTagInfo with build_id and assigned tags + +Example +```python +from agentbox import AsyncTemplate + +# Assign a single tag +result = await AsyncTemplate.assign_tags('my-template:v1.0', 'production') + +# Assign multiple tags +result = await AsyncTemplate.assign_tags('my-template:v1.0', ['production', 'stable']) +``` + +#### `agentbox.template_async.main.AsyncTemplate.build` + +```python +build( + template, + name, + *, + tags=None, + cpu_count=2, + memory_mb=1024, + skip_cache=False, + on_build_logs=None, + **opts +) +``` + +Build and deploy a template to AgentBox infrastructure. + +:param template: The template to build +:param name: Template name in 'name' or 'name:tag' format +:param tags: Optional additional tags to assign to the template +:param cpu_count: Number of CPUs allocated to the sandbox +:param memory_mb: Amount of memory in MB allocated to the sandbox +:param skip_cache: If True, forces a complete rebuild ignoring cache +:param on_build_logs: Callback function to receive build logs during the build process + +Example +```python +from agentbox import AsyncTemplate + +template = ( + AsyncTemplate() + .from_python_image('3') + .copy('requirements.txt', '/home/user/') + .run_cmd('pip install -r /home/user/requirements.txt') +) + +# Build with single tag +await AsyncTemplate.build(template, 'my-python-env:v1.0') + +# Build with multiple tags +await AsyncTemplate.build(template, 'my-python-env', tags=['v1.1.0', 'stable']) +``` + +#### `agentbox.template_async.main.AsyncTemplate.build_in_background` + +```python +build_in_background( + template, + name, + *, + tags=None, + cpu_count=2, + memory_mb=1024, + skip_cache=False, + on_build_logs=None, + **opts +) +``` + +Build and deploy a template to AgentBox infrastructure without waiting for completion. + +:param template: The template to build +:param name: Template name in 'name' or 'name:tag' format +:param tags: Optional additional tags to assign to the template +:param cpu_count: Number of CPUs allocated to the sandbox +:param memory_mb: Amount of memory in MB allocated to the sandbox +:param skip_cache: If True, forces a complete rebuild ignoring cache +:return: BuildInfo containing the template ID and build ID + +Example +```python +from agentbox import AsyncTemplate + +template = ( + AsyncTemplate() + .from_python_image('3') + .run_cmd('echo "test"') + .set_start_cmd('echo "Hello"', 'sleep 1') +) + +# Build with single tag +build_info = await AsyncTemplate.build_in_background(template, 'my-python-env:v1.0') + +# Build with multiple tags +build_info = await AsyncTemplate.build_in_background(template, 'my-python-env', tags=['v1.1.0', 'stable']) +``` + +#### `agentbox.template_async.main.AsyncTemplate.exists` + +```python +exists(name, **opts) +``` + +Check if a template with the given name exists. + +:param name: Template name to check +:return: True if the name exists, False otherwise + +Example +```python +from agentbox import AsyncTemplate + +exists = await AsyncTemplate.exists('my-python-env') +if exists: + print('Template exists!') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_alpine_image` + +```python +from_alpine_image(variant='3.24') +``` + +Start template from an Alpine base image. + +:param variant: Alpine image variant (default: '3.24') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_alpine_image('3.24') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_arch_image` + +```python +from_arch_image(variant='latest') +``` + +Start template from an Arch Linux base image. + +Defaults to `latest`: Arch is a rolling release and template +provisioning runs `pacman -Syu`, so pinning a tag would not change +the built result. + +:param variant: Arch Linux image variant (default: 'latest') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_arch_image('base-devel') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_aws_registry` + +```python +from_aws_registry(image, access_key_id, secret_access_key, region) +``` + +Start template from an AWS ECR registry image. + +:param image: Docker image name from AWS ECR +:param access_key_id: AWS access key ID +:param secret_access_key: AWS secret access key +:param region: AWS region + +:return: `TemplateBuilder` class + +Example +```python +Template().from_aws_registry( + '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest', + access_key_id='AKIA...', + secret_access_key='...', + region='us-west-2' +) +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_base_image` + +```python +from_base_image() +``` + +Start template from the pinned AgentBox base image. + +:return: `TemplateBuilder` class + +Example +```python +Template().from_base_image() +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_bun_image` + +```python +from_bun_image(variant='latest') +``` + +Start template from a Bun base image. + +:param variant: Bun image variant (default: 'latest') + +:return: `TemplateBuilder` class + +#### `agentbox.template_async.main.AsyncTemplate.from_debian_image` + +```python +from_debian_image(variant='stable') +``` + +Start template from a Debian base image. + +:param variant: Debian image variant + +:return: `TemplateBuilder` class + +Example +```python +Template().from_debian_image('bookworm') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_dockerfile` + +```python +from_dockerfile(dockerfile_content_or_path) +``` + +Parse a Dockerfile and convert it to Template SDK format. + +:param dockerfile_content_or_path: Either the Dockerfile content as a string, or a path to a Dockerfile file + +:return: `TemplateBuilder` class + +Example +```python +Template().from_dockerfile('Dockerfile') +Template().from_dockerfile('FROM python:3\nRUN pip install numpy') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_fedora_image` + +```python +from_fedora_image(variant='44') +``` + +Start template from a Fedora base image. + +:param variant: Fedora image variant (default: '44') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_fedora_image('44') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_gcp_registry` + +```python +from_gcp_registry(image, service_account_json) +``` + +Start template from a GCP Artifact Registry or Container Registry image. + +:param image: Docker image name from GCP registry +:param service_account_json: Service account JSON string, dict, or path to JSON file + +:return: `TemplateBuilder` class + +Example +```python +Template().from_gcp_registry( + 'gcr.io/myproject/myimage:latest', + service_account_json='path/to/service-account.json' +) +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_image` + +```python +from_image(image, username=None, password=None) +``` + +Start template from a Docker image. + +:param image: Docker image name (e.g., 'ubuntu:24.04') +:param username: Username for private registry authentication +:param password: Password for private registry authentication + +:return: `TemplateBuilder` class + +Example +```python +Template().from_image('python:3') + +# With credentials (optional) +Template().from_image('myregistry.com/myimage:latest', username='user', password='pass') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_node_image` + +```python +from_node_image(variant='lts') +``` + +Start template from a Node.js base image. + +:param variant: Node.js image variant (default: 'lts') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_node_image('24') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_python_image` + +```python +from_python_image(version='3') +``` + +Start template from a Python base image. + +:param version: Python version (default: '3') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_python_image('3') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_template` + +```python +from_template(template) +``` + +Start template from an existing AgentBox template. + +:param template: AgentBox template ID or alias + +:return: `TemplateBuilder` class + +Example +```python +Template().from_template('my-base-template') +``` + +#### `agentbox.template_async.main.AsyncTemplate.from_ubuntu_image` + +```python +from_ubuntu_image(variant='latest') +``` + +Start template from an Ubuntu base image. + +:param variant: Ubuntu image variant (default: 'latest') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_ubuntu_image('24.04') +``` + +#### `agentbox.template_async.main.AsyncTemplate.get_build_status` + +```python +get_build_status(build_info, logs_offset=0, **opts) +``` + +Get the status of a build. + +:param build_info: Build identifiers returned from build_in_background +:param logs_offset: Offset for fetching logs +:return: TemplateBuild containing the build status and logs + +Example +```python +from agentbox import AsyncTemplate + +build_info = await AsyncTemplate.build_in_background(template, 'my-template') +status = await AsyncTemplate.get_build_status(build_info, logs_offset=0) +``` + +#### `agentbox.template_async.main.AsyncTemplate.get_tags` + +```python +get_tags(template_id, **opts) +``` + +Get all tags for a template. + +:param template_id: Template ID or name +:return: List of TemplateTag with tag name, build_id, and created_at + +Example +```python +from agentbox import AsyncTemplate + +tags = await AsyncTemplate.get_tags('my-template') +for tag in tags: + print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}") +``` + +#### `agentbox.template_async.main.AsyncTemplate.remove_tags` + +```python +remove_tags(name, tags, **opts) +``` + +Remove tag(s) from a template. + +:param name: Template name +:param tags: Tag or tags to remove + +Example +```python +from agentbox import AsyncTemplate + +# Remove a single tag +await AsyncTemplate.remove_tags('my-template', 'production') + +# Remove multiple tags +await AsyncTemplate.remove_tags('my-template', ['production', 'stable']) +``` + +#### `agentbox.template_async.main.AsyncTemplate.skip_cache` + +```python +skip_cache() +``` + +Skip cache for all subsequent build instructions from this point. + +:return: `TemplateBase` class + +Example +```python +template.skip_cache().from_python_image('3.11') +``` + +#### `agentbox.template_async.main.AsyncTemplate.to_dockerfile` + +```python +to_dockerfile(template) +``` + +Convert a template to Dockerfile format. + +Note: Templates based on other AgentBox templates cannot be converted to Dockerfile. + +:param template: The template to convert (TemplateBuilder or TemplateFinal instance) + +:return: Dockerfile string representation + +:raises ValueError: If the template is based on another AgentBox template or has no base image + +Example +```python +template = Template().from_python_image('3').copy('app.py', '/app/') +dockerfile = TemplateBase.to_dockerfile(template) +``` + +#### `agentbox.template_async.main.AsyncTemplate.to_json` + +```python +to_json(template) +``` + +Convert a template to JSON representation. + +:param template: The template to convert (TemplateBuilder or TemplateFinal instance) + +:return: JSON string representation of the template + +Example +```python +template = Template().from_python_image('3').copy('app.py', '/app/') +json_str = TemplateBase.to_json(template) +``` + diff --git a/reference/sdk/python/templates-sync.md b/reference/sdk/python/templates-sync.md new file mode 100644 index 00000000..ca0eeb20 --- /dev/null +++ b/reference/sdk/python/templates-sync.md @@ -0,0 +1,540 @@ +## `agentbox.template_sync.main` + +**Classes:** + +- [**Template**](#agentbox.template_sync.main.Template) – Synchronous template builder for AgentBox sandboxes. + +### `agentbox.template_sync.main.Template` + +Bases: [TemplateBase](#agentbox.template.main.TemplateBase) + +Synchronous template builder for AgentBox sandboxes. + +**Functions:** + +- [**assign_tags**](#agentbox.template_sync.main.Template.assign_tags) – Assign tag(s) to an existing template build. +- [**build**](#agentbox.template_sync.main.Template.build) – Build and deploy a template to AgentBox infrastructure. +- [**build_in_background**](#agentbox.template_sync.main.Template.build_in_background) – Build and deploy a template to AgentBox infrastructure without waiting for completion. +- [**exists**](#agentbox.template_sync.main.Template.exists) – Check if a template with the given name exists. +- [**from_alpine_image**](#agentbox.template_sync.main.Template.from_alpine_image) – Start template from an Alpine base image. +- [**from_arch_image**](#agentbox.template_sync.main.Template.from_arch_image) – Start template from an Arch Linux base image. +- [**from_aws_registry**](#agentbox.template_sync.main.Template.from_aws_registry) – Start template from an AWS ECR registry image. +- [**from_base_image**](#agentbox.template_sync.main.Template.from_base_image) – Start template from the pinned AgentBox base image. +- [**from_bun_image**](#agentbox.template_sync.main.Template.from_bun_image) – Start template from a Bun base image. +- [**from_debian_image**](#agentbox.template_sync.main.Template.from_debian_image) – Start template from a Debian base image. +- [**from_dockerfile**](#agentbox.template_sync.main.Template.from_dockerfile) – Parse a Dockerfile and convert it to Template SDK format. +- [**from_fedora_image**](#agentbox.template_sync.main.Template.from_fedora_image) – Start template from a Fedora base image. +- [**from_gcp_registry**](#agentbox.template_sync.main.Template.from_gcp_registry) – Start template from a GCP Artifact Registry or Container Registry image. +- [**from_image**](#agentbox.template_sync.main.Template.from_image) – Start template from a Docker image. +- [**from_node_image**](#agentbox.template_sync.main.Template.from_node_image) – Start template from a Node.js base image. +- [**from_python_image**](#agentbox.template_sync.main.Template.from_python_image) – Start template from a Python base image. +- [**from_template**](#agentbox.template_sync.main.Template.from_template) – Start template from an existing AgentBox template. +- [**from_ubuntu_image**](#agentbox.template_sync.main.Template.from_ubuntu_image) – Start template from an Ubuntu base image. +- [**get_build_status**](#agentbox.template_sync.main.Template.get_build_status) – Get the status of a build. +- [**get_tags**](#agentbox.template_sync.main.Template.get_tags) – Get all tags for a template. +- [**remove_tags**](#agentbox.template_sync.main.Template.remove_tags) – Remove tag(s) from a template. +- [**skip_cache**](#agentbox.template_sync.main.Template.skip_cache) – Skip cache for all subsequent build instructions from this point. +- [**to_dockerfile**](#agentbox.template_sync.main.Template.to_dockerfile) – Convert a template to Dockerfile format. +- [**to_json**](#agentbox.template_sync.main.Template.to_json) – Convert a template to JSON representation. + +#### `agentbox.template_sync.main.Template.assign_tags` + +```python +assign_tags(target_name, tags, **opts) +``` + +Assign tag(s) to an existing template build. + +:param target_name: Template name in 'name:tag' format (the source build to tag from) +:param tags: Tag or tags to assign +:return: TemplateTagInfo with build_id and assigned tags + +Example +```python +from agentbox import Template + +# Assign a single tag +result = Template.assign_tags('my-template:v1.0', 'production') + +# Assign multiple tags +result = Template.assign_tags('my-template:v1.0', ['production', 'stable']) +``` + +#### `agentbox.template_sync.main.Template.build` + +```python +build( + template, + name, + *, + tags=None, + cpu_count=2, + memory_mb=1024, + skip_cache=False, + on_build_logs=None, + **opts +) +``` + +Build and deploy a template to AgentBox infrastructure. + +:param template: The template to build +:param name: Template name in 'name' or 'name:tag' format +:param tags: Optional additional tags to assign to the template +:param cpu_count: Number of CPUs allocated to the sandbox +:param memory_mb: Amount of memory in MB allocated to the sandbox +:param skip_cache: If True, forces a complete rebuild ignoring cache +:param on_build_logs: Callback function to receive build logs during the build process + +Example +```python +from agentbox import Template + +template = ( + Template() + .from_python_image('3') + .copy('requirements.txt', '/home/user/') + .run_cmd('pip install -r /home/user/requirements.txt') +) + +# Build with single tag +Template.build(template, 'my-python-env:v1.0') + +# Build with multiple tags +Template.build(template, 'my-python-env', tags=['v1.1.0', 'stable']) +``` + +#### `agentbox.template_sync.main.Template.build_in_background` + +```python +build_in_background( + template, + name, + *, + tags=None, + cpu_count=2, + memory_mb=1024, + skip_cache=False, + on_build_logs=None, + **opts +) +``` + +Build and deploy a template to AgentBox infrastructure without waiting for completion. + +:param template: The template to build +:param name: Template name in 'name' or 'name:tag' format +:param tags: Optional additional tags to assign to the template +:param cpu_count: Number of CPUs allocated to the sandbox +:param memory_mb: Amount of memory in MB allocated to the sandbox +:param skip_cache: If True, forces a complete rebuild ignoring cache +:return: BuildInfo containing the template ID and build ID + +Example +```python +from agentbox import Template + +template = ( + Template() + .from_python_image('3') + .run_cmd('echo "test"') + .set_start_cmd('echo "Hello"', 'sleep 1') +) + +# Build with single tag +build_info = Template.build_in_background(template, 'my-python-env:v1.0') + +# Build with multiple tags +build_info = Template.build_in_background(template, 'my-python-env', tags=['v1.1.0', 'stable']) +``` + +#### `agentbox.template_sync.main.Template.exists` + +```python +exists(name, **opts) +``` + +Check if a template with the given name exists. + +:param name: Template name to check +:return: True if the name exists, False otherwise + +Example +```python +from agentbox import Template + +exists = Template.exists('my-python-env') +if exists: + print('Template exists!') +``` + +#### `agentbox.template_sync.main.Template.from_alpine_image` + +```python +from_alpine_image(variant='3.24') +``` + +Start template from an Alpine base image. + +:param variant: Alpine image variant (default: '3.24') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_alpine_image('3.24') +``` + +#### `agentbox.template_sync.main.Template.from_arch_image` + +```python +from_arch_image(variant='latest') +``` + +Start template from an Arch Linux base image. + +Defaults to `latest`: Arch is a rolling release and template +provisioning runs `pacman -Syu`, so pinning a tag would not change +the built result. + +:param variant: Arch Linux image variant (default: 'latest') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_arch_image('base-devel') +``` + +#### `agentbox.template_sync.main.Template.from_aws_registry` + +```python +from_aws_registry(image, access_key_id, secret_access_key, region) +``` + +Start template from an AWS ECR registry image. + +:param image: Docker image name from AWS ECR +:param access_key_id: AWS access key ID +:param secret_access_key: AWS secret access key +:param region: AWS region + +:return: `TemplateBuilder` class + +Example +```python +Template().from_aws_registry( + '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest', + access_key_id='AKIA...', + secret_access_key='...', + region='us-west-2' +) +``` + +#### `agentbox.template_sync.main.Template.from_base_image` + +```python +from_base_image() +``` + +Start template from the pinned AgentBox base image. + +:return: `TemplateBuilder` class + +Example +```python +Template().from_base_image() +``` + +#### `agentbox.template_sync.main.Template.from_bun_image` + +```python +from_bun_image(variant='latest') +``` + +Start template from a Bun base image. + +:param variant: Bun image variant (default: 'latest') + +:return: `TemplateBuilder` class + +#### `agentbox.template_sync.main.Template.from_debian_image` + +```python +from_debian_image(variant='stable') +``` + +Start template from a Debian base image. + +:param variant: Debian image variant + +:return: `TemplateBuilder` class + +Example +```python +Template().from_debian_image('bookworm') +``` + +#### `agentbox.template_sync.main.Template.from_dockerfile` + +```python +from_dockerfile(dockerfile_content_or_path) +``` + +Parse a Dockerfile and convert it to Template SDK format. + +:param dockerfile_content_or_path: Either the Dockerfile content as a string, or a path to a Dockerfile file + +:return: `TemplateBuilder` class + +Example +```python +Template().from_dockerfile('Dockerfile') +Template().from_dockerfile('FROM python:3\nRUN pip install numpy') +``` + +#### `agentbox.template_sync.main.Template.from_fedora_image` + +```python +from_fedora_image(variant='44') +``` + +Start template from a Fedora base image. + +:param variant: Fedora image variant (default: '44') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_fedora_image('44') +``` + +#### `agentbox.template_sync.main.Template.from_gcp_registry` + +```python +from_gcp_registry(image, service_account_json) +``` + +Start template from a GCP Artifact Registry or Container Registry image. + +:param image: Docker image name from GCP registry +:param service_account_json: Service account JSON string, dict, or path to JSON file + +:return: `TemplateBuilder` class + +Example +```python +Template().from_gcp_registry( + 'gcr.io/myproject/myimage:latest', + service_account_json='path/to/service-account.json' +) +``` + +#### `agentbox.template_sync.main.Template.from_image` + +```python +from_image(image, username=None, password=None) +``` + +Start template from a Docker image. + +:param image: Docker image name (e.g., 'ubuntu:24.04') +:param username: Username for private registry authentication +:param password: Password for private registry authentication + +:return: `TemplateBuilder` class + +Example +```python +Template().from_image('python:3') + +# With credentials (optional) +Template().from_image('myregistry.com/myimage:latest', username='user', password='pass') +``` + +#### `agentbox.template_sync.main.Template.from_node_image` + +```python +from_node_image(variant='lts') +``` + +Start template from a Node.js base image. + +:param variant: Node.js image variant (default: 'lts') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_node_image('24') +``` + +#### `agentbox.template_sync.main.Template.from_python_image` + +```python +from_python_image(version='3') +``` + +Start template from a Python base image. + +:param version: Python version (default: '3') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_python_image('3') +``` + +#### `agentbox.template_sync.main.Template.from_template` + +```python +from_template(template) +``` + +Start template from an existing AgentBox template. + +:param template: AgentBox template ID or alias + +:return: `TemplateBuilder` class + +Example +```python +Template().from_template('my-base-template') +``` + +#### `agentbox.template_sync.main.Template.from_ubuntu_image` + +```python +from_ubuntu_image(variant='latest') +``` + +Start template from an Ubuntu base image. + +:param variant: Ubuntu image variant (default: 'latest') + +:return: `TemplateBuilder` class + +Example +```python +Template().from_ubuntu_image('24.04') +``` + +#### `agentbox.template_sync.main.Template.get_build_status` + +```python +get_build_status(build_info, logs_offset=0, **opts) +``` + +Get the status of a build. + +:param build_info: Build identifiers returned from build_in_background +:param logs_offset: Offset for fetching logs +:return: TemplateBuild containing the build status and logs + +Example +```python +from agentbox import Template + +build_info = Template.build_in_background(template, 'my-template') +status = Template.get_build_status(build_info, logs_offset=0) +``` + +#### `agentbox.template_sync.main.Template.get_tags` + +```python +get_tags(template_id, **opts) +``` + +Get all tags for a template. + +:param template_id: Template ID or name +:return: List of TemplateTag with tag name, build_id, and created_at + +Example +```python +from agentbox import Template + +tags = Template.get_tags('my-template') +for tag in tags: + print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}") +``` + +#### `agentbox.template_sync.main.Template.remove_tags` + +```python +remove_tags(name, tags, **opts) +``` + +Remove tag(s) from a template. + +:param name: Template name +:param tags: Tag or tags to remove + +Example +```python +from agentbox import Template + +# Remove a single tag +Template.remove_tags('my-template', 'production') + +# Remove multiple tags +Template.remove_tags('my-template', ['production', 'stable']) +``` + +#### `agentbox.template_sync.main.Template.skip_cache` + +```python +skip_cache() +``` + +Skip cache for all subsequent build instructions from this point. + +:return: `TemplateBase` class + +Example +```python +template.skip_cache().from_python_image('3.11') +``` + +#### `agentbox.template_sync.main.Template.to_dockerfile` + +```python +to_dockerfile(template) +``` + +Convert a template to Dockerfile format. + +Note: Templates based on other AgentBox templates cannot be converted to Dockerfile. + +:param template: The template to convert (TemplateBuilder or TemplateFinal instance) + +:return: Dockerfile string representation + +:raises ValueError: If the template is based on another AgentBox template or has no base image + +Example +```python +template = Template().from_python_image('3').copy('app.py', '/app/') +dockerfile = TemplateBase.to_dockerfile(template) +``` + +#### `agentbox.template_sync.main.Template.to_json` + +```python +to_json(template) +``` + +Convert a template to JSON representation. + +:param template: The template to convert (TemplateBuilder or TemplateFinal instance) + +:return: JSON string representation of the template + +Example +```python +template = Template().from_python_image('3').copy('app.py', '/app/') +json_str = TemplateBase.to_json(template) +``` + diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py new file mode 100644 index 00000000..39e88d2f --- /dev/null +++ b/scripts/generate-reference.py @@ -0,0 +1,325 @@ +#!/usr/bin/env python3 +"""Build the public documentation contract from checked-in SDK snapshots.""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import shutil +import subprocess +import tempfile +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parents[1] +OUT = ROOT / "reference" +HTTP_METHODS = {"get", "post", "put", "patch", "delete"} + + +def sha256(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def operation_key(method: str, path: str) -> str: + return f"{method.upper()} {path}" + + +def strip_extension(value): + if isinstance(value, dict): + return { + key: strip_extension(item) + for key, item in value.items() + if not key.startswith("x-") + and not (isinstance(item, dict) and item.get("x-not-implemented") is True) + } + if isinstance(value, list): + return [strip_extension(item) for item in value] + return value + + +def build_openapi(name: str, config: dict) -> list[dict]: + source = ROOT / config["source"] + document = yaml.safe_load(source.read_text()) + assigned = config["operations"] + seen = set() + output_paths = {} + + if name == "controlPlane": + public_tags = set(config["publicTags"]) + candidates = set() + for path, path_item in document["paths"].items(): + for method, operation in path_item.items(): + if ( + method not in HTTP_METHODS + or operation.get("deprecated") + or operation.get("x-not-implemented") is True + ): + continue + tags = set(operation.get("tags", [])) + if tags & public_tags: + candidates.add(operation_key(method, path)) + candidates.update( + { + "GET /teams/{teamID}/metrics", + "GET /teams/{teamID}/metrics/max", + } + ) + missing = sorted(candidates - set(assigned)) + if missing: + raise SystemExit( + "Public operations require an id, group and slug:\n " + + "\n ".join(missing) + ) + + records = [] + for path, path_item in document["paths"].items(): + for method, operation in path_item.items(): + key = operation_key(method, path) + if key not in assigned: + continue + metadata = assigned[key] + required = {"id", "group", "slug"} + if set(metadata) != required: + raise SystemExit(f"{key} must define exactly {sorted(required)}") + if metadata["id"] in seen: + raise SystemExit(f"Duplicate operation id: {metadata['id']}") + seen.add(metadata["id"]) + public_operation = strip_extension(operation) + public_operation["operationId"] = metadata["id"] + public_operation["tags"] = [metadata["group"]] + output_paths.setdefault(path, {})[method] = public_operation + records.append( + { + "operationId": metadata["id"], + "method": method.upper(), + "path": path, + "group": metadata["group"], + "slug": metadata["slug"], + "spec": "control-plane" if name == "controlPlane" else "envd", + } + ) + + unknown = sorted( + set(assigned) + - { + operation_key(method, path) + for path, item in document["paths"].items() + for method in item + if method in HTTP_METHODS + } + ) + if unknown: + raise SystemExit( + "Configured operations are missing from the spec:\n " + + "\n ".join(unknown) + ) + + public = strip_extension(document) + public["paths"] = output_paths + public["tags"] = [ + {"name": group} for group in sorted({record["group"] for record in records}) + ] + if "components" in public and "securitySchemes" in public["components"]: + public["components"]["securitySchemes"] = { + key: value + for key, value in public["components"]["securitySchemes"].items() + if key == "ApiKeyAuth" + } + destination = ( + OUT + / "openapi" + / ("control-plane.yml" if name == "controlPlane" else "envd.yml") + ) + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_text(yaml.safe_dump(public, sort_keys=False, allow_unicode=True)) + return sorted(records, key=lambda item: (item["group"], item["slug"])) + + +def proto_reference(source: Path, destination: Path, title: str) -> None: + text = source.read_text() + service_match = re.search(r"service\s+(\w+)\s*\{(.*?)\n\}", text, re.S) + if not service_match: + raise SystemExit(f"No service found in {source}") + service, body = service_match.groups() + rpcs = re.findall( + r"(?:\s*//\s*(.*?)\n)?\s*rpc\s+(\w+)\s*\(([^)]+)\)\s*returns\s*\(([^)]+)\)", + body, + ) + lines = [f"# {title}", "", f"Service: `{service}`", ""] + for comment, name, request, response in rpcs: + lines.extend( + [ + f"## {name}", + "", + comment.strip() if comment else "Public RPC exposed by envd.", + "", + f"- Request: `{request.strip()}`", + f"- Response: `{response.strip()}`", + "", + ] + ) + lines.extend(["## Message types", ""]) + for match in re.finditer( + r"(?:^|\n)(?:\s*//\s*(.*?)\n)?\s*message\s+(\w+)\s*\{", text + ): + comment, name = match.groups() + depth = 1 + cursor = match.end() + while depth and cursor < len(text): + if text[cursor] == "{": + depth += 1 + elif text[cursor] == "}": + depth -= 1 + cursor += 1 + body = text[match.end() : cursor - 1] + fields = re.findall( + r"(?:\s*//\s*(.*?)\n)?\s*(repeated\s+|optional\s+)?([.\w]+)\s+(\w+)\s*=\s*(\d+)", + body, + ) + lines.extend([f"### {name}", ""]) + if comment: + lines.extend([comment.strip(), ""]) + if fields: + lines.extend( + [ + "| Field | Type | Number | Description |", + "| --- | --- | ---: | --- |", + ] + ) + for field_comment, modifier, field_type, field_name, number in fields: + type_name = f"{modifier.strip()} {field_type}".strip() + lines.append( + f"| `{field_name}` | `{type_name}` | {number} | {field_comment.strip() if field_comment else ''} |" + ) + lines.append("") + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_text("\n".join(lines)) + + +def run_sdk_generators() -> None: + groups = json.loads((ROOT / "reference-config/sdk-groups.json").read_text()) + for name, entries in groups["javascript"].items(): + destination = OUT / "sdk/javascript" / name + tsconfig = ( + "packages/code-interpreter-js/tsconfig.json" + if entries[0].startswith("packages/code-interpreter-js/") + else "packages/js-sdk/tsconfig.json" + ) + command = [ + "pnpm", + "exec", + "typedoc", + "--plugin", + "typedoc-plugin-markdown", + "--entryPointStrategy", + "resolve", + "--tsconfig", + tsconfig, + "--readme", + "none", + "--disableSources", + "--hidePageHeader", + "--out", + str(destination), + *entries, + ] + subprocess.run(command, cwd=ROOT, check=True) + + with tempfile.TemporaryDirectory(prefix="agentbox-reference-") as temporary: + python_root = Path(temporary) + shutil.copytree(ROOT / "packages/python-sdk/agentbox", python_root / "agentbox") + shutil.copytree( + ROOT / "packages/code-interpreter-python/agentbox_code_interpreter", + python_root / "agentbox_code_interpreter", + ) + for namespace in ( + "sandbox_sync", + "sandbox_async", + "template", + "template_sync", + "template_async", + ): + (python_root / "agentbox" / namespace / "__init__.py").touch() + + for name, entries in groups["python"].items(): + destination = OUT / "sdk/python" / f"{name}.md" + destination.parent.mkdir(parents=True, exist_ok=True) + command = ["griffe2md", *entries, "-o", str(destination)] + environment = os.environ.copy() + environment["PYTHONPATH"] = os.pathsep.join( + [str(python_root), environment.get("PYTHONPATH", "")] + ) + subprocess.run(command, cwd=ROOT, env=environment, check=True) + + subprocess.run( + ["tsx", "src/reference.ts", str(OUT / "sdk/cli")], + cwd=ROOT / "packages/cli", + check=True, + ) + + +def package_versions() -> dict: + packages = { + "@abox-dev/sdk": ROOT / "packages/js-sdk/package.json", + "@abox-dev/code-interpreter": ROOT + / "packages/code-interpreter-js/package.json", + "@abox-dev/cli": ROOT / "packages/cli/package.json", + } + versions = { + name: json.loads(path.read_text())["version"] for name, path in packages.items() + } + for name, path in { + "abox-sdk": ROOT / "packages/python-sdk/pyproject.toml", + "abox-code-interpreter": ROOT + / "packages/code-interpreter-python/pyproject.toml", + }.items(): + versions[name] = re.search( + r'^version = "([^"]+)"', path.read_text(), re.M + ).group(1) + return versions + + +def main() -> None: + if OUT.exists(): + shutil.rmtree(OUT) + config = yaml.safe_load((ROOT / "reference-config/operations.yaml").read_text()) + operations = [] + operations.extend(build_openapi("controlPlane", config["controlPlane"])) + operations.extend(build_openapi("envd", config["envd"])) + (OUT / "openapi/operations.json").write_text( + json.dumps(operations, indent=2) + "\n" + ) + proto_reference( + ROOT / "spec/envd/process/process.proto", + OUT / "connect/process.md", + "Process API", + ) + proto_reference( + ROOT / "spec/envd/filesystem/filesystem.proto", + OUT / "connect/filesystem.md", + "Filesystem API", + ) + run_sdk_generators() + + source = json.loads((ROOT / "spec/source.json").read_text()) + files = { + str(path.relative_to(OUT)): sha256(path) + for path in sorted(OUT.rglob("*")) + if path.is_file() + } + manifest = { + "schemaVersion": config["schemaVersion"], + "packages": package_versions(), + "monoRevision": source["revision"], + "files": files, + } + (OUT / "manifest.json").write_text( + json.dumps(manifest, indent=2, sort_keys=True) + "\n" + ) + + +if __name__ == "__main__": + main() diff --git a/scripts/test-reference-contract.py b/scripts/test-reference-contract.py new file mode 100644 index 00000000..72b07ea6 --- /dev/null +++ b/scripts/test-reference-contract.py @@ -0,0 +1,73 @@ +#!/usr/bin/env python3 +"""Fast assertions for the generated public documentation contract.""" + +import hashlib +import json +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parents[1] +REFERENCE = ROOT / "reference" +BANNED_PATH_PARTS = ("/admin/", "/access-tokens", "/api-keys", "/volumes") +BANNED_ENVD_PATHS = { + "/init", + "/freeze", + "/unfreeze", + "/collapse", + "/fsfreeze", + "/fsthaw", +} + + +def main() -> None: + manifest = json.loads((REFERENCE / "manifest.json").read_text()) + assert manifest["schemaVersion"] == 1 + for relative, expected in manifest["files"].items(): + actual = hashlib.sha256((REFERENCE / relative).read_bytes()).hexdigest() + assert actual == expected, relative + + operations = json.loads((REFERENCE / "openapi/operations.json").read_text()) + ids = [operation["operationId"] for operation in operations] + routes = { + (operation["spec"], operation["method"], operation["path"]) + for operation in operations + } + assert len(ids) == len(set(ids)), "operationId values must be unique" + assert not any( + part in operation["path"] + for operation in operations + for part in BANNED_PATH_PARTS + ) + assert not any(operation["path"] in BANNED_ENVD_PATHS for operation in operations) + + config = yaml.safe_load((ROOT / "reference-config/operations.yaml").read_text()) + control = yaml.safe_load((ROOT / config["controlPlane"]["source"]).read_text()) + public_tags = set(config["controlPlane"]["publicTags"]) + expected = set() + for path, path_item in control["paths"].items(): + for method, operation in path_item.items(): + if method not in {"get", "post", "put", "patch", "delete"}: + continue + if operation.get("deprecated") or operation.get("x-not-implemented"): + continue + if set(operation.get("tags", [])) & public_tags: + expected.add(("control-plane", method.upper(), path)) + expected.update( + { + ("control-plane", "GET", "/teams/{teamID}/metrics"), + ("control-plane", "GET", "/teams/{teamID}/metrics/max"), + } + ) + assert expected == {route for route in routes if route[0] == "control-plane"} + + rendered_specs = "\n".join( + (REFERENCE / name).read_text() + for name in ("openapi/control-plane.yml", "openapi/envd.yml") + ) + assert "x-not-implemented" not in rendered_specs + assert "SandboxEgressProxyConfig" not in rendered_specs + + +if __name__ == "__main__": + main() From 420ca4b69540cc00c8891d5bddf8bed997c6f6f2 Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Mon, 31 Aug 2026 14:41:11 +0300 Subject: [PATCH 2/3] docs: make code interpreter reference self-contained --- reference-config/typedoc.code-interpreter.json | 11 +++++++++++ reference/manifest.json | 2 +- .../code-interpreter/sandbox/classes/Sandbox.md | 14 +++++++------- scripts/generate-reference.py | 2 +- 4 files changed, 20 insertions(+), 9 deletions(-) create mode 100644 reference-config/typedoc.code-interpreter.json diff --git a/reference-config/typedoc.code-interpreter.json b/reference-config/typedoc.code-interpreter.json new file mode 100644 index 00000000..28215503 --- /dev/null +++ b/reference-config/typedoc.code-interpreter.json @@ -0,0 +1,11 @@ +{ + "extends": "../packages/code-interpreter-js/tsconfig.json", + "compilerOptions": { + "baseUrl": "..", + "rootDir": "..", + "ignoreDeprecations": "6.0", + "paths": { + "@abox-dev/sdk": ["packages/js-sdk/src/index.ts"] + } + } +} diff --git a/reference/manifest.json b/reference/manifest.json index 9c10826e..8afbbca3 100644 --- a/reference/manifest.json +++ b/reference/manifest.json @@ -36,7 +36,7 @@ "sdk/javascript/code-interpreter/messaging/type-aliases/MIMEType.md": "e83e73d6a0e97763e7e82b736871be2363b73f078d500b0f753d0d5085a6737c", "sdk/javascript/code-interpreter/messaging/type-aliases/RawData.md": "1d4c93b749bebbb87e1f2b4a335528adb16f98360a24550c1fbb4d2056ca3c9b", "sdk/javascript/code-interpreter/sandbox/README.md": "ce7ff81b5b0bc706ab215ebbb971aac7951fbcd82959c0884fff8c84f0aae33a", - "sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md": "00b255364c5db61830b4fbe58c2dcf32aa80735b7c31ba9d4c07fe1552a45cbd", + "sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md": "953be987b9939a4d498e04e2c9d9e8bd6fe3312ca7aa33add9a2cf8b0537a176", "sdk/javascript/code-interpreter/sandbox/interfaces/CreateCodeContextOpts.md": "9077fc89c2bc9589e19112b63158ad55cd4d75c52879af93d3b65dd391fc1eaf", "sdk/javascript/code-interpreter/sandbox/interfaces/RunCodeOpts.md": "b7518d5d91a0def0d7f2f10bb4153a76969f0c0c049cac930519342d93c64556", "sdk/javascript/code-interpreter/sandbox/type-aliases/Context.md": "01a1570ac3f1870cb303215203b7b3dddf26bfcf5cc53c863bb65ea493956825", diff --git a/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md b/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md index f5b6e2ad..cd891f63 100644 --- a/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md +++ b/reference/sdk/javascript/code-interpreter/sandbox/classes/Sandbox.md @@ -143,7 +143,7 @@ Traffic access token for accessing sandbox services with restricted public traff ### defaultMcpTemplate -> `protected` `readonly` `static` **defaultMcpTemplate**: `string` +> `protected` `readonly` `static` **defaultMcpTemplate**: `string` = `'mcp-gateway'` #### Inherited from @@ -153,7 +153,7 @@ Traffic access token for accessing sandbox services with restricted public traff ### defaultSandboxTimeoutMs -> `protected` `readonly` `static` **defaultSandboxTimeoutMs**: `300000` = `300000` +> `protected` `readonly` `static` **defaultSandboxTimeoutMs**: `300000` = `DEFAULT_SANDBOX_TIMEOUT_MS` #### Inherited from @@ -416,7 +416,7 @@ Get sandbox information like sandbox ID, template, metadata, started at/end at d ##### opts? -`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> +`Pick`\<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`\> connection options. @@ -504,7 +504,7 @@ Check if the sandbox is running. ##### opts? -`Pick`\<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`\> +`Pick`\<`ConnectionOpts`, `"signal"` \| `"requestTimeoutMs"`\> #### Returns @@ -538,7 +538,7 @@ Kill the sandbox. ##### opts? -`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> +`Pick`\<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`\> connection options. @@ -762,7 +762,7 @@ timeout in **milliseconds**. ##### opts? -`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> +`Pick`\<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`\> connection options. @@ -795,7 +795,7 @@ new network configuration. ##### opts? -`Pick`\<`SandboxOpts`, `"requestTimeoutMs"` \| `"signal"`\> +`Pick`\<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`\> connection options. diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py index 39e88d2f..ad4dfab6 100644 --- a/scripts/generate-reference.py +++ b/scripts/generate-reference.py @@ -204,7 +204,7 @@ def run_sdk_generators() -> None: for name, entries in groups["javascript"].items(): destination = OUT / "sdk/javascript" / name tsconfig = ( - "packages/code-interpreter-js/tsconfig.json" + "reference-config/typedoc.code-interpreter.json" if entries[0].startswith("packages/code-interpreter-js/") else "packages/js-sdk/tsconfig.json" ) From b9ef520cb204178b52f036fca367966bba93bee0 Mon Sep 17 00:00:00 2001 From: Ilyas Salikhov Date: Mon, 31 Aug 2026 14:45:57 +0300 Subject: [PATCH 3/3] docs: make CLI reference self-contained --- reference-config/cli-reference.json | 13 +++++++++++++ scripts/generate-reference.py | 8 +++++++- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 reference-config/cli-reference.json diff --git a/reference-config/cli-reference.json b/reference-config/cli-reference.json new file mode 100644 index 00000000..364d1b2a --- /dev/null +++ b/reference-config/cli-reference.json @@ -0,0 +1,13 @@ +{ + "extends": "../packages/cli/tsconfig.json", + "compilerOptions": { + "baseUrl": "..", + "rootDir": "..", + "ignoreDeprecations": "6.0", + "paths": { + "@abox-dev/sdk": ["packages/js-sdk/src/index.ts"], + "src": ["packages/cli/src/index.ts"], + "src/*": ["packages/cli/src/*"] + } + } +} diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py index ad4dfab6..dff79d38 100644 --- a/scripts/generate-reference.py +++ b/scripts/generate-reference.py @@ -255,7 +255,13 @@ def run_sdk_generators() -> None: subprocess.run(command, cwd=ROOT, env=environment, check=True) subprocess.run( - ["tsx", "src/reference.ts", str(OUT / "sdk/cli")], + [ + "tsx", + "--tsconfig", + "../../reference-config/cli-reference.json", + "src/reference.ts", + str(OUT / "sdk/cli"), + ], cwd=ROOT / "packages/cli", check=True, )