diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 769fae4c..0395267a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -46,7 +46,7 @@ jobs:
- run: pnpm test
- run: go mod tidy && git diff --exit-code -- go.mod go.sum
working-directory: packages/go-sdk
- - run: make check-agent-instructions go-format-check go-vet go-coverage go-consumer-check
+ - run: make check-agent-instructions go-format-check go-doc-check go-vet go-coverage go-consumer-check
go-test:
runs-on: ubuntu-24.04
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b693ee79..49ea88e5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -149,3 +149,24 @@ jobs:
go mod init example.com/agentbox-release-smoke
GOPROXY=https://proxy.golang.org go get "github.com/abox-dev/sdk/packages/go-sdk@${GITHUB_REF_NAME}"
go test github.com/abox-dev/sdk/packages/go-sdk github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter
+ - name: Wait for pkg.go.dev reference pages
+ env:
+ VERSION: ${{ github.ref_name }}
+ run: |
+ for package in \
+ "github.com/abox-dev/sdk/packages/go-sdk" \
+ "github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter"
+ do
+ url="https://pkg.go.dev/${package}@${VERSION}"
+ available=false
+ for attempt in $(seq 1 30)
+ do
+ if curl --fail --silent --show-error --location --output /dev/null "$url"
+ then
+ available=true
+ break
+ fi
+ sleep 20
+ done
+ test "$available" = true
+ done
diff --git a/CLAUDE.md b/CLAUDE.md
index b67c570c..2bbeea5c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,9 +2,10 @@ Use pnpm for JavaScript packages, uv for Python packages, and Go modules for Go
Use English exclusively in source code, comments, documentation, commit messages, and GitHub pull request titles and descriptions.
Keep the JavaScript, Python sync/async, and Go SDKs behaviorally aligned, including their Code Interpreter APIs.
Use only Go syntax and runtime dependencies compatible with the `go` directive in `packages/go-sdk/go.mod`.
-Run format checks, lint, type checks, unit tests, deterministic generation, builds, package-install checks, and the Go race and coverage checks before committing. Handwritten Go code must keep at least 90% statement coverage; generated packages are excluded from the threshold.
+Run format checks, lint, type checks, unit tests, deterministic generation, builds, package-install checks, the exported GoDoc gate, and the Go race and coverage checks before committing. Handwritten Go code must keep at least 90% statement coverage; generated packages are excluded from the threshold.
The API and envd snapshots under spec/ are generated from mono/infra. Do not edit them manually. Update them with `make sync-specs MONO_DIR=/path/to/mono`, then run `make generate`.
Generated clients must depend only on checked-in snapshots and never fetch network content during generation. Do not edit generated Go files under `packages/go-sdk/internal/gen` manually.
+Generated SDK reference files under `reference/`, including `reference/sdk/go`, are owned by `make generate`; do not edit them manually. Keep `gomarkdoc` pinned as a build-only tool and do not emit source links to a floating branch.
Public APIs, package artifacts, examples, errors, environment variables, and headers must use AgentBox naming. Upstream names are allowed only in licenses, attribution, pinned build-only codegen tooling, and wire/protobuf namespaces that are required by the runtime protocol.
Default development credentials may be stored in `.env.local` or `~/.agentbox/config.json`; never print or commit them.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8980f29c..d48761da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,6 @@
Open an issue or pull request at [abox-dev/sdk](https://github.com/abox-dev/sdk). Include tests for behavior changes and keep JavaScript, Python sync/async, and Go APIs aligned where applicable.
-For Go changes, run `make go-check`. Generated clients under `packages/go-sdk/internal/gen` must be regenerated with `make generate` and must not be edited manually. `packages/go-sdk/go.mod` defines the minimum supported Go version; CI also tests every newer supported minor listed in `RELEASING.md`.
+For Go changes, run `make go-check`. It includes the exported GoDoc gate. Generated clients under `packages/go-sdk/internal/gen` and Go reference pages under `reference/sdk/go` must be regenerated with `make generate` and must not be edited manually. `packages/go-sdk/go.mod` defines the minimum supported Go version; CI also tests every newer supported minor listed in `RELEASING.md`.
Use the development and generation commands documented in the root README. By contributing, you agree that your contribution is licensed under the license applicable to the package you modify.
diff --git a/Makefile b/Makefile
index 62e85b57..d84072ea 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@ CODEGEN_IMAGE ?= agentbox-sdk-codegen
.PHONY: generate generate-in-container generate-go codegen-image sync-specs \
go-format-check go-vet go-build go-test go-race go-coverage \
- go-integration go-consumer-check go-check check-agent-instructions
+ go-doc-check go-integration go-consumer-check go-check check-agent-instructions
# Generate exclusively from the checked-in snapshots under spec/.
generate: codegen-image
@@ -33,6 +33,10 @@ check-agent-instructions:
go-format-check:
cd packages/go-sdk && ./scripts/check-go-format.sh
+ test -z "$$(gofmt -l scripts/check-go-docs.go)"
+
+go-doc-check:
+ go run ./scripts/check-go-docs.go packages/go-sdk packages/go-sdk/codeinterpreter
go-vet:
cd packages/go-sdk && go vet ./...
@@ -55,7 +59,7 @@ go-integration:
go-consumer-check:
cd packages/go-sdk && ./scripts/test-go-consumer.sh
-go-check: check-agent-instructions go-format-check go-vet go-build go-test go-race go-coverage go-consumer-check
+go-check: check-agent-instructions go-format-check go-doc-check go-vet go-build go-test go-race go-coverage go-consumer-check
# Maintainer-only update from a local mono checkout.
sync-specs:
diff --git a/RELEASING.md b/RELEASING.md
index 10557031..6dcff186 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -41,9 +41,9 @@ node scripts/check-release-versions.mjs vX.Y.Z
```
`release:version` updates the five workspace manifests, both Python
-`pyproject.toml` files, and `packages/go-sdk/version.go`. Regenerate both Python lock files
-rather than editing them by hand. Do not release any SDK packages at different
-versions.
+`pyproject.toml` files, `packages/go-sdk/version.go`, and the versioned
+pkg.go.dev links in the Go README. Regenerate both Python lock files rather than
+editing them by hand. Do not release any SDK packages at different versions.
## 3. Verify source and release artifacts
@@ -109,7 +109,8 @@ the tagged Go submodule. The `packages/go-sdk/vX.Y.Z` and `vX.Y.Z` tags must
point to the same commit. Go has no separate registry account or archive: the
immutable Git tag and Go checksum database are its published artifact. An
existing registry file is accepted only when its digest matches the newly built
-artifact.
+artifact. The release workflow also waits for the versioned core and Code
+Interpreter pages to become available on pkg.go.dev.
## 6. Verify the published packages
@@ -122,6 +123,10 @@ packages into clean environments and repeat the KVM suite:
Also verify a clean Go consumer with
`GOPROXY=https://proxy.golang.org go get github.com/abox-dev/sdk/packages/go-sdk@vX.Y.Z`.
+Confirm both versioned reference pages:
+
+- `https://pkg.go.dev/github.com/abox-dev/sdk/packages/go-sdk@vX.Y.Z`;
+- `https://pkg.go.dev/github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter@vX.Y.Z`.
Supported Go CI versions are 1.24.x, 1.25.x, 1.26.x, and 1.27.x. Builds and
hermetic tests run on every row; race and coverage run on 1.27.x, while
diff --git a/codegen.Dockerfile b/codegen.Dockerfile
index 66953558..c54a489f 100644
--- a/codegen.Dockerfile
+++ b/codegen.Dockerfile
@@ -4,7 +4,8 @@ FROM golang:1.24.13 AS go-tools
RUN go install github.com/bufbuild/buf/cmd/buf@v1.50.1 && \
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.12 && \
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@v1.19.1 && \
- go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.7.2
+ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.7.2 && \
+ go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@v1.1.0
FROM python:3.10
diff --git a/packages/go-sdk/README.md b/packages/go-sdk/README.md
index eb2e34c3..6cfa0d7b 100644
--- a/packages/go-sdk/README.md
+++ b/packages/go-sdk/README.md
@@ -44,6 +44,9 @@ func main() {
Code Interpreter is available from
`github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter`.
+API reference for this release: [core SDK on pkg.go.dev](https://pkg.go.dev/github.com/abox-dev/sdk/packages/go-sdk@v0.1.2) and
+[Code Interpreter on pkg.go.dev](https://pkg.go.dev/github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter@v0.1.2).
+
Documentation: [core SDK](https://docs.agentbox.ru/en/sdk/),
[sandboxes](https://docs.agentbox.ru/en/sdk/sandboxes/),
[templates](https://docs.agentbox.ru/en/sdk/templates/), and
diff --git a/packages/go-sdk/codeinterpreter/client.go b/packages/go-sdk/codeinterpreter/client.go
index a5a55077..c1b92a46 100644
--- a/packages/go-sdk/codeinterpreter/client.go
+++ b/packages/go-sdk/codeinterpreter/client.go
@@ -18,7 +18,9 @@ import (
)
const (
- DefaultTemplate = "code-interpreter"
+ // DefaultTemplate is the template used when Create receives no template.
+ DefaultTemplate = "code-interpreter"
+ // JupyterPort is the internal Code Interpreter service port.
JupyterPort = 49999
defaultExecutionTimeout = time.Minute
)
@@ -26,6 +28,7 @@ const (
// Client wraps the core client with Code Interpreter creation helpers.
type Client struct{ Core *agentbox.Client }
+// NewClient creates a Code Interpreter client using the core client options.
func NewClient(options ...agentbox.ClientOption) (*Client, error) {
client, err := agentbox.NewClient(options...)
if err != nil {
@@ -37,6 +40,7 @@ func NewClient(options ...agentbox.ClientOption) (*Client, error) {
// Sandbox is a core sandbox with notebook-kernel APIs.
type Sandbox struct{ *agentbox.Sandbox }
+// Create creates a Code Interpreter sandbox.
func (client *Client) Create(ctx context.Context, options *agentbox.CreateSandboxOptions) (*Sandbox, error) {
if options == nil {
options = &agentbox.CreateSandboxOptions{}
@@ -53,6 +57,8 @@ func (client *Client) Create(ctx context.Context, options *agentbox.CreateSandbo
}
return &Sandbox{Sandbox: sandbox}, nil
}
+
+// Connect attaches to an existing Code Interpreter sandbox.
func (client *Client) Connect(ctx context.Context, id string, options *agentbox.ConnectSandboxOptions) (*Sandbox, error) {
sandbox, err := client.Core.Sandboxes.Connect(ctx, id, options)
if err != nil {
@@ -65,8 +71,11 @@ func (client *Client) Connect(ctx context.Context, id string, options *agentbox.
type Language string
const (
- Python Language = "python"
+ // Python selects a Python kernel.
+ Python Language = "python"
+ // JavaScript selects a JavaScript kernel.
JavaScript Language = "javascript"
+ // TypeScript selects a TypeScript kernel.
TypeScript Language = "typescript"
)
@@ -76,6 +85,8 @@ type Context struct {
Language string `json:"language"`
Cwd string `json:"cwd"`
}
+
+// CreateContextOptions configures a persistent kernel context.
type CreateContextOptions struct {
Language Language `json:"language,omitempty"`
Cwd string `json:"cwd,omitempty"`
@@ -170,6 +181,7 @@ func (sandbox *Sandbox) RunCode(ctx context.Context, code string, options *RunCo
return execution, nil
}
+// CreateContext creates a persistent kernel context.
func (sandbox *Sandbox) CreateContext(ctx context.Context, options *CreateContextOptions) (*Context, error) {
if options == nil {
options = &CreateContextOptions{}
@@ -180,6 +192,8 @@ func (sandbox *Sandbox) CreateContext(ctx context.Context, options *CreateContex
}
return &result, nil
}
+
+// ListContexts returns all persistent kernel contexts in the sandbox.
func (sandbox *Sandbox) ListContexts(ctx context.Context) ([]Context, error) {
var result []Context
if err := sandbox.contextRequest(ctx, http.MethodGet, "/contexts", nil, 0, &result); err != nil {
@@ -187,12 +201,16 @@ func (sandbox *Sandbox) ListContexts(ctx context.Context) ([]Context, error) {
}
return result, nil
}
+
+// RemoveContext removes a persistent kernel context.
func (sandbox *Sandbox) RemoveContext(ctx context.Context, contextID string) error {
if strings.TrimSpace(contextID) == "" {
return &agentbox.InvalidArgumentError{Message: "context ID cannot be empty"}
}
return sandbox.contextRequest(ctx, http.MethodDelete, "/contexts/"+url.PathEscape(contextID), nil, 0, nil)
}
+
+// RestartContext restarts a persistent kernel context.
func (sandbox *Sandbox) RestartContext(ctx context.Context, contextID string) error {
if strings.TrimSpace(contextID) == "" {
return &agentbox.InvalidArgumentError{Message: "context ID cannot be empty"}
diff --git a/packages/go-sdk/codeinterpreter/models.go b/packages/go-sdk/codeinterpreter/models.go
index 7754ea05..7ab6c661 100644
--- a/packages/go-sdk/codeinterpreter/models.go
+++ b/packages/go-sdk/codeinterpreter/models.go
@@ -14,6 +14,7 @@ type OutputMessage struct {
Error bool
}
+// String returns the output line.
func (message OutputMessage) String() string { return message.Line }
// ExecutionError is a kernel error and traceback.
@@ -23,12 +24,16 @@ type ExecutionError struct {
Traceback string `json:"traceback"`
}
+// Error formats the kernel error name and value.
func (e ExecutionError) Error() string { return fmt.Sprintf("%s: %s", e.Name, e.Value) }
+// Logs contains collected standard output and standard error lines.
type Logs struct {
Stdout []string `json:"stdout"`
Stderr []string `json:"stderr"`
}
+
+// Execution contains the complete result of one code execution.
type Execution struct {
Results []Result `json:"results"`
Logs Logs `json:"logs"`
@@ -36,6 +41,7 @@ type Execution struct {
ExecutionCount int `json:"execution_count,omitempty"`
}
+// Text returns the text representation of the main result, if present.
func (execution Execution) Text() string {
for _, result := range execution.Results {
if result.IsMainResult {
@@ -47,6 +53,8 @@ func (execution Execution) Text() string {
// RawData preserves every MIME representation returned by the kernel.
type RawData map[string]json.RawMessage
+
+// Result contains the decoded and raw MIME representations of one result.
type Result struct {
Text, HTML, Markdown, SVG, PNG, JPEG, PDF, LaTeX, JSON, JavaScript string
Data map[string]any
@@ -56,6 +64,7 @@ type Result struct {
IsMainResult bool
}
+// Formats returns the available raw MIME keys in sorted order.
func (result Result) Formats() []string {
formats := make([]string, 0, len(result.Raw))
for key := range result.Raw {
@@ -65,30 +74,48 @@ func (result Result) Formats() []string {
return formats
}
+// ChartType identifies a supported chart representation.
type ChartType string
const (
- ChartLine ChartType = "line"
- ChartScatter ChartType = "scatter"
- ChartBar ChartType = "bar"
- ChartPie ChartType = "pie"
+ // ChartLine identifies a line chart.
+ ChartLine ChartType = "line"
+ // ChartScatter identifies a scatter chart.
+ ChartScatter ChartType = "scatter"
+ // ChartBar identifies a bar chart.
+ ChartBar ChartType = "bar"
+ // ChartPie identifies a pie chart.
+ ChartPie ChartType = "pie"
+ // ChartBoxAndWhisker identifies a box-and-whisker chart.
ChartBoxAndWhisker ChartType = "box_and_whisker"
- ChartSuper ChartType = "superchart"
- ChartUnknown ChartType = "unknown"
+ // ChartSuper identifies a composite chart.
+ ChartSuper ChartType = "superchart"
+ // ChartUnknown identifies a chart type unknown to this SDK version.
+ ChartUnknown ChartType = "unknown"
)
+// ScaleType identifies a chart axis scale.
type ScaleType string
const (
- ScaleLinear ScaleType = "linear"
- ScaleDatetime ScaleType = "datetime"
+ // ScaleLinear identifies a linear scale.
+ ScaleLinear ScaleType = "linear"
+ // ScaleDatetime identifies a date and time scale.
+ ScaleDatetime ScaleType = "datetime"
+ // ScaleCategorical identifies a categorical scale.
ScaleCategorical ScaleType = "categorical"
- ScaleLog ScaleType = "log"
- ScaleSymlog ScaleType = "symlog"
- ScaleLogit ScaleType = "logit"
- ScaleFunction ScaleType = "function"
+ // ScaleLog identifies a logarithmic scale.
+ ScaleLog ScaleType = "log"
+ // ScaleSymlog identifies a symmetric logarithmic scale.
+ ScaleSymlog ScaleType = "symlog"
+ // ScaleLogit identifies a logit scale.
+ ScaleLogit ScaleType = "logit"
+ // ScaleFunction identifies a custom function scale.
+ ScaleFunction ScaleType = "function"
+ // ScaleFunctionLog identifies a logarithmic custom function scale.
ScaleFunctionLog ScaleType = "functionlog"
- ScaleAsinh ScaleType = "asinh"
+ // ScaleAsinh identifies an inverse hyperbolic sine scale.
+ ScaleAsinh ScaleType = "asinh"
)
// Chart retains typed common chart properties and unknown fields in Extra.
@@ -105,6 +132,7 @@ type Chart struct {
Extra map[string]json.RawMessage `json:"-"`
}
+// UnmarshalJSON decodes known chart fields and preserves unknown fields in Extra.
func (chart *Chart) UnmarshalJSON(data []byte) error {
type wire Chart
var value wire
diff --git a/packages/go-sdk/commands.go b/packages/go-sdk/commands.go
index c9dce3ca..dc10fbd1 100644
--- a/packages/go-sdk/commands.go
+++ b/packages/go-sdk/commands.go
@@ -43,6 +43,7 @@ type CommandExitError struct {
Message string
}
+// Error describes the non-zero command exit code.
func (e *CommandExitError) Error() string {
if e.Message != "" {
return fmt.Sprintf("agentbox: command exited with code %d: %s", e.Result.ExitCode, e.Message)
diff --git a/packages/go-sdk/errors.go b/packages/go-sdk/errors.go
index 0cd865c9..5665045b 100644
--- a/packages/go-sdk/errors.go
+++ b/packages/go-sdk/errors.go
@@ -10,6 +10,7 @@ type APIError struct {
Cause error
}
+// Error formats the AgentBox API failure.
func (e *APIError) Error() string {
if e.StatusCode != 0 {
return fmt.Sprintf("agentbox: %d: %s", e.StatusCode, e.Message)
@@ -17,30 +18,43 @@ func (e *APIError) Error() string {
return "agentbox: " + e.Message
}
+// Unwrap returns the underlying request error, if any.
func (e *APIError) Unwrap() error { return e.Cause }
// SandboxError is the base error for sandbox operations.
type SandboxError struct{ APIError }
+// Error formats the sandbox operation failure.
func (e *SandboxError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying sandbox operation error, if any.
func (e *SandboxError) Unwrap() error { return e.APIError.Unwrap() }
// AuthenticationError reports missing or invalid credentials.
type AuthenticationError struct{ APIError }
+// Error formats the authentication failure.
func (e *AuthenticationError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying authentication error, if any.
func (e *AuthenticationError) Unwrap() error { return e.APIError.Unwrap() }
// RateLimitError reports an exhausted API quota.
type RateLimitError struct{ APIError }
+// Error formats the rate-limit failure.
func (e *RateLimitError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying rate-limit error, if any.
func (e *RateLimitError) Unwrap() error { return e.APIError.Unwrap() }
// TimeoutError reports a request, execution, or sandbox timeout.
type TimeoutError struct{ APIError }
+// Error formats the timeout failure.
func (e *TimeoutError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying timeout error, if any.
func (e *TimeoutError) Unwrap() error { return e.APIError.Unwrap() }
// InvalidArgumentError reports invalid SDK input.
@@ -49,41 +63,62 @@ type InvalidArgumentError struct {
Cause error
}
+// Error formats the invalid argument failure.
func (e *InvalidArgumentError) Error() string { return "agentbox: " + e.Message }
+
+// Unwrap returns the underlying validation error, if any.
func (e *InvalidArgumentError) Unwrap() error { return e.Cause }
// FileNotFoundError reports a missing sandbox file.
type FileNotFoundError struct{ APIError }
+// Error formats the missing-file failure.
func (e *FileNotFoundError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying missing-file error, if any.
func (e *FileNotFoundError) Unwrap() error { return e.APIError.Unwrap() }
// NotEnoughSpaceError reports exhausted sandbox storage.
type NotEnoughSpaceError struct{ APIError }
+// Error formats the storage-capacity failure.
func (e *NotEnoughSpaceError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying storage error, if any.
func (e *NotEnoughSpaceError) Unwrap() error { return e.APIError.Unwrap() }
// SandboxNotFoundError reports a missing or expired sandbox.
type SandboxNotFoundError struct{ APIError }
+// Error formats the missing-sandbox failure.
func (e *SandboxNotFoundError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying missing-sandbox error, if any.
func (e *SandboxNotFoundError) Unwrap() error { return e.APIError.Unwrap() }
// TemplateError reports an invalid or incompatible template.
type TemplateError struct{ APIError }
+// Error formats the template operation failure.
func (e *TemplateError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying template operation error, if any.
func (e *TemplateError) Unwrap() error { return e.APIError.Unwrap() }
// BuildError reports a failed template build.
type BuildError struct{ APIError }
+// Error formats the template build failure.
func (e *BuildError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying template build error, if any.
func (e *BuildError) Unwrap() error { return e.APIError.Unwrap() }
// FileUploadError reports a failed template file upload.
type FileUploadError struct{ APIError }
+// Error formats the file upload failure.
func (e *FileUploadError) Error() string { return e.APIError.Error() }
+
+// Unwrap returns the underlying file upload error, if any.
func (e *FileUploadError) Unwrap() error { return e.APIError.Unwrap() }
diff --git a/packages/go-sdk/filesystem.go b/packages/go-sdk/filesystem.go
index b615b17c..01eed14b 100644
--- a/packages/go-sdk/filesystem.go
+++ b/packages/go-sdk/filesystem.go
@@ -28,9 +28,12 @@ import (
type FileType string
const (
- FileTypeFile FileType = "file"
+ // FileTypeFile identifies a regular file.
+ FileTypeFile FileType = "file"
+ // FileTypeDirectory identifies a directory.
FileTypeDirectory FileType = "dir"
- FileTypeSymlink FileType = "symlink"
+ // FileTypeSymlink identifies a symbolic link.
+ FileTypeSymlink FileType = "symlink"
)
// EntryInfo describes a sandbox filesystem entry.
diff --git a/packages/go-sdk/models.go b/packages/go-sdk/models.go
index 6f857535..0382aff8 100644
--- a/packages/go-sdk/models.go
+++ b/packages/go-sdk/models.go
@@ -10,8 +10,10 @@ import (
type SandboxState string
const (
+ // SandboxRunning indicates that a sandbox accepts requests.
SandboxRunning SandboxState = "running"
- SandboxPaused SandboxState = "paused"
+ // SandboxPaused indicates that a sandbox is suspended.
+ SandboxPaused SandboxState = "paused"
)
// SandboxMetadata contains user-defined sandbox metadata.
@@ -121,10 +123,14 @@ type SandboxLogEntry struct {
type TemplateBuildStatus string
const (
- BuildWaiting TemplateBuildStatus = "waiting"
+ // BuildWaiting indicates that a template build is queued.
+ BuildWaiting TemplateBuildStatus = "waiting"
+ // BuildBuilding indicates that a template build is in progress.
BuildBuilding TemplateBuildStatus = "building"
- BuildReady TemplateBuildStatus = "ready"
- BuildFailed TemplateBuildStatus = "error"
+ // BuildReady indicates that a template build completed successfully.
+ BuildReady TemplateBuildStatus = "ready"
+ // BuildFailed indicates that a template build failed.
+ BuildFailed TemplateBuildStatus = "error"
)
// BuildLogEntry is one structured template build log record.
diff --git a/packages/go-sdk/template.go b/packages/go-sdk/template.go
index 298cd337..9280c8aa 100644
--- a/packages/go-sdk/template.go
+++ b/packages/go-sdk/template.go
@@ -89,54 +89,72 @@ func (builder *TemplateBuilder) fromImage(image string) *TemplateBuilder {
func (builder *TemplateBuilder) FromImage(image string) *TemplateBuilder {
return builder.fromImage(image)
}
+
+// FromDebian selects an official Debian image, defaulting to stable.
func (builder *TemplateBuilder) FromDebian(variant string) *TemplateBuilder {
if variant == "" {
variant = "stable"
}
return builder.fromImage("debian:" + variant)
}
+
+// FromUbuntu selects an official Ubuntu image, defaulting to latest.
func (builder *TemplateBuilder) FromUbuntu(variant string) *TemplateBuilder {
if variant == "" {
variant = "latest"
}
return builder.fromImage("ubuntu:" + variant)
}
+
+// FromFedora selects an official Fedora image, defaulting to version 44.
func (builder *TemplateBuilder) FromFedora(variant string) *TemplateBuilder {
if variant == "" {
variant = "44"
}
return builder.fromImage("fedora:" + variant)
}
+
+// FromAlpine selects an official Alpine image, defaulting to version 3.24.
func (builder *TemplateBuilder) FromAlpine(variant string) *TemplateBuilder {
if variant == "" {
variant = "3.24"
}
return builder.fromImage("alpine:" + variant)
}
+
+// FromArch selects an official Arch Linux image.
func (builder *TemplateBuilder) FromArch(variant string) *TemplateBuilder {
if variant == "" {
variant = "latest"
}
return builder.fromImage("archlinux:" + variant)
}
+
+// FromPython selects an official Python image.
func (builder *TemplateBuilder) FromPython(version string) *TemplateBuilder {
if version == "" {
version = "3"
}
return builder.fromImage("python:" + version)
}
+
+// FromNode selects an official Node.js image, defaulting to the LTS variant.
func (builder *TemplateBuilder) FromNode(variant string) *TemplateBuilder {
if variant == "" {
variant = "lts"
}
return builder.fromImage("node:" + variant)
}
+
+// FromBun selects an official Bun image.
func (builder *TemplateBuilder) FromBun(variant string) *TemplateBuilder {
if variant == "" {
variant = "latest"
}
return builder.fromImage("oven/bun:" + variant)
}
+
+// FromBase selects the default AgentBox base image.
func (builder *TemplateBuilder) FromBase() *TemplateBuilder {
return builder.fromImage(defaultBaseImage)
}
@@ -317,16 +335,25 @@ func (builder *TemplateBuilder) Copy(source, destination string, options *CopyOp
return builder
}
+// Run adds shell commands executed as the current build user.
func (builder *TemplateBuilder) Run(commands ...string) *TemplateBuilder {
return builder.add("RUN", strings.Join(commands, " && "))
}
+
+// RunAs adds shell commands executed as user.
func (builder *TemplateBuilder) RunAs(user string, commands ...string) *TemplateBuilder {
return builder.add("RUN", strings.Join(commands, " && "), user)
}
+
+// Workdir sets the working directory for subsequent template steps.
func (builder *TemplateBuilder) Workdir(path string) *TemplateBuilder {
return builder.add("WORKDIR", path)
}
+
+// User sets the user for subsequent template steps.
func (builder *TemplateBuilder) User(user string) *TemplateBuilder { return builder.add("USER", user) }
+
+// Env sets environment variables for subsequent template steps.
func (builder *TemplateBuilder) Env(values map[string]string) *TemplateBuilder {
args := make([]string, 0, len(values)*2)
keys := slices.Sorted(maps.Keys(values))
@@ -335,6 +362,8 @@ func (builder *TemplateBuilder) Env(values map[string]string) *TemplateBuilder {
}
return builder.add("ENV", args...)
}
+
+// Remove recursively removes paths from the template filesystem.
func (builder *TemplateBuilder) Remove(paths ...string) *TemplateBuilder {
quoted := make([]string, len(paths))
for index, path := range paths {
@@ -342,9 +371,13 @@ func (builder *TemplateBuilder) Remove(paths ...string) *TemplateBuilder {
}
return builder.Run("rm -rf " + strings.Join(quoted, " "))
}
+
+// Rename moves a path in the template filesystem.
func (builder *TemplateBuilder) Rename(source, destination string) *TemplateBuilder {
return builder.Run("mv " + shellQuote(source) + " " + shellQuote(destination))
}
+
+// MakeDir creates directories and their missing parents.
func (builder *TemplateBuilder) MakeDir(paths ...string) *TemplateBuilder {
quoted := make([]string, len(paths))
for index, path := range paths {
@@ -352,15 +385,21 @@ func (builder *TemplateBuilder) MakeDir(paths ...string) *TemplateBuilder {
}
return builder.Run("mkdir -p " + strings.Join(quoted, " "))
}
+
+// Symlink creates a symbolic link.
func (builder *TemplateBuilder) Symlink(source, destination string) *TemplateBuilder {
return builder.Run("ln -s " + shellQuote(source) + " " + shellQuote(destination))
}
+
+// PipInstall installs Python packages as root.
func (builder *TemplateBuilder) PipInstall(packages ...string) *TemplateBuilder {
if len(packages) == 0 {
packages = []string{"."}
}
return builder.RunAs("root", "pip install "+strings.Join(packages, " "))
}
+
+// NPMInstall installs npm packages with the requested scope.
func (builder *TemplateBuilder) NPMInstall(options PackageInstallOptions, packages ...string) *TemplateBuilder {
flags := ""
if options.Global {
@@ -375,6 +414,8 @@ func (builder *TemplateBuilder) NPMInstall(options PackageInstallOptions, packag
}
return builder.RunAs(user, strings.TrimSpace("npm install"+flags+" "+strings.Join(packages, " ")))
}
+
+// BunInstall installs Bun packages with the requested scope.
func (builder *TemplateBuilder) BunInstall(options PackageInstallOptions, packages ...string) *TemplateBuilder {
flags := ""
if options.Global {
@@ -389,6 +430,8 @@ func (builder *TemplateBuilder) BunInstall(options PackageInstallOptions, packag
}
return builder.RunAs(user, strings.TrimSpace("bun install"+flags+" "+strings.Join(packages, " ")))
}
+
+// AptInstall installs Debian packages as root.
func (builder *TemplateBuilder) AptInstall(options AptInstallOptions, packages ...string) *TemplateBuilder {
flags := ""
if options.NoInstallRecommends {
@@ -399,6 +442,8 @@ func (builder *TemplateBuilder) AptInstall(options AptInstallOptions, packages .
}
return builder.RunAs("root", "apt-get update", "DEBIAN_FRONTEND=noninteractive DEBCONF_NOWARNINGS=yes apt-get install -y"+flags+" "+strings.Join(packages, " "))
}
+
+// GitClone clones a Git repository into the template filesystem.
func (builder *TemplateBuilder) GitClone(repository string, options *GitCloneOptions) *TemplateBuilder {
args := []string{"git clone", shellQuote(repository)}
user := ""
@@ -422,21 +467,33 @@ func (builder *TemplateBuilder) SkipCache() *TemplateBuilder {
builder.forceNext = true
return builder
}
+
+// Start configures the sandbox start command and readiness command.
func (builder *TemplateBuilder) Start(command, readyCommand string) *TemplateBuilder {
builder.startCmd, builder.readyCmd = command, readyCommand
return builder
}
+
+// Ready replaces the readiness command for the template.
func (builder *TemplateBuilder) Ready(command string) *TemplateBuilder {
builder.readyCmd = command
return builder
}
+
+// WaitForPort returns a readiness command that waits for a listening port.
func WaitForPort(port int) string {
return fmt.Sprintf(`[ -n "$(ss -Htuln sport = :%d)" ]`, port)
}
+
+// WaitForURL returns a readiness command that waits for an HTTP status.
func WaitForURL(value string, status int) string {
return fmt.Sprintf(`curl -s -o /dev/null -w "%%{http_code}" %s | grep -q "%d"`, shellQuote(value), status)
}
-func WaitForFile(path string) string { return "test -e " + shellQuote(path) }
+
+// WaitForFile returns a readiness command that waits for a filesystem path.
+func WaitForFile(path string) string { return "test -e " + shellQuote(path) }
+
+// WaitForProcess returns a readiness command that waits for a named process.
func WaitForProcess(process string) string { return "pgrep " + shellQuote(process) + " >/dev/null" }
// WaitForTimeout waits a fixed duration before marking a service ready.
@@ -510,6 +567,8 @@ func (builder *TemplateBuilder) request(steps []api.TemplateStep) api.TemplateBu
// TemplateService manages AgentBox templates.
type TemplateService struct{ client *Client }
+
+// TemplateBuildOptions configures resources, tags, caching, and build polling.
type TemplateBuildOptions struct {
Tags []string
CPUCount, MemoryMB int
@@ -517,11 +576,15 @@ type TemplateBuildOptions struct {
PollInterval time.Duration
OnLog func(BuildLogEntry)
}
+
+// TemplateBuildRef identifies a started template build.
type TemplateBuildRef struct {
Name string
Tags []string
TemplateID, BuildID string
}
+
+// TemplateListOptions configures template pagination and team filtering.
type TemplateListOptions struct {
TeamID, NextToken string
Limit int
@@ -532,12 +595,16 @@ type TemplateInfoOptions struct {
NextToken string
Limit int
}
+
+// TemplateLogOptions configures template log pagination and filtering.
type TemplateLogOptions struct {
Cursor string
Timestamp int64
Limit int
Direction, Level, Source string
}
+
+// TemplateTag associates a template tag with a build.
type TemplateTag struct {
Tag, BuildID string
CreatedAt time.Time
@@ -635,6 +702,7 @@ func (service *TemplateService) Build(ctx context.Context, builder *TemplateBuil
}
}
+// BuildStatus returns the current build state and logs after logsOffset.
func (service *TemplateService) BuildStatus(ctx context.Context, templateID, buildID string, logsOffset int) (*TemplateBuildInfo, error) {
offset := int32(logsOffset)
requestCtx, cancel := withRequestTimeout(ctx, service.client.config.requestTimeout)
@@ -649,6 +717,8 @@ func (service *TemplateService) BuildStatus(ctx context.Context, templateID, bui
result, err := convertModel[TemplateBuildInfo](*response.JSON200)
return &result, err
}
+
+// Exists reports whether a template alias exists or is reserved.
func (service *TemplateService) Exists(ctx context.Context, alias string) (bool, error) {
requestCtx, cancel := withRequestTimeout(ctx, service.client.config.requestTimeout)
defer cancel()
@@ -667,6 +737,8 @@ func (service *TemplateService) Exists(ctx context.Context, alias string) (bool,
}
return true, nil
}
+
+// AssignTags assigns tags to a template target and returns the selected build ID.
func (service *TemplateService) AssignTags(ctx context.Context, target string, tags []string) (string, error) {
requestCtx, cancel := withRequestTimeout(ctx, service.client.config.requestTimeout)
defer cancel()
@@ -679,6 +751,8 @@ func (service *TemplateService) AssignTags(ctx context.Context, target string, t
}
return response.JSON201.BuildID.String(), nil
}
+
+// RemoveTags removes tags from a named template.
func (service *TemplateService) RemoveTags(ctx context.Context, name string, tags []string) error {
requestCtx, cancel := withRequestTimeout(ctx, service.client.config.requestTimeout)
defer cancel()
@@ -691,6 +765,8 @@ func (service *TemplateService) RemoveTags(ctx context.Context, name string, tag
}
return nil
}
+
+// Tags lists tags assigned to a template.
func (service *TemplateService) Tags(ctx context.Context, templateID string) ([]TemplateTag, error) {
requestCtx, cancel := withRequestTimeout(ctx, service.client.config.requestTimeout)
defer cancel()
diff --git a/reference/manifest.json b/reference/manifest.json
index 146b911c..d3ab2ec7 100644
--- a/reference/manifest.json
+++ b/reference/manifest.json
@@ -44,6 +44,8 @@
"sdk/cli/auth.md": "0b2c75262b0c0670c7bc0f0f3cbed65fbe4a16d6fe4437789a5685b8bf2174a1",
"sdk/cli/sandbox.md": "16b64c5a4e932eca2452e400e0faf154eba1d3c7373513aa7cd9744e02908313",
"sdk/cli/template.md": "f270b22b9ee10a9b954a14f24e04c5449b4d5823bb28002ffde3ed682594cfc5",
+ "sdk/go/code-interpreter.md": "9c56333b8181878d656baa27a4b56b768a0cb01c9d764f7ac8d52d32d8faa70c",
+ "sdk/go/core.md": "72592421dccf87837b71ddf1e52d812474311f0cc498dc0756af186ce114a84e",
"sdk/javascript/code-interpreter/README.md": "a787206eb86f81fc306b373ce20bc6c91464b0ab3c3ec7650eccbb6be5f676c5",
"sdk/javascript/code-interpreter/classes/Sandbox.md": "19d9f1f1e8847606a54d93c5a6e5d4c89f936a745866e8d6a2aa06758b605e60",
"sdk/javascript/code-interpreter/enumerations/ChartType.md": "cf1ba00cd3258cc88814b7215e101b0d775ceb15dd833636d58ae538d8107ec1",
@@ -186,7 +188,8 @@
"@abox-dev/code-interpreter": "0.1.2",
"@abox-dev/sdk": "0.1.2",
"abox-code-interpreter": "0.1.2",
- "abox-sdk": "0.1.2"
+ "abox-sdk": "0.1.2",
+ "github.com/abox-dev/sdk/packages/go-sdk": "0.1.2"
},
"schemaVersion": 1
}
diff --git a/reference/sdk/go/code-interpreter.md b/reference/sdk/go/code-interpreter.md
new file mode 100644
index 00000000..d460ebea
--- /dev/null
+++ b/reference/sdk/go/code-interpreter.md
@@ -0,0 +1,354 @@
+
+
+# codeinterpreter
+
+ import "github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter"
+
+Package codeinterpreter runs Python, JavaScript, and TypeScript in AgentBox.
+
+## Index
+
+- Constants
+- [type Chart](<#Chart>)
+ - [func \(chart \*Chart\) UnmarshalJSON\(data \[\]byte\) error](<#Chart.UnmarshalJSON>)
+- [type ChartType](<#ChartType>)
+- [type Client](<#Client>)
+ - [func NewClient\(options ...agentbox.ClientOption\) \(\*Client, error\)](<#NewClient>)
+ - [func \(client \*Client\) Connect\(ctx context.Context, id string, options \*agentbox.ConnectSandboxOptions\) \(\*Sandbox, error\)](<#Client.Connect>)
+ - [func \(client \*Client\) Create\(ctx context.Context, options \*agentbox.CreateSandboxOptions\) \(\*Sandbox, error\)](<#Client.Create>)
+- [type Context](<#Context>)
+- [type CreateContextOptions](<#CreateContextOptions>)
+- [type Execution](<#Execution>)
+ - [func \(execution Execution\) Text\(\) string](<#Execution.Text>)
+- [type ExecutionError](<#ExecutionError>)
+ - [func \(e ExecutionError\) Error\(\) string](<#ExecutionError.Error>)
+- [type Language](<#Language>)
+- [type Logs](<#Logs>)
+- [type OutputMessage](<#OutputMessage>)
+ - [func \(message OutputMessage\) String\(\) string](<#OutputMessage.String>)
+- [type RawData](<#RawData>)
+- [type Result](<#Result>)
+ - [func \(result Result\) Formats\(\) \[\]string](<#Result.Formats>)
+- [type RunCodeOptions](<#RunCodeOptions>)
+- [type Sandbox](<#Sandbox>)
+ - [func \(sandbox \*Sandbox\) CreateContext\(ctx context.Context, options \*CreateContextOptions\) \(\*Context, error\)](<#Sandbox.CreateContext>)
+ - [func \(sandbox \*Sandbox\) ListContexts\(ctx context.Context\) \(\[\]Context, error\)](<#Sandbox.ListContexts>)
+ - [func \(sandbox \*Sandbox\) RemoveContext\(ctx context.Context, contextID string\) error](<#Sandbox.RemoveContext>)
+ - [func \(sandbox \*Sandbox\) RestartContext\(ctx context.Context, contextID string\) error](<#Sandbox.RestartContext>)
+ - [func \(sandbox \*Sandbox\) RunCode\(ctx context.Context, code string, options \*RunCodeOptions\) \(\*Execution, error\)](<#Sandbox.RunCode>)
+- [type ScaleType](<#ScaleType>)
+
+
+## Constants
+
+
+
+ const (
+ // DefaultTemplate is the template used when Create receives no template.
+ DefaultTemplate = "code-interpreter"
+ // JupyterPort is the internal Code Interpreter service port.
+ JupyterPort = 49999
+ )
+
+
+## type Chart
+
+Chart retains typed common chart properties and unknown fields in Extra.
+
+ type Chart struct {
+ Type ChartType `json:"type"`
+ Title string `json:"title"`
+ Elements []json.RawMessage `json:"elements"`
+ XLabel string `json:"x_label,omitempty"`
+ YLabel string `json:"y_label,omitempty"`
+ XUnit string `json:"x_unit,omitempty"`
+ YUnit string `json:"y_unit,omitempty"`
+ XScale ScaleType `json:"x_scale,omitempty"`
+ YScale ScaleType `json:"y_scale,omitempty"`
+ Extra map[string]json.RawMessage `json:"-"`
+ }
+
+
+### func \(\*Chart\) UnmarshalJSON
+
+ func (chart *Chart) UnmarshalJSON(data []byte) error
+
+UnmarshalJSON decodes known chart fields and preserves unknown fields in Extra.
+
+
+## type ChartType
+
+ChartType identifies a supported chart representation.
+
+ type ChartType string
+
+
+
+ const (
+ // ChartLine identifies a line chart.
+ ChartLine ChartType = "line"
+ // ChartScatter identifies a scatter chart.
+ ChartScatter ChartType = "scatter"
+ // ChartBar identifies a bar chart.
+ ChartBar ChartType = "bar"
+ // ChartPie identifies a pie chart.
+ ChartPie ChartType = "pie"
+ // ChartBoxAndWhisker identifies a box-and-whisker chart.
+ ChartBoxAndWhisker ChartType = "box_and_whisker"
+ // ChartSuper identifies a composite chart.
+ ChartSuper ChartType = "superchart"
+ // ChartUnknown identifies a chart type unknown to this SDK version.
+ ChartUnknown ChartType = "unknown"
+ )
+
+
+## type Client
+
+Client wraps the core client with Code Interpreter creation helpers.
+
+ type Client struct{ Core *agentbox.Client }
+
+
+### func NewClient
+
+ func NewClient(options ...agentbox.ClientOption) (*Client, error)
+
+NewClient creates a Code Interpreter client using the core client options.
+
+
+### func \(\*Client\) Connect
+
+ func (client *Client) Connect(ctx context.Context, id string, options *agentbox.ConnectSandboxOptions) (*Sandbox, error)
+
+Connect attaches to an existing Code Interpreter sandbox.
+
+
+### func \(\*Client\) Create
+
+ func (client *Client) Create(ctx context.Context, options *agentbox.CreateSandboxOptions) (*Sandbox, error)
+
+Create creates a Code Interpreter sandbox.
+
+
+## type Context
+
+Context identifies a persistent kernel context.
+
+ type Context struct {
+ ID string `json:"id"`
+ Language string `json:"language"`
+ Cwd string `json:"cwd"`
+ }
+
+
+## type CreateContextOptions
+
+CreateContextOptions configures a persistent kernel context.
+
+ type CreateContextOptions struct {
+ Language Language `json:"language,omitempty"`
+ Cwd string `json:"cwd,omitempty"`
+ RequestTimeout time.Duration `json:"-"`
+ }
+
+
+## type Execution
+
+Execution contains the complete result of one code execution.
+
+ type Execution struct {
+ Results []Result `json:"results"`
+ Logs Logs `json:"logs"`
+ Error *ExecutionError `json:"error,omitempty"`
+ ExecutionCount int `json:"execution_count,omitempty"`
+ }
+
+
+### func \(Execution\) Text
+
+ func (execution Execution) Text() string
+
+Text returns the text representation of the main result, if present.
+
+
+## type ExecutionError
+
+ExecutionError is a kernel error and traceback.
+
+ type ExecutionError struct {
+ Name string `json:"name"`
+ Value string `json:"value"`
+ Traceback string `json:"traceback"`
+ }
+
+
+### func \(ExecutionError\) Error
+
+ func (e ExecutionError) Error() string
+
+Error formats the kernel error name and value.
+
+
+## type Language
+
+Language is a Code Interpreter runtime language.
+
+ type Language string
+
+
+
+ const (
+ // Python selects a Python kernel.
+ Python Language = "python"
+ // JavaScript selects a JavaScript kernel.
+ JavaScript Language = "javascript"
+ // TypeScript selects a TypeScript kernel.
+ TypeScript Language = "typescript"
+ )
+
+
+## type Logs
+
+Logs contains collected standard output and standard error lines.
+
+ type Logs struct {
+ Stdout []string `json:"stdout"`
+ Stderr []string `json:"stderr"`
+ }
+
+
+## type OutputMessage
+
+OutputMessage is one stdout or stderr line.
+
+ type OutputMessage struct {
+ Line string
+ Timestamp int64
+ Error bool
+ }
+
+
+### func \(OutputMessage\) String
+
+ func (message OutputMessage) String() string
+
+String returns the output line.
+
+
+## type RawData
+
+RawData preserves every MIME representation returned by the kernel.
+
+ type RawData map[string]json.RawMessage
+
+
+## type Result
+
+Result contains the decoded and raw MIME representations of one result.
+
+ type Result struct {
+ Text, HTML, Markdown, SVG, PNG, JPEG, PDF, LaTeX, JSON, JavaScript string
+ Data map[string]any
+ Chart *Chart
+ Extra map[string]json.RawMessage
+ Raw RawData
+ IsMainResult bool
+ }
+
+
+### func \(Result\) Formats
+
+ func (result Result) Formats() []string
+
+Formats returns the available raw MIME keys in sorted order.
+
+
+## type RunCodeOptions
+
+RunCodeOptions configures code execution and streaming callbacks.
+
+ type RunCodeOptions struct {
+ Language Language
+ Context *Context
+ Env map[string]string
+ RequestTimeout time.Duration
+ ExecutionTimeout time.Duration
+ OnStdout func(OutputMessage)
+ OnStderr func(OutputMessage)
+ OnResult func(Result)
+ OnError func(ExecutionError)
+ }
+
+
+## type Sandbox
+
+Sandbox is a core sandbox with notebook\-kernel APIs.
+
+ type Sandbox struct{ *agentbox.Sandbox }
+
+
+### func \(\*Sandbox\) CreateContext
+
+ func (sandbox *Sandbox) CreateContext(ctx context.Context, options *CreateContextOptions) (*Context, error)
+
+CreateContext creates a persistent kernel context.
+
+
+### func \(\*Sandbox\) ListContexts
+
+ func (sandbox *Sandbox) ListContexts(ctx context.Context) ([]Context, error)
+
+ListContexts returns all persistent kernel contexts in the sandbox.
+
+
+### func \(\*Sandbox\) RemoveContext
+
+ func (sandbox *Sandbox) RemoveContext(ctx context.Context, contextID string) error
+
+RemoveContext removes a persistent kernel context.
+
+
+### func \(\*Sandbox\) RestartContext
+
+ func (sandbox *Sandbox) RestartContext(ctx context.Context, contextID string) error
+
+RestartContext restarts a persistent kernel context.
+
+
+### func \(\*Sandbox\) RunCode
+
+ func (sandbox *Sandbox) RunCode(ctx context.Context, code string, options *RunCodeOptions) (*Execution, error)
+
+RunCode executes source code and collects streamed NDJSON output.
+
+
+## type ScaleType
+
+ScaleType identifies a chart axis scale.
+
+ type ScaleType string
+
+
+
+ const (
+ // ScaleLinear identifies a linear scale.
+ ScaleLinear ScaleType = "linear"
+ // ScaleDatetime identifies a date and time scale.
+ ScaleDatetime ScaleType = "datetime"
+ // ScaleCategorical identifies a categorical scale.
+ ScaleCategorical ScaleType = "categorical"
+ // ScaleLog identifies a logarithmic scale.
+ ScaleLog ScaleType = "log"
+ // ScaleSymlog identifies a symmetric logarithmic scale.
+ ScaleSymlog ScaleType = "symlog"
+ // ScaleLogit identifies a logit scale.
+ ScaleLogit ScaleType = "logit"
+ // ScaleFunction identifies a custom function scale.
+ ScaleFunction ScaleType = "function"
+ // ScaleFunctionLog identifies a logarithmic custom function scale.
+ ScaleFunctionLog ScaleType = "functionlog"
+ // ScaleAsinh identifies an inverse hyperbolic sine scale.
+ ScaleAsinh ScaleType = "asinh"
+ )
+
+Generated by [gomarkdoc]()
diff --git a/reference/sdk/go/core.md b/reference/sdk/go/core.md
new file mode 100644
index 00000000..d0061d48
--- /dev/null
+++ b/reference/sdk/go/core.md
@@ -0,0 +1,2246 @@
+
+
+# agentbox
+
+ import "github.com/abox-dev/sdk/packages/go-sdk"
+
+Package agentbox provides the official Go client for AgentBox sandboxes.
+
+Create a client, start a sandbox, and run a command:
+
+ client, err := agentbox.NewClient()
+ if err != nil {
+ log.Fatal(err)
+ }
+ sandbox, err := client.Sandboxes.Create(ctx, nil)
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer sandbox.Kill(context.Background())
+ result, err := sandbox.Commands.Run(ctx, "echo", &agentbox.CommandOptions{
+ Args: []string{"Hello from AgentBox"},
+ })
+
+
+## Index
+
+- Constants
+- [func IAMTokenPlaceholder\(name string\) \(string, error\)](<#IAMTokenPlaceholder>)
+- [func IAMTokenPlaceholders\(names ...string\) \(map\[string\]string, error\)](<#IAMTokenPlaceholders>)
+- [func ValidateIAMTokenName\(name string\) error](<#ValidateIAMTokenName>)
+- [func WaitForFile\(path string\) string](<#WaitForFile>)
+- [func WaitForPort\(port int\) string](<#WaitForPort>)
+- [func WaitForProcess\(process string\) string](<#WaitForProcess>)
+- [func WaitForTimeout\(timeout time.Duration\) string](<#WaitForTimeout>)
+- [func WaitForURL\(value string, status int\) string](<#WaitForURL>)
+- [type APIError](<#APIError>)
+ - [func \(e \*APIError\) Error\(\) string](<#APIError.Error>)
+ - [func \(e \*APIError\) Unwrap\(\) error](<#APIError.Unwrap>)
+- [type AptInstallOptions](<#AptInstallOptions>)
+- [type AuthenticationError](<#AuthenticationError>)
+ - [func \(e \*AuthenticationError\) Error\(\) string](<#AuthenticationError.Error>)
+ - [func \(e \*AuthenticationError\) Unwrap\(\) error](<#AuthenticationError.Unwrap>)
+- [type BuildError](<#BuildError>)
+ - [func \(e \*BuildError\) Error\(\) string](<#BuildError.Error>)
+ - [func \(e \*BuildError\) Unwrap\(\) error](<#BuildError.Unwrap>)
+- [type BuildLogEntry](<#BuildLogEntry>)
+- [type BuildStatusReason](<#BuildStatusReason>)
+- [type Client](<#Client>)
+ - [func NewClient\(options ...ClientOption\) \(\*Client, error\)](<#NewClient>)
+- [type ClientOption](<#ClientOption>)
+ - [func WithAPIKey\(apiKey string\) ClientOption](<#WithAPIKey>)
+ - [func WithAPIURL\(value string\) ClientOption](<#WithAPIURL>)
+ - [func WithDebug\(enabled bool\) ClientOption](<#WithDebug>)
+ - [func WithDomain\(domain string\) ClientOption](<#WithDomain>)
+ - [func WithHTTPClient\(client \*http.Client\) ClientOption](<#WithHTTPClient>)
+ - [func WithHeaders\(headers http.Header\) ClientOption](<#WithHeaders>)
+ - [func WithLogger\(logger \*slog.Logger\) ClientOption](<#WithLogger>)
+ - [func WithProxy\(value string\) ClientOption](<#WithProxy>)
+ - [func WithRequestTimeout\(timeout time.Duration\) ClientOption](<#WithRequestTimeout>)
+ - [func WithSandboxURL\(value string\) ClientOption](<#WithSandboxURL>)
+- [type CommandExitError](<#CommandExitError>)
+ - [func \(e \*CommandExitError\) Error\(\) string](<#CommandExitError.Error>)
+- [type CommandHandle](<#CommandHandle>)
+ - [func \(handle \*CommandHandle\) CloseStdin\(ctx context.Context\) error](<#CommandHandle.CloseStdin>)
+ - [func \(handle \*CommandHandle\) Kill\(ctx context.Context\) error](<#CommandHandle.Kill>)
+ - [func \(handle \*CommandHandle\) PID\(ctx context.Context\) \(uint32, error\)](<#CommandHandle.PID>)
+ - [func \(handle \*CommandHandle\) Wait\(ctx context.Context\) \(CommandResult, error\)](<#CommandHandle.Wait>)
+ - [func \(handle \*CommandHandle\) Write\(ctx context.Context, data \[\]byte\) \(int, error\)](<#CommandHandle.Write>)
+- [type CommandOptions](<#CommandOptions>)
+- [type CommandResult](<#CommandResult>)
+- [type CommandService](<#CommandService>)
+ - [func \(service \*CommandService\) Connect\(ctx context.Context, pid uint32, tag string\) \(\*CommandHandle, error\)](<#CommandService.Connect>)
+ - [func \(service \*CommandService\) Kill\(ctx context.Context, pid uint32, tag string\) error](<#CommandService.Kill>)
+ - [func \(service \*CommandService\) List\(ctx context.Context\) \(\[\]ProcessInfo, error\)](<#CommandService.List>)
+ - [func \(service \*CommandService\) Run\(ctx context.Context, command string, options \*CommandOptions\) \(CommandResult, error\)](<#CommandService.Run>)
+ - [func \(service \*CommandService\) Start\(ctx context.Context, command string, options \*CommandOptions\) \(\*CommandHandle, error\)](<#CommandService.Start>)
+ - [func \(service \*CommandService\) Terminate\(ctx context.Context, pid uint32, tag string\) error](<#CommandService.Terminate>)
+- [type ConnectSandboxOptions](<#ConnectSandboxOptions>)
+- [type CopyOptions](<#CopyOptions>)
+- [type CreateSandboxOptions](<#CreateSandboxOptions>)
+- [type EntryInfo](<#EntryInfo>)
+- [type FileEvent](<#FileEvent>)
+- [type FileNotFoundError](<#FileNotFoundError>)
+ - [func \(e \*FileNotFoundError\) Error\(\) string](<#FileNotFoundError.Error>)
+ - [func \(e \*FileNotFoundError\) Unwrap\(\) error](<#FileNotFoundError.Unwrap>)
+- [type FileService](<#FileService>)
+ - [func \(service \*FileService\) Exists\(ctx context.Context, path string\) \(bool, error\)](<#FileService.Exists>)
+ - [func \(service \*FileService\) List\(ctx context.Context, path string, depth uint32\) \(\[\]EntryInfo, error\)](<#FileService.List>)
+ - [func \(service \*FileService\) MakeDir\(ctx context.Context, path string\) \(\*EntryInfo, error\)](<#FileService.MakeDir>)
+ - [func \(service \*FileService\) Read\(ctx context.Context, path, user string\) \(io.ReadCloser, error\)](<#FileService.Read>)
+ - [func \(service \*FileService\) ReadBytes\(ctx context.Context, path, user string\) \(\[\]byte, error\)](<#FileService.ReadBytes>)
+ - [func \(service \*FileService\) ReadText\(ctx context.Context, path, user string\) \(string, error\)](<#FileService.ReadText>)
+ - [func \(service \*FileService\) ReadTo\(ctx context.Context, path, user string, writer io.Writer\) \(int64, error\)](<#FileService.ReadTo>)
+ - [func \(service \*FileService\) Remove\(ctx context.Context, path string\) error](<#FileService.Remove>)
+ - [func \(service \*FileService\) Rename\(ctx context.Context, source, destination string\) \(\*EntryInfo, error\)](<#FileService.Rename>)
+ - [func \(service \*FileService\) SignedReadURL\(path, user string, expiration time.Time\) \(string, error\)](<#FileService.SignedReadURL>)
+ - [func \(service \*FileService\) SignedWriteURL\(path, user string, expiration time.Time\) \(string, error\)](<#FileService.SignedWriteURL>)
+ - [func \(service \*FileService\) Stat\(ctx context.Context, path string\) \(\*EntryInfo, error\)](<#FileService.Stat>)
+ - [func \(service \*FileService\) Watch\(ctx context.Context, path string, options \*WatchOptions\) \(\*WatchHandle, error\)](<#FileService.Watch>)
+ - [func \(service \*FileService\) Write\(ctx context.Context, path string, reader io.Reader, options \*WriteFileOptions\) \(\*EntryInfo, error\)](<#FileService.Write>)
+ - [func \(service \*FileService\) WriteBatch\(ctx context.Context, files \[\]WriteFile, user string\) \(\[\]EntryInfo, error\)](<#FileService.WriteBatch>)
+ - [func \(service \*FileService\) WriteBytes\(ctx context.Context, path string, data \[\]byte, options \*WriteFileOptions\) \(\*EntryInfo, error\)](<#FileService.WriteBytes>)
+ - [func \(service \*FileService\) WriteText\(ctx context.Context, path, text string, options \*WriteFileOptions\) \(\*EntryInfo, error\)](<#FileService.WriteText>)
+- [type FileType](<#FileType>)
+- [type FileUploadError](<#FileUploadError>)
+ - [func \(e \*FileUploadError\) Error\(\) string](<#FileUploadError.Error>)
+ - [func \(e \*FileUploadError\) Unwrap\(\) error](<#FileUploadError.Unwrap>)
+- [type ForkOptions](<#ForkOptions>)
+- [type ForkResult](<#ForkResult>)
+- [type GitCloneOptions](<#GitCloneOptions>)
+- [type InvalidArgumentError](<#InvalidArgumentError>)
+ - [func \(e \*InvalidArgumentError\) Error\(\) string](<#InvalidArgumentError.Error>)
+ - [func \(e \*InvalidArgumentError\) Unwrap\(\) error](<#InvalidArgumentError.Unwrap>)
+- [type ListSandboxOptions](<#ListSandboxOptions>)
+- [type ListedSandbox](<#ListedSandbox>)
+- [type MetricsOptions](<#MetricsOptions>)
+- [type NotEnoughSpaceError](<#NotEnoughSpaceError>)
+ - [func \(e \*NotEnoughSpaceError\) Error\(\) string](<#NotEnoughSpaceError.Error>)
+ - [func \(e \*NotEnoughSpaceError\) Unwrap\(\) error](<#NotEnoughSpaceError.Unwrap>)
+- [type PTYOptions](<#PTYOptions>)
+- [type PTYService](<#PTYService>)
+ - [func \(service \*PTYService\) Connect\(ctx context.Context, pid uint32, tag string\) \(\*CommandHandle, error\)](<#PTYService.Connect>)
+ - [func \(service \*PTYService\) Create\(ctx context.Context, command string, options \*PTYOptions\) \(\*CommandHandle, error\)](<#PTYService.Create>)
+ - [func \(service \*PTYService\) Input\(ctx context.Context, handle \*CommandHandle, data \[\]byte\) error](<#PTYService.Input>)
+ - [func \(service \*PTYService\) Kill\(ctx context.Context, handle \*CommandHandle\) error](<#PTYService.Kill>)
+ - [func \(service \*PTYService\) Resize\(ctx context.Context, handle \*CommandHandle, cols, rows uint32\) error](<#PTYService.Resize>)
+- [type PackageInstallOptions](<#PackageInstallOptions>)
+- [type Page](<#Page>)
+- [type PauseOptions](<#PauseOptions>)
+- [type ProcessInfo](<#ProcessInfo>)
+- [type RateLimitError](<#RateLimitError>)
+ - [func \(e \*RateLimitError\) Error\(\) string](<#RateLimitError.Error>)
+ - [func \(e \*RateLimitError\) Unwrap\(\) error](<#RateLimitError.Unwrap>)
+- [type Sandbox](<#Sandbox>)
+ - [func \(sandbox \*Sandbox\) CreateSnapshot\(ctx context.Context, name string\) \(\*SnapshotInfo, error\)](<#Sandbox.CreateSnapshot>)
+ - [func \(sandbox \*Sandbox\) Fork\(ctx context.Context, options \*ForkOptions\) \(\[\]ForkResult, error\)](<#Sandbox.Fork>)
+ - [func \(sandbox Sandbox\) GoString\(\) string](<#Sandbox.GoString>)
+ - [func \(sandbox \*Sandbox\) Host\(port int\) string](<#Sandbox.Host>)
+ - [func \(sandbox \*Sandbox\) Info\(ctx context.Context\) \(\*SandboxInfo, error\)](<#Sandbox.Info>)
+ - [func \(sandbox \*Sandbox\) IsRunning\(ctx context.Context\) \(bool, error\)](<#Sandbox.IsRunning>)
+ - [func \(sandbox \*Sandbox\) KeepAlive\(ctx context.Context, duration time.Duration\) error](<#Sandbox.KeepAlive>)
+ - [func \(sandbox \*Sandbox\) Kill\(ctx context.Context\) \(bool, error\)](<#Sandbox.Kill>)
+ - [func \(sandbox \*Sandbox\) Logs\(ctx context.Context, options \*SandboxLogOptions\) \(Page\[SandboxLogEntry\], error\)](<#Sandbox.Logs>)
+ - [func \(sandbox \*Sandbox\) Metrics\(ctx context.Context, options \*MetricsOptions\) \(\[\]SandboxMetric, error\)](<#Sandbox.Metrics>)
+ - [func \(sandbox \*Sandbox\) Pause\(ctx context.Context, options \*PauseOptions\) error](<#Sandbox.Pause>)
+ - [func \(sandbox \*Sandbox\) Request\(ctx context.Context, port int, method, path string, body io.Reader, direct bool\) \(\*http.Response, error\)](<#Sandbox.Request>)
+ - [func \(sandbox \*Sandbox\) RequestTimeout\(\) time.Duration](<#Sandbox.RequestTimeout>)
+ - [func \(sandbox \*Sandbox\) RequestWithOptions\(ctx context.Context, port int, method, path string, body io.Reader, options \*SandboxRequestOptions\) \(\*http.Response, error\)](<#Sandbox.RequestWithOptions>)
+ - [func \(sandbox \*Sandbox\) SetTimeout\(ctx context.Context, timeout time.Duration\) error](<#Sandbox.SetTimeout>)
+ - [func \(sandbox Sandbox\) String\(\) string](<#Sandbox.String>)
+ - [func \(sandbox \*Sandbox\) UpdateNetwork\(ctx context.Context, config SandboxNetworkConfig, allowInternetAccess \*bool\) error](<#Sandbox.UpdateNetwork>)
+- [type SandboxError](<#SandboxError>)
+ - [func \(e \*SandboxError\) Error\(\) string](<#SandboxError.Error>)
+ - [func \(e \*SandboxError\) Unwrap\(\) error](<#SandboxError.Unwrap>)
+- [type SandboxIAM](<#SandboxIAM>)
+- [type SandboxIAMToken](<#SandboxIAMToken>)
+- [type SandboxIAMTokens](<#SandboxIAMTokens>)
+- [type SandboxInfo](<#SandboxInfo>)
+- [type SandboxLifecycle](<#SandboxLifecycle>)
+- [type SandboxLogEntry](<#SandboxLogEntry>)
+- [type SandboxLogOptions](<#SandboxLogOptions>)
+- [type SandboxMetadata](<#SandboxMetadata>)
+- [type SandboxMetric](<#SandboxMetric>)
+- [type SandboxNetworkConfig](<#SandboxNetworkConfig>)
+- [type SandboxNetworkRule](<#SandboxNetworkRule>)
+- [type SandboxNetworkTransform](<#SandboxNetworkTransform>)
+- [type SandboxNotFoundError](<#SandboxNotFoundError>)
+ - [func \(e \*SandboxNotFoundError\) Error\(\) string](<#SandboxNotFoundError.Error>)
+ - [func \(e \*SandboxNotFoundError\) Unwrap\(\) error](<#SandboxNotFoundError.Unwrap>)
+- [type SandboxRequestOptions](<#SandboxRequestOptions>)
+- [type SandboxService](<#SandboxService>)
+ - [func \(service \*SandboxService\) Connect\(ctx context.Context, id string, options \*ConnectSandboxOptions\) \(\*Sandbox, error\)](<#SandboxService.Connect>)
+ - [func \(service \*SandboxService\) Create\(ctx context.Context, options \*CreateSandboxOptions\) \(\*Sandbox, error\)](<#SandboxService.Create>)
+ - [func \(service \*SandboxService\) DeleteSnapshot\(ctx context.Context, snapshotID string\) \(bool, error\)](<#SandboxService.DeleteSnapshot>)
+ - [func \(service \*SandboxService\) Info\(ctx context.Context, id string\) \(\*SandboxInfo, error\)](<#SandboxService.Info>)
+ - [func \(service \*SandboxService\) Kill\(ctx context.Context, id string\) \(bool, error\)](<#SandboxService.Kill>)
+ - [func \(service \*SandboxService\) List\(ctx context.Context, options \*ListSandboxOptions\) \(Page\[ListedSandbox\], error\)](<#SandboxService.List>)
+ - [func \(service \*SandboxService\) Logs\(ctx context.Context, id string, options \*SandboxLogOptions\) \(Page\[SandboxLogEntry\], error\)](<#SandboxService.Logs>)
+ - [func \(service \*SandboxService\) Metrics\(ctx context.Context, sandboxIDs ...string\) \(map\[string\]SandboxMetric, error\)](<#SandboxService.Metrics>)
+ - [func \(service \*SandboxService\) Snapshots\(ctx context.Context, options \*SnapshotListOptions\) \(Page\[SnapshotInfo\], error\)](<#SandboxService.Snapshots>)
+- [type SandboxState](<#SandboxState>)
+- [type SnapshotInfo](<#SnapshotInfo>)
+- [type SnapshotListOptions](<#SnapshotListOptions>)
+- [type TeamUser](<#TeamUser>)
+- [type TemplateBuild](<#TemplateBuild>)
+- [type TemplateBuildInfo](<#TemplateBuildInfo>)
+- [type TemplateBuildOptions](<#TemplateBuildOptions>)
+- [type TemplateBuildRef](<#TemplateBuildRef>)
+- [type TemplateBuildStatus](<#TemplateBuildStatus>)
+- [type TemplateBuilder](<#TemplateBuilder>)
+ - [func NewTemplate\(contextPath string, ignore ...string\) \*TemplateBuilder](<#NewTemplate>)
+ - [func \(builder \*TemplateBuilder\) AptInstall\(options AptInstallOptions, packages ...string\) \*TemplateBuilder](<#TemplateBuilder.AptInstall>)
+ - [func \(builder \*TemplateBuilder\) BunInstall\(options PackageInstallOptions, packages ...string\) \*TemplateBuilder](<#TemplateBuilder.BunInstall>)
+ - [func \(builder \*TemplateBuilder\) Copy\(source, destination string, options \*CopyOptions\) \*TemplateBuilder](<#TemplateBuilder.Copy>)
+ - [func \(builder \*TemplateBuilder\) Dockerfile\(\) string](<#TemplateBuilder.Dockerfile>)
+ - [func \(builder \*TemplateBuilder\) Env\(values map\[string\]string\) \*TemplateBuilder](<#TemplateBuilder.Env>)
+ - [func \(builder \*TemplateBuilder\) FromAWSRegistry\(image, accessKeyID, secretAccessKey, region string\) \*TemplateBuilder](<#TemplateBuilder.FromAWSRegistry>)
+ - [func \(builder \*TemplateBuilder\) FromAlpine\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromAlpine>)
+ - [func \(builder \*TemplateBuilder\) FromArch\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromArch>)
+ - [func \(builder \*TemplateBuilder\) FromBase\(\) \*TemplateBuilder](<#TemplateBuilder.FromBase>)
+ - [func \(builder \*TemplateBuilder\) FromBun\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromBun>)
+ - [func \(builder \*TemplateBuilder\) FromDebian\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromDebian>)
+ - [func \(builder \*TemplateBuilder\) FromDockerfile\(contentOrPath string\) \*TemplateBuilder](<#TemplateBuilder.FromDockerfile>)
+ - [func \(builder \*TemplateBuilder\) FromFedora\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromFedora>)
+ - [func \(builder \*TemplateBuilder\) FromGCPRegistry\(image, serviceAccountJSON string\) \*TemplateBuilder](<#TemplateBuilder.FromGCPRegistry>)
+ - [func \(builder \*TemplateBuilder\) FromImage\(image string\) \*TemplateBuilder](<#TemplateBuilder.FromImage>)
+ - [func \(builder \*TemplateBuilder\) FromNode\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromNode>)
+ - [func \(builder \*TemplateBuilder\) FromPython\(version string\) \*TemplateBuilder](<#TemplateBuilder.FromPython>)
+ - [func \(builder \*TemplateBuilder\) FromRegistry\(image, username, password string\) \*TemplateBuilder](<#TemplateBuilder.FromRegistry>)
+ - [func \(builder \*TemplateBuilder\) FromTemplate\(template string\) \*TemplateBuilder](<#TemplateBuilder.FromTemplate>)
+ - [func \(builder \*TemplateBuilder\) FromUbuntu\(variant string\) \*TemplateBuilder](<#TemplateBuilder.FromUbuntu>)
+ - [func \(builder \*TemplateBuilder\) GitClone\(repository string, options \*GitCloneOptions\) \*TemplateBuilder](<#TemplateBuilder.GitClone>)
+ - [func \(builder \*TemplateBuilder\) JSON\(\) \(\[\]byte, error\)](<#TemplateBuilder.JSON>)
+ - [func \(builder \*TemplateBuilder\) MakeDir\(paths ...string\) \*TemplateBuilder](<#TemplateBuilder.MakeDir>)
+ - [func \(builder \*TemplateBuilder\) NPMInstall\(options PackageInstallOptions, packages ...string\) \*TemplateBuilder](<#TemplateBuilder.NPMInstall>)
+ - [func \(builder \*TemplateBuilder\) PipInstall\(packages ...string\) \*TemplateBuilder](<#TemplateBuilder.PipInstall>)
+ - [func \(builder \*TemplateBuilder\) Ready\(command string\) \*TemplateBuilder](<#TemplateBuilder.Ready>)
+ - [func \(builder \*TemplateBuilder\) Remove\(paths ...string\) \*TemplateBuilder](<#TemplateBuilder.Remove>)
+ - [func \(builder \*TemplateBuilder\) Rename\(source, destination string\) \*TemplateBuilder](<#TemplateBuilder.Rename>)
+ - [func \(builder \*TemplateBuilder\) Run\(commands ...string\) \*TemplateBuilder](<#TemplateBuilder.Run>)
+ - [func \(builder \*TemplateBuilder\) RunAs\(user string, commands ...string\) \*TemplateBuilder](<#TemplateBuilder.RunAs>)
+ - [func \(builder \*TemplateBuilder\) SkipCache\(\) \*TemplateBuilder](<#TemplateBuilder.SkipCache>)
+ - [func \(builder \*TemplateBuilder\) Start\(command, readyCommand string\) \*TemplateBuilder](<#TemplateBuilder.Start>)
+ - [func \(builder \*TemplateBuilder\) Symlink\(source, destination string\) \*TemplateBuilder](<#TemplateBuilder.Symlink>)
+ - [func \(builder \*TemplateBuilder\) User\(user string\) \*TemplateBuilder](<#TemplateBuilder.User>)
+ - [func \(builder \*TemplateBuilder\) Workdir\(path string\) \*TemplateBuilder](<#TemplateBuilder.Workdir>)
+- [type TemplateError](<#TemplateError>)
+ - [func \(e \*TemplateError\) Error\(\) string](<#TemplateError.Error>)
+ - [func \(e \*TemplateError\) Unwrap\(\) error](<#TemplateError.Unwrap>)
+- [type TemplateInfo](<#TemplateInfo>)
+- [type TemplateInfoOptions](<#TemplateInfoOptions>)
+- [type TemplateListOptions](<#TemplateListOptions>)
+- [type TemplateLogOptions](<#TemplateLogOptions>)
+- [type TemplateService](<#TemplateService>)
+ - [func \(service \*TemplateService\) AssignTags\(ctx context.Context, target string, tags \[\]string\) \(string, error\)](<#TemplateService.AssignTags>)
+ - [func \(service \*TemplateService\) Build\(ctx context.Context, builder \*TemplateBuilder, name string, options \*TemplateBuildOptions\) \(\*TemplateBuildRef, error\)](<#TemplateService.Build>)
+ - [func \(service \*TemplateService\) BuildInBackground\(ctx context.Context, builder \*TemplateBuilder, name string, options \*TemplateBuildOptions\) \(\*TemplateBuildRef, error\)](<#TemplateService.BuildInBackground>)
+ - [func \(service \*TemplateService\) BuildLogs\(ctx context.Context, templateID, buildID string, options \*TemplateLogOptions\) \(Page\[BuildLogEntry\], error\)](<#TemplateService.BuildLogs>)
+ - [func \(service \*TemplateService\) BuildStatus\(ctx context.Context, templateID, buildID string, logsOffset int\) \(\*TemplateBuildInfo, error\)](<#TemplateService.BuildStatus>)
+ - [func \(service \*TemplateService\) Delete\(ctx context.Context, templateID string\) error](<#TemplateService.Delete>)
+ - [func \(service \*TemplateService\) Exists\(ctx context.Context, alias string\) \(bool, error\)](<#TemplateService.Exists>)
+ - [func \(service \*TemplateService\) Info\(ctx context.Context, templateID string, options \*TemplateInfoOptions\) \(\*TemplateWithBuilds, error\)](<#TemplateService.Info>)
+ - [func \(service \*TemplateService\) List\(ctx context.Context, options \*TemplateListOptions\) \(Page\[TemplateInfo\], error\)](<#TemplateService.List>)
+ - [func \(service \*TemplateService\) RemoveTags\(ctx context.Context, name string, tags \[\]string\) error](<#TemplateService.RemoveTags>)
+ - [func \(service \*TemplateService\) SetPublic\(ctx context.Context, templateID string, public bool\) \(\[\]string, error\)](<#TemplateService.SetPublic>)
+ - [func \(service \*TemplateService\) Tags\(ctx context.Context, templateID string\) \(\[\]TemplateTag, error\)](<#TemplateService.Tags>)
+- [type TemplateStep](<#TemplateStep>)
+- [type TemplateTag](<#TemplateTag>)
+- [type TemplateWithBuilds](<#TemplateWithBuilds>)
+- [type TimeoutError](<#TimeoutError>)
+ - [func \(e \*TimeoutError\) Error\(\) string](<#TimeoutError.Error>)
+ - [func \(e \*TimeoutError\) Unwrap\(\) error](<#TimeoutError.Unwrap>)
+- [type WatchHandle](<#WatchHandle>)
+ - [func \(handle \*WatchHandle\) Close\(\) error](<#WatchHandle.Close>)
+- [type WatchOptions](<#WatchOptions>)
+- [type WriteFile](<#WriteFile>)
+- [type WriteFileOptions](<#WriteFileOptions>)
+
+
+## Constants
+
+Version is the AgentBox SDK release version.
+
+ const Version = "0.1.2"
+
+
+## func IAMTokenPlaceholder
+
+ func IAMTokenPlaceholder(name string) (string, error)
+
+IAMTokenPlaceholder returns the value the egress proxy replaces with a freshly minted workload token.
+
+
+## func IAMTokenPlaceholders
+
+ func IAMTokenPlaceholders(names ...string) (map[string]string, error)
+
+IAMTokenPlaceholders returns placeholders for the supplied registered names.
+
+
+## func ValidateIAMTokenName
+
+ func ValidateIAMTokenName(name string) error
+
+ValidateIAMTokenName verifies that name can be embedded in the workload\-token placeholder grammar understood by the AgentBox egress proxy.
+
+
+## func WaitForFile
+
+ func WaitForFile(path string) string
+
+WaitForFile returns a readiness command that waits for a filesystem path.
+
+
+## func WaitForPort
+
+ func WaitForPort(port int) string
+
+WaitForPort returns a readiness command that waits for a listening port.
+
+
+## func WaitForProcess
+
+ func WaitForProcess(process string) string
+
+WaitForProcess returns a readiness command that waits for a named process.
+
+
+## func WaitForTimeout
+
+ func WaitForTimeout(timeout time.Duration) string
+
+WaitForTimeout waits a fixed duration before marking a service ready.
+
+
+## func WaitForURL
+
+ func WaitForURL(value string, status int) string
+
+WaitForURL returns a readiness command that waits for an HTTP status.
+
+
+## type APIError
+
+APIError describes a non\-successful HTTP or Connect response.
+
+ type APIError struct {
+ StatusCode int
+ Code string
+ Message string
+ Cause error
+ }
+
+
+### func \(\*APIError\) Error
+
+ func (e *APIError) Error() string
+
+Error formats the AgentBox API failure.
+
+
+### func \(\*APIError\) Unwrap
+
+ func (e *APIError) Unwrap() error
+
+Unwrap returns the underlying request error, if any.
+
+
+## type AptInstallOptions
+
+AptInstallOptions configures apt\-get.
+
+ type AptInstallOptions struct{ NoInstallRecommends, FixMissing bool }
+
+
+## type AuthenticationError
+
+AuthenticationError reports missing or invalid credentials.
+
+ type AuthenticationError struct{ APIError }
+
+
+### func \(\*AuthenticationError\) Error
+
+ func (e *AuthenticationError) Error() string
+
+Error formats the authentication failure.
+
+
+### func \(\*AuthenticationError\) Unwrap
+
+ func (e *AuthenticationError) Unwrap() error
+
+Unwrap returns the underlying authentication error, if any.
+
+
+## type BuildError
+
+BuildError reports a failed template build.
+
+ type BuildError struct{ APIError }
+
+
+### func \(\*BuildError\) Error
+
+ func (e *BuildError) Error() string
+
+Error formats the template build failure.
+
+
+### func \(\*BuildError\) Unwrap
+
+ func (e *BuildError) Unwrap() error
+
+Unwrap returns the underlying template build error, if any.
+
+
+## type BuildLogEntry
+
+BuildLogEntry is one structured template build log record.
+
+ type BuildLogEntry struct {
+ ID *string `json:"id,omitzero"`
+ Level string `json:"level"`
+ Message string `json:"message"`
+ Step *string `json:"step,omitzero"`
+ Timestamp time.Time `json:"timestamp"`
+ }
+
+
+## type BuildStatusReason
+
+BuildStatusReason explains a terminal template build status.
+
+ type BuildStatusReason struct {
+ LogEntries *[]BuildLogEntry `json:"logEntries,omitzero"`
+ Message string `json:"message"`
+ Step *string `json:"step,omitzero"`
+ }
+
+
+## type Client
+
+Client is an AgentBox control\-plane client.
+
+ type Client struct {
+ Sandboxes *SandboxService
+ Templates *TemplateService
+ // contains filtered or unexported fields
+ }
+
+###### Example
+
+
+
+
+ client, err := agentbox.NewClient()
+ if err != nil {
+ log.Fatal(err)
+ }
+ sandbox, err := client.Sandboxes.Create(context.Background(), nil)
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer sandbox.Kill(context.Background())
+ _, _ = sandbox.Commands.Run(context.Background(), "echo", &agentbox.CommandOptions{Args: []string{"hello"}})
+
+
+
+
+
+
+
+### func NewClient
+
+ func NewClient(options ...ClientOption) (*Client, error)
+
+NewClient creates a client. Configuration defaults to AGENTBOX\_\* environment variables and can be overridden with options.
+
+
+## type ClientOption
+
+ClientOption configures a Client.
+
+ type ClientOption func(*clientConfig) error
+
+
+### func WithAPIKey
+
+ func WithAPIKey(apiKey string) ClientOption
+
+WithAPIKey sets the AgentBox API key. By default AGENTBOX\_API\_KEY is used.
+
+
+### func WithAPIURL
+
+ func WithAPIURL(value string) ClientOption
+
+WithAPIURL overrides the control\-plane API URL.
+
+
+### func WithDebug
+
+ func WithDebug(enabled bool) ClientOption
+
+WithDebug enables local envd routing.
+
+
+### func WithDomain
+
+ func WithDomain(domain string) ClientOption
+
+WithDomain sets the AgentBox runtime domain.
+
+
+### func WithHTTPClient
+
+ func WithHTTPClient(client *http.Client) ClientOption
+
+WithHTTPClient supplies the HTTP client used for every request. Its Timeout applies to complete streaming requests as well as unary requests; leave it at zero and use contexts or operation options for long\-lived streams.
+
+
+### func WithHeaders
+
+ func WithHeaders(headers http.Header) ClientOption
+
+WithHeaders adds headers to control\-plane requests.
+
+
+### func WithLogger
+
+ func WithLogger(logger *slog.Logger) ClientOption
+
+WithLogger enables structured request and lifecycle logging.
+
+
+### func WithProxy
+
+ func WithProxy(value string) ClientOption
+
+WithProxy sets an HTTP or HTTPS proxy for SDK requests.
+
+
+### func WithRequestTimeout
+
+ func WithRequestTimeout(timeout time.Duration) ClientOption
+
+WithRequestTimeout sets the default unary request timeout. Zero disables it.
+
+
+### func WithSandboxURL
+
+ func WithSandboxURL(value string) ClientOption
+
+WithSandboxURL overrides the sandbox proxy URL.
+
+
+## type CommandExitError
+
+CommandExitError reports a process that completed with a non\-zero exit code.
+
+ type CommandExitError struct {
+ Result CommandResult
+ Message string
+ }
+
+
+### func \(\*CommandExitError\) Error
+
+ func (e *CommandExitError) Error() string
+
+Error describes the non\-zero command exit code.
+
+
+## type CommandHandle
+
+CommandHandle represents a streaming process. Wait can be called without draining the output channels and always returns the complete collected output.
+
+ type CommandHandle struct {
+ Stdout <-chan []byte
+ Stderr <-chan []byte
+ PTY <-chan []byte
+ Done <-chan struct{}
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*CommandHandle\) CloseStdin
+
+ func (handle *CommandHandle) CloseStdin(ctx context.Context) error
+
+CloseStdin signals EOF to a non\-PTY process.
+
+
+### func \(\*CommandHandle\) Kill
+
+ func (handle *CommandHandle) Kill(ctx context.Context) error
+
+Kill sends SIGKILL to this process.
+
+
+### func \(\*CommandHandle\) PID
+
+ func (handle *CommandHandle) PID(ctx context.Context) (uint32, error)
+
+PID waits for and returns the process identifier.
+
+
+### func \(\*CommandHandle\) Wait
+
+ func (handle *CommandHandle) Wait(ctx context.Context) (CommandResult, error)
+
+Wait waits for completion and returns collected output.
+
+
+### func \(\*CommandHandle\) Write
+
+ func (handle *CommandHandle) Write(ctx context.Context, data []byte) (int, error)
+
+Write writes bytes to process stdin.
+
+
+## type CommandOptions
+
+CommandOptions configures a command process.
+
+ type CommandOptions struct {
+ Args []string
+ Env map[string]string
+ Cwd string
+ Tag string
+ Stdin bool
+ OnStdout func([]byte)
+ OnStderr func([]byte)
+ }
+
+
+## type CommandResult
+
+CommandResult contains collected process output.
+
+ type CommandResult struct {
+ PID uint32
+ ExitCode int
+ Stdout []byte
+ Stderr []byte
+ Status string
+ }
+
+
+## type CommandService
+
+CommandService executes and manages sandbox processes.
+
+ type CommandService struct {
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*CommandService\) Connect
+
+ func (service *CommandService) Connect(ctx context.Context, pid uint32, tag string) (*CommandHandle, error)
+
+Connect attaches to an existing process by PID or tag.
+
+
+### func \(\*CommandService\) Kill
+
+ func (service *CommandService) Kill(ctx context.Context, pid uint32, tag string) error
+
+Kill sends SIGKILL to a process.
+
+
+### func \(\*CommandService\) List
+
+ func (service *CommandService) List(ctx context.Context) ([]ProcessInfo, error)
+
+List returns currently running processes.
+
+
+### func \(\*CommandService\) Run
+
+ func (service *CommandService) Run(ctx context.Context, command string, options *CommandOptions) (CommandResult, error)
+
+Run executes a foreground command and collects its output.
+
+
+### func \(\*CommandService\) Start
+
+ func (service *CommandService) Start(ctx context.Context, command string, options *CommandOptions) (*CommandHandle, error)
+
+Start starts a process and streams output through the returned handle.
+
+
+### func \(\*CommandService\) Terminate
+
+ func (service *CommandService) Terminate(ctx context.Context, pid uint32, tag string) error
+
+Terminate sends SIGTERM to a process.
+
+
+## type ConnectSandboxOptions
+
+ConnectSandboxOptions configures connecting or resuming a sandbox.
+
+ type ConnectSandboxOptions struct{ Timeout time.Duration }
+
+
+## type CopyOptions
+
+CopyOptions configures a COPY template layer.
+
+ type CopyOptions struct {
+ User string
+ Mode os.FileMode
+ ForceUpload bool
+ ResolveSymlinks bool
+ Gzip *bool
+ }
+
+
+## type CreateSandboxOptions
+
+CreateSandboxOptions configures a new sandbox.
+
+ type CreateSandboxOptions struct {
+ Template string
+ Timeout time.Duration
+ AutoPause *bool
+ AutoPauseMemory *bool
+ AutoResume *bool
+ Secure *bool
+ AllowInternetAccess *bool
+ Env map[string]string
+ Metadata map[string]string
+ Network *SandboxNetworkConfig
+ IAM *SandboxIAM
+ }
+
+
+## type EntryInfo
+
+EntryInfo describes a sandbox filesystem entry.
+
+ type EntryInfo struct {
+ Name string
+ Type FileType
+ Path string
+ Size int64
+ Mode uint32
+ Permissions string
+ Owner string
+ Group string
+ ModifiedAt time.Time
+ SymlinkTarget string
+ Metadata map[string]string
+ }
+
+
+## type FileEvent
+
+FileEvent describes a filesystem change.
+
+ type FileEvent struct {
+ Name string
+ Type string
+ Entry *EntryInfo
+ }
+
+
+## type FileNotFoundError
+
+FileNotFoundError reports a missing sandbox file.
+
+ type FileNotFoundError struct{ APIError }
+
+
+### func \(\*FileNotFoundError\) Error
+
+ func (e *FileNotFoundError) Error() string
+
+Error formats the missing\-file failure.
+
+
+### func \(\*FileNotFoundError\) Unwrap
+
+ func (e *FileNotFoundError) Unwrap() error
+
+Unwrap returns the underlying missing\-file error, if any.
+
+
+## type FileService
+
+FileService reads and mutates sandbox files.
+
+ type FileService struct {
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*FileService\) Exists
+
+ func (service *FileService) Exists(ctx context.Context, path string) (bool, error)
+
+Exists reports whether path exists.
+
+
+### func \(\*FileService\) List
+
+ func (service *FileService) List(ctx context.Context, path string, depth uint32) ([]EntryInfo, error)
+
+List lists path recursively up to depth.
+
+
+### func \(\*FileService\) MakeDir
+
+ func (service *FileService) MakeDir(ctx context.Context, path string) (*EntryInfo, error)
+
+MakeDir creates a directory.
+
+
+### func \(\*FileService\) Read
+
+ func (service *FileService) Read(ctx context.Context, path, user string) (io.ReadCloser, error)
+
+Read opens a streaming file response. The caller must close it.
+
+
+### func \(\*FileService\) ReadBytes
+
+ func (service *FileService) ReadBytes(ctx context.Context, path, user string) ([]byte, error)
+
+ReadBytes reads a complete file.
+
+
+### func \(\*FileService\) ReadText
+
+ func (service *FileService) ReadText(ctx context.Context, path, user string) (string, error)
+
+ReadText reads a UTF\-8 file as a string.
+
+
+### func \(\*FileService\) ReadTo
+
+ func (service *FileService) ReadTo(ctx context.Context, path, user string, writer io.Writer) (int64, error)
+
+ReadTo streams a file into writer.
+
+
+### func \(\*FileService\) Remove
+
+ func (service *FileService) Remove(ctx context.Context, path string) error
+
+Remove recursively removes a filesystem entry.
+
+
+### func \(\*FileService\) Rename
+
+ func (service *FileService) Rename(ctx context.Context, source, destination string) (*EntryInfo, error)
+
+Rename moves a filesystem entry.
+
+
+### func \(\*FileService\) SignedReadURL
+
+ func (service *FileService) SignedReadURL(path, user string, expiration time.Time) (string, error)
+
+SignedReadURL creates a directly usable download URL.
+
+
+### func \(\*FileService\) SignedWriteURL
+
+ func (service *FileService) SignedWriteURL(path, user string, expiration time.Time) (string, error)
+
+SignedWriteURL creates a directly usable upload URL.
+
+
+### func \(\*FileService\) Stat
+
+ func (service *FileService) Stat(ctx context.Context, path string) (*EntryInfo, error)
+
+Stat returns information about a path.
+
+
+### func \(\*FileService\) Watch
+
+ func (service *FileService) Watch(ctx context.Context, path string, options *WatchOptions) (*WatchHandle, error)
+
+Watch watches a directory until context cancellation or Close.
+
+
+### func \(\*FileService\) Write
+
+ func (service *FileService) Write(ctx context.Context, path string, reader io.Reader, options *WriteFileOptions) (*EntryInfo, error)
+
+Write uploads a file from reader.
+
+
+### func \(\*FileService\) WriteBatch
+
+ func (service *FileService) WriteBatch(ctx context.Context, files []WriteFile, user string) ([]EntryInfo, error)
+
+WriteBatch writes files in order and stops at the first failure.
+
+
+### func \(\*FileService\) WriteBytes
+
+ func (service *FileService) WriteBytes(ctx context.Context, path string, data []byte, options *WriteFileOptions) (*EntryInfo, error)
+
+WriteBytes uploads bytes.
+
+
+### func \(\*FileService\) WriteText
+
+ func (service *FileService) WriteText(ctx context.Context, path, text string, options *WriteFileOptions) (*EntryInfo, error)
+
+WriteText uploads a string.
+
+
+## type FileType
+
+FileType identifies a filesystem entry kind.
+
+ type FileType string
+
+
+
+ const (
+ // FileTypeFile identifies a regular file.
+ FileTypeFile FileType = "file"
+ // FileTypeDirectory identifies a directory.
+ FileTypeDirectory FileType = "dir"
+ // FileTypeSymlink identifies a symbolic link.
+ FileTypeSymlink FileType = "symlink"
+ )
+
+
+## type FileUploadError
+
+FileUploadError reports a failed template file upload.
+
+ type FileUploadError struct{ APIError }
+
+
+### func \(\*FileUploadError\) Error
+
+ func (e *FileUploadError) Error() string
+
+Error formats the file upload failure.
+
+
+### func \(\*FileUploadError\) Unwrap
+
+ func (e *FileUploadError) Unwrap() error
+
+Unwrap returns the underlying file upload error, if any.
+
+
+## type ForkOptions
+
+ForkOptions configures sandbox forks.
+
+ type ForkOptions struct {
+ Count int
+ Timeout time.Duration
+ }
+
+
+## type ForkResult
+
+ForkResult is one ordered fork outcome. Exactly one of Sandbox or Err is set.
+
+ type ForkResult struct {
+ Sandbox *Sandbox
+ Err error
+ }
+
+
+## type GitCloneOptions
+
+GitCloneOptions configures a git clone layer.
+
+ type GitCloneOptions struct {
+ Path, Branch, User string
+ Depth int
+ }
+
+
+## type InvalidArgumentError
+
+InvalidArgumentError reports invalid SDK input.
+
+ type InvalidArgumentError struct {
+ Message string
+ Cause error
+ }
+
+
+### func \(\*InvalidArgumentError\) Error
+
+ func (e *InvalidArgumentError) Error() string
+
+Error formats the invalid argument failure.
+
+
+### func \(\*InvalidArgumentError\) Unwrap
+
+ func (e *InvalidArgumentError) Unwrap() error
+
+Unwrap returns the underlying validation error, if any.
+
+
+## type ListSandboxOptions
+
+ListSandboxOptions filters one sandbox list page.
+
+ type ListSandboxOptions struct {
+ Metadata map[string]string
+ States []SandboxState
+ NextToken string
+ Limit int
+ }
+
+
+## type ListedSandbox
+
+ListedSandbox is a compact sandbox list entry.
+
+ type ListedSandbox struct {
+ Alias *string `json:"alias,omitzero"`
+ CPUCount int32 `json:"cpuCount"`
+ DiskSizeMB int32 `json:"diskSizeMB"`
+ EndAt time.Time `json:"endAt"`
+ EnvdVersion string `json:"envdVersion"`
+ MemoryMB int32 `json:"memoryMB"`
+ Metadata *SandboxMetadata `json:"metadata,omitzero"`
+ SandboxID string `json:"sandboxID"`
+ StartedAt time.Time `json:"startedAt"`
+ State SandboxState `json:"state"`
+ TemplateID string `json:"templateID"`
+ }
+
+
+## type MetricsOptions
+
+MetricsOptions selects a metrics interval.
+
+ type MetricsOptions struct{ Start, End time.Time }
+
+
+## type NotEnoughSpaceError
+
+NotEnoughSpaceError reports exhausted sandbox storage.
+
+ type NotEnoughSpaceError struct{ APIError }
+
+
+### func \(\*NotEnoughSpaceError\) Error
+
+ func (e *NotEnoughSpaceError) Error() string
+
+Error formats the storage\-capacity failure.
+
+
+### func \(\*NotEnoughSpaceError\) Unwrap
+
+ func (e *NotEnoughSpaceError) Unwrap() error
+
+Unwrap returns the underlying storage error, if any.
+
+
+## type PTYOptions
+
+PTYOptions configures an interactive terminal.
+
+ type PTYOptions struct {
+ Args []string
+ Env map[string]string
+ Cwd string
+ Tag string
+ Cols uint32
+ Rows uint32
+ OnPTY func([]byte)
+ }
+
+
+## type PTYService
+
+PTYService manages pseudo\-terminal processes.
+
+ type PTYService struct {
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*PTYService\) Connect
+
+ func (service *PTYService) Connect(ctx context.Context, pid uint32, tag string) (*CommandHandle, error)
+
+Connect attaches to an existing PTY process.
+
+
+### func \(\*PTYService\) Create
+
+ func (service *PTYService) Create(ctx context.Context, command string, options *PTYOptions) (*CommandHandle, error)
+
+Create starts a process attached to a pseudo\-terminal.
+
+
+### func \(\*PTYService\) Input
+
+ func (service *PTYService) Input(ctx context.Context, handle *CommandHandle, data []byte) error
+
+Input sends terminal input.
+
+
+### func \(\*PTYService\) Kill
+
+ func (service *PTYService) Kill(ctx context.Context, handle *CommandHandle) error
+
+Kill stops the terminal process.
+
+
+### func \(\*PTYService\) Resize
+
+ func (service *PTYService) Resize(ctx context.Context, handle *CommandHandle, cols, rows uint32) error
+
+Resize changes terminal dimensions.
+
+
+## type PackageInstallOptions
+
+PackageInstallOptions configures npm/bun installs.
+
+ type PackageInstallOptions struct{ Global, Dev bool }
+
+
+## type Page
+
+Page contains one page and an optional opaque continuation token.
+
+ type Page[T any] struct {
+ Items []T
+ NextToken string
+ }
+
+
+## type PauseOptions
+
+PauseOptions configures snapshot behavior while pausing.
+
+ type PauseOptions struct{ Memory *bool }
+
+
+## type ProcessInfo
+
+ProcessInfo describes a running envd process.
+
+ type ProcessInfo struct {
+ PID uint32
+ Tag string
+ Command string
+ Args []string
+ Env map[string]string
+ Cwd string
+ }
+
+
+## type RateLimitError
+
+RateLimitError reports an exhausted API quota.
+
+ type RateLimitError struct{ APIError }
+
+
+### func \(\*RateLimitError\) Error
+
+ func (e *RateLimitError) Error() string
+
+Error formats the rate\-limit failure.
+
+
+### func \(\*RateLimitError\) Unwrap
+
+ func (e *RateLimitError) Unwrap() error
+
+Unwrap returns the underlying rate\-limit error, if any.
+
+
+## type Sandbox
+
+Sandbox is a connected AgentBox sandbox.
+
+ type Sandbox struct {
+ ID string
+ TemplateID string
+ Alias string
+ Domain string
+ EnvdVersion string
+
+ Commands *CommandService
+ PTY *PTYService
+ Files *FileService
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*Sandbox\) CreateSnapshot
+
+ func (sandbox *Sandbox) CreateSnapshot(ctx context.Context, name string) (*SnapshotInfo, error)
+
+CreateSnapshot stores this sandbox as a template snapshot.
+
+
+### func \(\*Sandbox\) Fork
+
+ func (sandbox *Sandbox) Fork(ctx context.Context, options *ForkOptions) ([]ForkResult, error)
+
+Fork creates one or more sandboxes from this sandbox's current state.
+
+
+### func \(Sandbox\) GoString
+
+ func (sandbox Sandbox) GoString() string
+
+GoString returns a credential\-free sandbox description for %\#v formatting.
+
+
+### func \(\*Sandbox\) Host
+
+ func (sandbox *Sandbox) Host(port int) string
+
+Host returns the public hostname for a port exposed by the sandbox.
+
+
+### func \(\*Sandbox\) Info
+
+ func (sandbox *Sandbox) Info(ctx context.Context) (*SandboxInfo, error)
+
+Info returns information about this sandbox.
+
+
+### func \(\*Sandbox\) IsRunning
+
+ func (sandbox *Sandbox) IsRunning(ctx context.Context) (bool, error)
+
+IsRunning reports whether envd is reachable. A 502 response means the sandbox is no longer running.
+
+
+### func \(\*Sandbox\) KeepAlive
+
+ func (sandbox *Sandbox) KeepAlive(ctx context.Context, duration time.Duration) error
+
+KeepAlive extends the sandbox lifetime. A zero duration uses the server default.
+
+
+### func \(\*Sandbox\) Kill
+
+ func (sandbox *Sandbox) Kill(ctx context.Context) (bool, error)
+
+Kill permanently stops this sandbox. It returns false when it was not found.
+
+
+### func \(\*Sandbox\) Logs
+
+ func (sandbox *Sandbox) Logs(ctx context.Context, options *SandboxLogOptions) (Page[SandboxLogEntry], error)
+
+Logs returns one page of sandbox logs.
+
+
+### func \(\*Sandbox\) Metrics
+
+ func (sandbox *Sandbox) Metrics(ctx context.Context, options *MetricsOptions) ([]SandboxMetric, error)
+
+Metrics returns sandbox metrics for the requested interval.
+
+
+### func \(\*Sandbox\) Pause
+
+ func (sandbox *Sandbox) Pause(ctx context.Context, options *PauseOptions) error
+
+Pause pauses the sandbox, optionally retaining memory.
+
+
+### func \(\*Sandbox\) Request
+
+ func (sandbox *Sandbox) Request(ctx context.Context, port int, method, path string, body io.Reader, direct bool) (*http.Response, error)
+
+Request performs an authenticated request against a service inside the sandbox. Direct bypasses the stable proxy hostname while retaining AgentBox routing headers.
+
+
+### func \(\*Sandbox\) RequestTimeout
+
+ func (sandbox *Sandbox) RequestTimeout() time.Duration
+
+RequestTimeout returns the default unary request timeout configured on the client.
+
+
+### func \(\*Sandbox\) RequestWithOptions
+
+ func (sandbox *Sandbox) RequestWithOptions(ctx context.Context, port int, method, path string, body io.Reader, options *SandboxRequestOptions) (*http.Response, error)
+
+RequestWithOptions performs an authenticated request with custom headers.
+
+
+### func \(\*Sandbox\) SetTimeout
+
+ func (sandbox *Sandbox) SetTimeout(ctx context.Context, timeout time.Duration) error
+
+SetTimeout changes the sandbox expiration timeout from now.
+
+
+### func \(Sandbox\) String
+
+ func (sandbox Sandbox) String() string
+
+String returns a credential\-free sandbox description.
+
+
+### func \(\*Sandbox\) UpdateNetwork
+
+ func (sandbox *Sandbox) UpdateNetwork(ctx context.Context, config SandboxNetworkConfig, allowInternetAccess *bool) error
+
+UpdateNetwork atomically replaces sandbox egress rules.
+
+
+## type SandboxError
+
+SandboxError is the base error for sandbox operations.
+
+ type SandboxError struct{ APIError }
+
+
+### func \(\*SandboxError\) Error
+
+ func (e *SandboxError) Error() string
+
+Error formats the sandbox operation failure.
+
+
+### func \(\*SandboxError\) Unwrap
+
+ func (e *SandboxError) Unwrap() error
+
+Unwrap returns the underlying sandbox operation error, if any.
+
+
+## type SandboxIAM
+
+SandboxIAM configures workload identity tokens.
+
+ type SandboxIAM struct {
+ Tokens *SandboxIAMTokens `json:"tokens,omitzero"`
+ }
+
+
+## type SandboxIAMToken
+
+SandboxIAMToken configures one workload identity token.
+
+ type SandboxIAMToken struct {
+ Audience string `json:"audience"`
+ TokenType string `json:"tokenType"`
+ }
+
+
+## type SandboxIAMTokens
+
+SandboxIAMTokens contains named workload identity token definitions.
+
+ type SandboxIAMTokens map[string]SandboxIAMToken
+
+
+## type SandboxInfo
+
+SandboxInfo contains current sandbox state and configuration.
+
+ type SandboxInfo struct {
+ Alias *string `json:"alias,omitzero"`
+ AllowInternetAccess *bool `json:"allowInternetAccess,omitzero"`
+ CPUCount int32 `json:"cpuCount"`
+ DiskSizeMB int32 `json:"diskSizeMB"`
+ Domain *string `json:"domain,omitzero"`
+ EndAt time.Time `json:"endAt"`
+ EnvdVersion string `json:"envdVersion"`
+ Lifecycle *SandboxLifecycle `json:"lifecycle,omitzero"`
+ MemoryMB int32 `json:"memoryMB"`
+ Metadata *SandboxMetadata `json:"metadata,omitzero"`
+ Network *SandboxNetworkConfig `json:"network,omitzero"`
+ SandboxID string `json:"sandboxID"`
+ StartedAt time.Time `json:"startedAt"`
+ State SandboxState `json:"state"`
+ TemplateID string `json:"templateID"`
+ }
+
+
+## type SandboxLifecycle
+
+SandboxLifecycle describes timeout and auto\-resume behavior.
+
+ type SandboxLifecycle struct {
+ AutoResume bool `json:"autoResume"`
+ OnTimeout string `json:"onTimeout"`
+ }
+
+
+## type SandboxLogEntry
+
+SandboxLogEntry is one structured sandbox log record.
+
+ type SandboxLogEntry struct {
+ Fields map[string]string `json:"fields"`
+ ID *string `json:"id,omitzero"`
+ Level string `json:"level"`
+ Message string `json:"message"`
+ Timestamp time.Time `json:"timestamp"`
+ }
+
+
+## type SandboxLogOptions
+
+SandboxLogOptions filters one page of sandbox logs.
+
+ type SandboxLogOptions struct {
+ Cursor string
+ Timestamp int64
+ Limit int
+ Direction string
+ Level string
+ Search string
+ }
+
+
+## type SandboxMetadata
+
+SandboxMetadata contains user\-defined sandbox metadata.
+
+ type SandboxMetadata map[string]string
+
+
+## type SandboxMetric
+
+SandboxMetric is one timestamped resource\-usage sample.
+
+ type SandboxMetric struct {
+ CPUCount int32 `json:"cpuCount"`
+ CPUUsedPct float32 `json:"cpuUsedPct"`
+ DiskTotal int64 `json:"diskTotal"`
+ DiskUsed int64 `json:"diskUsed"`
+ MemCache int64 `json:"memCache"`
+ MemTotal int64 `json:"memTotal"`
+ MemUsed int64 `json:"memUsed"`
+ TimestampUnix int64 `json:"timestampUnix"`
+ }
+
+
+## type SandboxNetworkConfig
+
+SandboxNetworkConfig configures sandbox egress and public traffic.
+
+ type SandboxNetworkConfig struct {
+ AllowOut *[]string `json:"allowOut,omitzero"`
+ AllowPublicTraffic *bool `json:"allowPublicTraffic,omitzero"`
+ DenyOut *[]string `json:"denyOut,omitzero"`
+ MaskRequestHost *string `json:"maskRequestHost,omitzero"`
+ Rules *map[string][]SandboxNetworkRule `json:"rules,omitzero"`
+ }
+
+
+## type SandboxNetworkRule
+
+SandboxNetworkRule applies request transformations to matching traffic.
+
+ type SandboxNetworkRule struct {
+ Transform *SandboxNetworkTransform `json:"transform,omitzero"`
+ }
+
+
+## type SandboxNetworkTransform
+
+SandboxNetworkTransform describes headers injected into matching requests.
+
+ type SandboxNetworkTransform struct {
+ Headers *map[string]string `json:"headers,omitzero"`
+ }
+
+
+## type SandboxNotFoundError
+
+SandboxNotFoundError reports a missing or expired sandbox.
+
+ type SandboxNotFoundError struct{ APIError }
+
+
+### func \(\*SandboxNotFoundError\) Error
+
+ func (e *SandboxNotFoundError) Error() string
+
+Error formats the missing\-sandbox failure.
+
+
+### func \(\*SandboxNotFoundError\) Unwrap
+
+ func (e *SandboxNotFoundError) Unwrap() error
+
+Unwrap returns the underlying missing\-sandbox error, if any.
+
+
+## type SandboxRequestOptions
+
+SandboxRequestOptions configures a request to a service inside a sandbox.
+
+ type SandboxRequestOptions struct {
+ Direct bool
+ Headers http.Header
+ ContentType string
+ }
+
+
+## type SandboxService
+
+SandboxService manages sandboxes owned by a client.
+
+ type SandboxService struct {
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*SandboxService\) Connect
+
+ func (service *SandboxService) Connect(ctx context.Context, id string, options *ConnectSandboxOptions) (*Sandbox, error)
+
+Connect connects to or resumes a sandbox.
+
+
+### func \(\*SandboxService\) Create
+
+ func (service *SandboxService) Create(ctx context.Context, options *CreateSandboxOptions) (*Sandbox, error)
+
+Create starts and connects to a sandbox.
+
+
+### func \(\*SandboxService\) DeleteSnapshot
+
+ func (service *SandboxService) DeleteSnapshot(ctx context.Context, snapshotID string) (bool, error)
+
+DeleteSnapshot deletes a snapshot. It returns false when it did not exist.
+
+
+### func \(\*SandboxService\) Info
+
+ func (service *SandboxService) Info(ctx context.Context, id string) (*SandboxInfo, error)
+
+Info returns current sandbox state and configuration.
+
+
+### func \(\*SandboxService\) Kill
+
+ func (service *SandboxService) Kill(ctx context.Context, id string) (bool, error)
+
+Kill permanently stops a sandbox. It returns false when it did not exist.
+
+
+### func \(\*SandboxService\) List
+
+ func (service *SandboxService) List(ctx context.Context, options *ListSandboxOptions) (Page[ListedSandbox], error)
+
+List returns one list page. The continuation token is read from X\-Next\-Token.
+
+
+### func \(\*SandboxService\) Logs
+
+ func (service *SandboxService) Logs(ctx context.Context, id string, options *SandboxLogOptions) (Page[SandboxLogEntry], error)
+
+Logs returns one page of structured sandbox logs.
+
+
+### func \(\*SandboxService\) Metrics
+
+ func (service *SandboxService) Metrics(ctx context.Context, sandboxIDs ...string) (map[string]SandboxMetric, error)
+
+Metrics returns the latest metrics for the requested sandbox IDs.
+
+
+### func \(\*SandboxService\) Snapshots
+
+ func (service *SandboxService) Snapshots(ctx context.Context, options *SnapshotListOptions) (Page[SnapshotInfo], error)
+
+Snapshots returns one page of snapshots.
+
+
+## type SandboxState
+
+SandboxState is the lifecycle state of a sandbox.
+
+ type SandboxState string
+
+
+
+ const (
+ // SandboxRunning indicates that a sandbox accepts requests.
+ SandboxRunning SandboxState = "running"
+ // SandboxPaused indicates that a sandbox is suspended.
+ SandboxPaused SandboxState = "paused"
+ )
+
+
+## type SnapshotInfo
+
+SnapshotInfo identifies a saved sandbox snapshot.
+
+ type SnapshotInfo struct {
+ Names []string `json:"names"`
+ SnapshotID string `json:"snapshotID"`
+ }
+
+
+## type SnapshotListOptions
+
+SnapshotListOptions filters and paginates snapshots.
+
+ type SnapshotListOptions struct {
+ SandboxID string
+ Name string
+ NextToken string
+ Limit int
+ }
+
+
+## type TeamUser
+
+TeamUser identifies the user who created a template.
+
+ type TeamUser struct {
+ ID string `json:"id"`
+ }
+
+
+## type TemplateBuild
+
+TemplateBuild describes one historical template build.
+
+ type TemplateBuild struct {
+ BuildID string `json:"buildID"`
+ CPUCount int32 `json:"cpuCount"`
+ CreatedAt time.Time `json:"createdAt"`
+ DiskSizeMB *int32 `json:"diskSizeMB,omitzero"`
+ EnvdVersion *string `json:"envdVersion,omitzero"`
+ FinishedAt *time.Time `json:"finishedAt,omitzero"`
+ MemoryMB int32 `json:"memoryMB"`
+ Status TemplateBuildStatus `json:"status"`
+ UpdatedAt time.Time `json:"updatedAt"`
+ }
+
+
+## type TemplateBuildInfo
+
+TemplateBuildInfo contains the latest status and logs for a build.
+
+ type TemplateBuildInfo struct {
+ BuildID string `json:"buildID"`
+ LogEntries []BuildLogEntry `json:"logEntries"`
+ Logs []string `json:"logs"`
+ Reason *BuildStatusReason `json:"reason,omitzero"`
+ Status TemplateBuildStatus `json:"status"`
+ TemplateID string `json:"templateID"`
+ }
+
+
+## type TemplateBuildOptions
+
+TemplateBuildOptions configures resources, tags, caching, and build polling.
+
+ type TemplateBuildOptions struct {
+ Tags []string
+ CPUCount, MemoryMB int
+ SkipCache bool
+ PollInterval time.Duration
+ OnLog func(BuildLogEntry)
+ }
+
+
+## type TemplateBuildRef
+
+TemplateBuildRef identifies a started template build.
+
+ type TemplateBuildRef struct {
+ Name string
+ Tags []string
+ TemplateID, BuildID string
+ }
+
+
+## type TemplateBuildStatus
+
+TemplateBuildStatus is a template build state.
+
+ type TemplateBuildStatus string
+
+
+
+ const (
+ // BuildWaiting indicates that a template build is queued.
+ BuildWaiting TemplateBuildStatus = "waiting"
+ // BuildBuilding indicates that a template build is in progress.
+ BuildBuilding TemplateBuildStatus = "building"
+ // BuildReady indicates that a template build completed successfully.
+ BuildReady TemplateBuildStatus = "ready"
+ // BuildFailed indicates that a template build failed.
+ BuildFailed TemplateBuildStatus = "error"
+ )
+
+
+## type TemplateBuilder
+
+TemplateBuilder builds a declarative template definition.
+
+ type TemplateBuilder struct {
+ // contains filtered or unexported fields
+ }
+
+###### Example
+
+
+
+
+ template := agentbox.NewTemplate(".").FromPython("3.13").Copy("requirements.txt", "/app/", nil).PipInstall().Workdir("/app")
+ _, _ = template.JSON()
+
+
+
+
+
+
+
+### func NewTemplate
+
+ func NewTemplate(contextPath string, ignore ...string) *TemplateBuilder
+
+NewTemplate starts a template definition. Empty contextPath uses the current directory.
+
+
+### func \(\*TemplateBuilder\) AptInstall
+
+ func (builder *TemplateBuilder) AptInstall(options AptInstallOptions, packages ...string) *TemplateBuilder
+
+AptInstall installs Debian packages as root.
+
+
+### func \(\*TemplateBuilder\) BunInstall
+
+ func (builder *TemplateBuilder) BunInstall(options PackageInstallOptions, packages ...string) *TemplateBuilder
+
+BunInstall installs Bun packages with the requested scope.
+
+
+### func \(\*TemplateBuilder\) Copy
+
+ func (builder *TemplateBuilder) Copy(source, destination string, options *CopyOptions) *TemplateBuilder
+
+Copy adds a file or directory from the context.
+
+
+### func \(\*TemplateBuilder\) Dockerfile
+
+ func (builder *TemplateBuilder) Dockerfile() string
+
+Dockerfile returns a human\-readable equivalent definition.
+
+
+### func \(\*TemplateBuilder\) Env
+
+ func (builder *TemplateBuilder) Env(values map[string]string) *TemplateBuilder
+
+Env sets environment variables for subsequent template steps.
+
+
+### func \(\*TemplateBuilder\) FromAWSRegistry
+
+ func (builder *TemplateBuilder) FromAWSRegistry(image, accessKeyID, secretAccessKey, region string) *TemplateBuilder
+
+FromAWSRegistry selects an AWS ECR image.
+
+
+### func \(\*TemplateBuilder\) FromAlpine
+
+ func (builder *TemplateBuilder) FromAlpine(variant string) *TemplateBuilder
+
+FromAlpine selects an official Alpine image, defaulting to version 3.24.
+
+
+### func \(\*TemplateBuilder\) FromArch
+
+ func (builder *TemplateBuilder) FromArch(variant string) *TemplateBuilder
+
+FromArch selects an official Arch Linux image.
+
+
+### func \(\*TemplateBuilder\) FromBase
+
+ func (builder *TemplateBuilder) FromBase() *TemplateBuilder
+
+FromBase selects the default AgentBox base image.
+
+
+### func \(\*TemplateBuilder\) FromBun
+
+ func (builder *TemplateBuilder) FromBun(variant string) *TemplateBuilder
+
+FromBun selects an official Bun image.
+
+
+### func \(\*TemplateBuilder\) FromDebian
+
+ func (builder *TemplateBuilder) FromDebian(variant string) *TemplateBuilder
+
+FromDebian selects an official Debian image, defaulting to stable.
+
+
+### func \(\*TemplateBuilder\) FromDockerfile
+
+ func (builder *TemplateBuilder) FromDockerfile(contentOrPath string) *TemplateBuilder
+
+FromDockerfile parses common FROM/RUN/COPY/ENV/WORKDIR/USER directives.
+
+
+### func \(\*TemplateBuilder\) FromFedora
+
+ func (builder *TemplateBuilder) FromFedora(variant string) *TemplateBuilder
+
+FromFedora selects an official Fedora image, defaulting to version 44.
+
+
+### func \(\*TemplateBuilder\) FromGCPRegistry
+
+ func (builder *TemplateBuilder) FromGCPRegistry(image, serviceAccountJSON string) *TemplateBuilder
+
+FromGCPRegistry selects a GCP Artifact Registry image.
+
+
+### func \(\*TemplateBuilder\) FromImage
+
+ func (builder *TemplateBuilder) FromImage(image string) *TemplateBuilder
+
+FromImage selects an OCI image.
+
+
+### func \(\*TemplateBuilder\) FromNode
+
+ func (builder *TemplateBuilder) FromNode(variant string) *TemplateBuilder
+
+FromNode selects an official Node.js image, defaulting to the LTS variant.
+
+
+### func \(\*TemplateBuilder\) FromPython
+
+ func (builder *TemplateBuilder) FromPython(version string) *TemplateBuilder
+
+FromPython selects an official Python image.
+
+
+### func \(\*TemplateBuilder\) FromRegistry
+
+ func (builder *TemplateBuilder) FromRegistry(image, username, password string) *TemplateBuilder
+
+FromRegistry selects a password\-authenticated OCI registry image.
+
+
+### func \(\*TemplateBuilder\) FromTemplate
+
+ func (builder *TemplateBuilder) FromTemplate(template string) *TemplateBuilder
+
+FromTemplate selects another AgentBox template.
+
+
+### func \(\*TemplateBuilder\) FromUbuntu
+
+ func (builder *TemplateBuilder) FromUbuntu(variant string) *TemplateBuilder
+
+FromUbuntu selects an official Ubuntu image, defaulting to latest.
+
+
+### func \(\*TemplateBuilder\) GitClone
+
+ func (builder *TemplateBuilder) GitClone(repository string, options *GitCloneOptions) *TemplateBuilder
+
+GitClone clones a Git repository into the template filesystem.
+
+
+### func \(\*TemplateBuilder\) JSON
+
+ func (builder *TemplateBuilder) JSON() ([]byte, error)
+
+JSON returns the build request representation without computed copy hashes.
+
+
+### func \(\*TemplateBuilder\) MakeDir
+
+ func (builder *TemplateBuilder) MakeDir(paths ...string) *TemplateBuilder
+
+MakeDir creates directories and their missing parents.
+
+
+### func \(\*TemplateBuilder\) NPMInstall
+
+ func (builder *TemplateBuilder) NPMInstall(options PackageInstallOptions, packages ...string) *TemplateBuilder
+
+NPMInstall installs npm packages with the requested scope.
+
+
+### func \(\*TemplateBuilder\) PipInstall
+
+ func (builder *TemplateBuilder) PipInstall(packages ...string) *TemplateBuilder
+
+PipInstall installs Python packages as root.
+
+
+### func \(\*TemplateBuilder\) Ready
+
+ func (builder *TemplateBuilder) Ready(command string) *TemplateBuilder
+
+Ready replaces the readiness command for the template.
+
+
+### func \(\*TemplateBuilder\) Remove
+
+ func (builder *TemplateBuilder) Remove(paths ...string) *TemplateBuilder
+
+Remove recursively removes paths from the template filesystem.
+
+
+### func \(\*TemplateBuilder\) Rename
+
+ func (builder *TemplateBuilder) Rename(source, destination string) *TemplateBuilder
+
+Rename moves a path in the template filesystem.
+
+
+### func \(\*TemplateBuilder\) Run
+
+ func (builder *TemplateBuilder) Run(commands ...string) *TemplateBuilder
+
+Run adds shell commands executed as the current build user.
+
+
+### func \(\*TemplateBuilder\) RunAs
+
+ func (builder *TemplateBuilder) RunAs(user string, commands ...string) *TemplateBuilder
+
+RunAs adds shell commands executed as user.
+
+
+### func \(\*TemplateBuilder\) SkipCache
+
+ func (builder *TemplateBuilder) SkipCache() *TemplateBuilder
+
+SkipCache forces this and all subsequent layers.
+
+
+### func \(\*TemplateBuilder\) Start
+
+ func (builder *TemplateBuilder) Start(command, readyCommand string) *TemplateBuilder
+
+Start configures the sandbox start command and readiness command.
+
+
+### func \(\*TemplateBuilder\) Symlink
+
+ func (builder *TemplateBuilder) Symlink(source, destination string) *TemplateBuilder
+
+Symlink creates a symbolic link.
+
+
+### func \(\*TemplateBuilder\) User
+
+ func (builder *TemplateBuilder) User(user string) *TemplateBuilder
+
+User sets the user for subsequent template steps.
+
+
+### func \(\*TemplateBuilder\) Workdir
+
+ func (builder *TemplateBuilder) Workdir(path string) *TemplateBuilder
+
+Workdir sets the working directory for subsequent template steps.
+
+
+## type TemplateError
+
+TemplateError reports an invalid or incompatible template.
+
+ type TemplateError struct{ APIError }
+
+
+### func \(\*TemplateError\) Error
+
+ func (e *TemplateError) Error() string
+
+Error formats the template operation failure.
+
+
+### func \(\*TemplateError\) Unwrap
+
+ func (e *TemplateError) Unwrap() error
+
+Unwrap returns the underlying template operation error, if any.
+
+
+## type TemplateInfo
+
+TemplateInfo is a compact template list entry.
+
+ type TemplateInfo struct {
+ BuildCount int32 `json:"buildCount"`
+ BuildID string `json:"buildID"`
+ BuildStatus TemplateBuildStatus `json:"buildStatus"`
+ CPUCount int32 `json:"cpuCount"`
+ CreatedAt time.Time `json:"createdAt"`
+ CreatedBy *TeamUser `json:"createdBy,omitzero"`
+ DiskSizeMB int32 `json:"diskSizeMB"`
+ EnvdVersion string `json:"envdVersion"`
+ LastSpawnedAt *time.Time `json:"lastSpawnedAt,omitzero"`
+ MemoryMB int32 `json:"memoryMB"`
+ Names []string `json:"names"`
+ Public bool `json:"public"`
+ SpawnCount int64 `json:"spawnCount"`
+ TemplateID string `json:"templateID"`
+ UpdatedAt time.Time `json:"updatedAt"`
+ }
+
+
+## type TemplateInfoOptions
+
+TemplateInfoOptions paginates a template's build history.
+
+ type TemplateInfoOptions struct {
+ NextToken string
+ Limit int
+ }
+
+
+## type TemplateListOptions
+
+TemplateListOptions configures template pagination and team filtering.
+
+ type TemplateListOptions struct {
+ TeamID, NextToken string
+ Limit int
+ }
+
+
+## type TemplateLogOptions
+
+TemplateLogOptions configures template log pagination and filtering.
+
+ type TemplateLogOptions struct {
+ Cursor string
+ Timestamp int64
+ Limit int
+ Direction, Level, Source string
+ }
+
+
+## type TemplateService
+
+TemplateService manages AgentBox templates.
+
+ type TemplateService struct {
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*TemplateService\) AssignTags
+
+ func (service *TemplateService) AssignTags(ctx context.Context, target string, tags []string) (string, error)
+
+AssignTags assigns tags to a template target and returns the selected build ID.
+
+
+### func \(\*TemplateService\) Build
+
+ func (service *TemplateService) Build(ctx context.Context, builder *TemplateBuilder, name string, options *TemplateBuildOptions) (*TemplateBuildRef, error)
+
+Build starts a build and waits for a terminal state.
+
+
+### func \(\*TemplateService\) BuildInBackground
+
+ func (service *TemplateService) BuildInBackground(ctx context.Context, builder *TemplateBuilder, name string, options *TemplateBuildOptions) (*TemplateBuildRef, error)
+
+BuildInBackground uploads COPY contexts and starts a build.
+
+
+### func \(\*TemplateService\) BuildLogs
+
+ func (service *TemplateService) BuildLogs(ctx context.Context, templateID, buildID string, options *TemplateLogOptions) (Page[BuildLogEntry], error)
+
+BuildLogs returns one page of structured build logs.
+
+
+### func \(\*TemplateService\) BuildStatus
+
+ func (service *TemplateService) BuildStatus(ctx context.Context, templateID, buildID string, logsOffset int) (*TemplateBuildInfo, error)
+
+BuildStatus returns the current build state and logs after logsOffset.
+
+
+### func \(\*TemplateService\) Delete
+
+ func (service *TemplateService) Delete(ctx context.Context, templateID string) error
+
+Delete removes a template.
+
+
+### func \(\*TemplateService\) Exists
+
+ func (service *TemplateService) Exists(ctx context.Context, alias string) (bool, error)
+
+Exists reports whether a template alias exists or is reserved.
+
+
+### func \(\*TemplateService\) Info
+
+ func (service *TemplateService) Info(ctx context.Context, templateID string, options *TemplateInfoOptions) (*TemplateWithBuilds, error)
+
+Info returns a template and its build history.
+
+
+### func \(\*TemplateService\) List
+
+ func (service *TemplateService) List(ctx context.Context, options *TemplateListOptions) (Page[TemplateInfo], error)
+
+List returns one template page.
+
+
+### func \(\*TemplateService\) RemoveTags
+
+ func (service *TemplateService) RemoveTags(ctx context.Context, name string, tags []string) error
+
+RemoveTags removes tags from a named template.
+
+
+### func \(\*TemplateService\) SetPublic
+
+ func (service *TemplateService) SetPublic(ctx context.Context, templateID string, public bool) ([]string, error)
+
+SetPublic changes template visibility and returns its names.
+
+
+### func \(\*TemplateService\) Tags
+
+ func (service *TemplateService) Tags(ctx context.Context, templateID string) ([]TemplateTag, error)
+
+Tags lists tags assigned to a template.
+
+
+## type TemplateStep
+
+TemplateStep is one layer in a template build.
+
+ type TemplateStep struct {
+ Type string `json:"type"`
+ Args []string `json:"args"`
+ Force bool `json:"force"`
+ FilesHash string `json:"filesHash,omitempty"`
+ ForceUpload bool `json:"forceUpload,omitempty"`
+ ResolveSymlinks bool `json:"resolveSymlinks,omitempty"`
+ Gzip bool `json:"gzip,omitempty"`
+ }
+
+
+## type TemplateTag
+
+TemplateTag associates a template tag with a build.
+
+ type TemplateTag struct {
+ Tag, BuildID string
+ CreatedAt time.Time
+ }
+
+
+## type TemplateWithBuilds
+
+TemplateWithBuilds contains a template and its build history.
+
+ type TemplateWithBuilds struct {
+ Builds []TemplateBuild `json:"builds"`
+ CreatedAt time.Time `json:"createdAt"`
+ LastSpawnedAt *time.Time `json:"lastSpawnedAt,omitzero"`
+ Names []string `json:"names"`
+ Public bool `json:"public"`
+ SpawnCount int64 `json:"spawnCount"`
+ TemplateID string `json:"templateID"`
+ UpdatedAt time.Time `json:"updatedAt"`
+ }
+
+
+## type TimeoutError
+
+TimeoutError reports a request, execution, or sandbox timeout.
+
+ type TimeoutError struct{ APIError }
+
+
+### func \(\*TimeoutError\) Error
+
+ func (e *TimeoutError) Error() string
+
+Error formats the timeout failure.
+
+
+### func \(\*TimeoutError\) Unwrap
+
+ func (e *TimeoutError) Unwrap() error
+
+Unwrap returns the underlying timeout error, if any.
+
+
+## type WatchHandle
+
+WatchHandle owns a directory watch stream.
+
+ type WatchHandle struct {
+ Events <-chan FileEvent
+ // contains filtered or unexported fields
+ }
+
+
+### func \(\*WatchHandle\) Close
+
+ func (handle *WatchHandle) Close() error
+
+Close stops the watcher.
+
+
+## type WatchOptions
+
+WatchOptions configures recursive and enriched filesystem events.
+
+ type WatchOptions struct{ Recursive, IncludeEntry, AllowNetworkMounts bool }
+
+
+## type WriteFile
+
+WriteFile describes one batch upload.
+
+ type WriteFile struct {
+ Path string
+ Data io.Reader
+ Metadata map[string]string
+ }
+
+
+## type WriteFileOptions
+
+WriteFileOptions configures file ownership, metadata, and upload timeout.
+
+ type WriteFileOptions struct {
+ User string
+ Metadata map[string]string
+ // RequestTimeout limits the complete streaming upload. Zero leaves the
+ // upload bounded only by ctx and a custom HTTP client timeout.
+ RequestTimeout time.Duration
+ }
+
+Generated by [gomarkdoc]()
diff --git a/scripts/check-go-docs.go b/scripts/check-go-docs.go
new file mode 100644
index 00000000..41ef6cca
--- /dev/null
+++ b/scripts/check-go-docs.go
@@ -0,0 +1,96 @@
+// Command check-go-docs verifies that every exported Go declaration has a
+// documentation comment suitable for GoDoc.
+package main
+
+import (
+ "fmt"
+ "go/ast"
+ "go/parser"
+ "go/token"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+)
+
+func main() {
+ if len(os.Args) < 2 {
+ fmt.Fprintln(os.Stderr, "usage: check-go-docs ...")
+ os.Exit(2)
+ }
+
+ var missing []string
+ for _, directory := range os.Args[1:] {
+ missing = append(missing, undocumented(directory)...)
+ }
+ sort.Strings(missing)
+ if len(missing) > 0 {
+ fmt.Fprintln(os.Stderr, "Exported Go declarations need documentation:")
+ for _, declaration := range missing {
+ fmt.Fprintf(os.Stderr, " %s\n", declaration)
+ }
+ os.Exit(1)
+ }
+}
+
+func undocumented(directory string) []string {
+ files, err := parser.ParseDir(token.NewFileSet(), directory, func(info os.FileInfo) bool {
+ return !strings.HasSuffix(info.Name(), "_test.go")
+ }, parser.ParseComments)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "parse %s: %v\n", directory, err)
+ os.Exit(1)
+ }
+
+ var missing []string
+ for _, packageFiles := range files {
+ for filename, file := range packageFiles.Files {
+ for _, declaration := range file.Decls {
+ switch declaration := declaration.(type) {
+ case *ast.FuncDecl:
+ if exportedFunction(declaration) && declaration.Doc == nil {
+ missing = append(missing, location(filename, declaration.Name.Name))
+ }
+ case *ast.GenDecl:
+ for _, specification := range declaration.Specs {
+ switch specification := specification.(type) {
+ case *ast.TypeSpec:
+ if specification.Name.IsExported() && declaration.Doc == nil && specification.Doc == nil {
+ missing = append(missing, location(filename, specification.Name.Name))
+ }
+ case *ast.ValueSpec:
+ for _, name := range specification.Names {
+ if name.IsExported() && declaration.Doc == nil && specification.Doc == nil {
+ missing = append(missing, location(filename, name.Name))
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ return missing
+}
+
+func exportedFunction(declaration *ast.FuncDecl) bool {
+ if !declaration.Name.IsExported() {
+ return false
+ }
+ if declaration.Recv == nil {
+ return true
+ }
+ if len(declaration.Recv.List) != 1 {
+ return false
+ }
+ receiver := declaration.Recv.List[0].Type
+ if pointer, ok := receiver.(*ast.StarExpr); ok {
+ receiver = pointer.X
+ }
+ name, ok := receiver.(*ast.Ident)
+ return ok && name.IsExported()
+}
+
+func location(filename, name string) string {
+ return filepath.ToSlash(filename) + ": " + name
+}
diff --git a/scripts/check-release-versions.mjs b/scripts/check-release-versions.mjs
index 7fafb23e..0fb53f85 100644
--- a/scripts/check-release-versions.mjs
+++ b/scripts/check-release-versions.mjs
@@ -27,6 +27,17 @@ if (goVersion !== expected)
`packages/go-sdk/version.go: expected ${expected}, got ${goVersion}`
)
+const goReadme = fs.readFileSync('packages/go-sdk/README.md', 'utf8')
+for (const packagePath of [
+ 'github.com/abox-dev/sdk/packages/go-sdk',
+ 'github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter',
+]) {
+ const reference = `https://pkg.go.dev/${packagePath}@v${expected}`
+ if (!goReadme.includes(reference)) {
+ throw new Error(`packages/go-sdk/README.md: missing ${reference}`)
+ }
+}
+
for (const manifest of [
'packages/python-sdk/pyproject.toml',
'packages/code-interpreter-python/pyproject.toml',
diff --git a/scripts/generate-reference.py b/scripts/generate-reference.py
index 9a3bffd5..3f2f5c08 100644
--- a/scripts/generate-reference.py
+++ b/scripts/generate-reference.py
@@ -1120,6 +1120,31 @@ def run_sdk_generators() -> None:
check=True,
)
+ for package, output in (
+ (ROOT / "packages/go-sdk", OUT / "sdk/go/core.md"),
+ (
+ ROOT / "packages/go-sdk/codeinterpreter",
+ OUT / "sdk/go/code-interpreter.md",
+ ),
+ ):
+ output.parent.mkdir(parents=True, exist_ok=True)
+ subprocess.run(
+ [
+ "gomarkdoc",
+ "--format",
+ "plain",
+ "--output",
+ str(output),
+ ".",
+ ],
+ cwd=package,
+ check=True,
+ )
+ output.write_text(
+ "\n".join(line.rstrip() for line in output.read_text().splitlines())
+ + "\n"
+ )
+
def package_versions() -> dict:
packages = {
@@ -1139,6 +1164,11 @@ def package_versions() -> dict:
versions[name] = re.search(
r'^version = "([^"]+)"', path.read_text(), re.M
).group(1)
+ versions["github.com/abox-dev/sdk/packages/go-sdk"] = re.search(
+ r'^const Version = "([^"]+)"',
+ (ROOT / "packages/go-sdk/version.go").read_text(),
+ re.M,
+ ).group(1)
return versions
diff --git a/scripts/set-release-version.mjs b/scripts/set-release-version.mjs
index 3ea7dcc7..3a053f0c 100644
--- a/scripts/set-release-version.mjs
+++ b/scripts/set-release-version.mjs
@@ -67,4 +67,21 @@ fs.writeFileSync(
)
)
+const goReadmeFile = path.join(root, 'packages/go-sdk/README.md')
+const goReadmeContent = fs.readFileSync(goReadmeFile, 'utf8')
+const goReferenceVersion = new RegExp(
+ `(https://pkg\\.go\\.dev/github\\.com/abox-dev/sdk/packages/go-sdk(?:/codeinterpreter)?@)v${goVersion.replaceAll('.', '\\.')}`,
+ 'g'
+)
+const goReadmeUpdated = goReadmeContent.replace(
+ goReferenceVersion,
+ `$1v${version}`
+)
+if (goReadmeUpdated === goReadmeContent && version !== goVersion) {
+ throw new Error(
+ 'Cannot update versioned pkg.go.dev links in packages/go-sdk/README.md'
+ )
+}
+fs.writeFileSync(goReadmeFile, goReadmeUpdated)
+
process.stdout.write(`Updated all AgentBox SDK packages to ${version}\n`)
diff --git a/scripts/test-reference-contract.py b/scripts/test-reference-contract.py
index 68175cb0..12354266 100644
--- a/scripts/test-reference-contract.py
+++ b/scripts/test-reference-contract.py
@@ -165,6 +165,15 @@ def assert_only_reachable_components(document: dict) -> None:
def main() -> None:
manifest = json.loads((REFERENCE / "manifest.json").read_text())
assert manifest["schemaVersion"] == 1
+ assert manifest["packages"]["github.com/abox-dev/sdk/packages/go-sdk"] == re.search(
+ r'^const Version = "([^"]+)"',
+ (ROOT / "packages/go-sdk/version.go").read_text(),
+ re.M,
+ ).group(1)
+ assert {
+ "sdk/go/core.md",
+ "sdk/go/code-interpreter.md",
+ } <= set(manifest["files"])
for relative, expected in manifest["files"].items():
actual = hashlib.sha256((REFERENCE / relative).read_bytes()).hexdigest()
assert actual == expected, relative
@@ -372,6 +381,28 @@ def main() -> None:
)
assert "[object Object]" not in cli_markdown
+ go_core = (REFERENCE / "sdk/go/core.md").read_text()
+ go_code_interpreter = (REFERENCE / "sdk/go/code-interpreter.md").read_text()
+ for rendered, package, signatures in (
+ (
+ go_core,
+ 'import "github.com/abox-dev/sdk/packages/go-sdk"',
+ ("func NewClient", "type Sandbox", "Start(ctx context.Context"),
+ ),
+ (
+ go_code_interpreter,
+ 'import "github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter"',
+ ("func NewClient", "type Execution", "RunCode(ctx context.Context"),
+ ),
+ ):
+ assert rendered.startswith("")
+ assert package in rendered
+ assert "blob/main" not in rendered
+ assert "github.com/abox-dev/sdk/blob/" not in rendered
+ assert "](<#" in rendered
+ for signature in signatures:
+ assert signature in rendered
+
process_reference = (REFERENCE / "connect/process.md").read_text()
for value in (
"Production base URL: `https://sandbox.agentbox-runtime.ru`",