abox-dev · muxx · Sep 3, 2026 · Sep 3, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -32,13 +32,68 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.27.x'
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
       - run: pnpm install --frozen-lockfile
       - run: uv sync --project packages/python-sdk --frozen
       - run: uv sync --project packages/code-interpreter-python --frozen
       - run: pnpm format:check
       - run: pnpm lint
       - run: pnpm typecheck
       - 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
+
+  go-test:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        go: ['1.24.x', '1.25.x', '1.26.x', '1.27.x']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v6
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
+      - run: go build ./...
+        working-directory: packages/go-sdk
+      - run: go test ./...
+        working-directory: packages/go-sdk
+
+  go-race:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.27.x'
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
+      - run: go test -race ./...
+        working-directory: packages/go-sdk
+
+  go-cross-build:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        go: ['1.24.x', '1.27.x']
+        goos: [linux, darwin, windows]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v6
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
+      - run: GOOS=${{ matrix.goos }} GOARCH=amd64 CGO_ENABLED=0 go build ./...
+        working-directory: packages/go-sdk
 
   deterministic-codegen:
     runs-on: ubuntu-24.04
@@ -51,6 +106,11 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.24.x'
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
       - run: pnpm install --frozen-lockfile
       - run: make generate
       - run: git diff --exit-code

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -26,10 +26,23 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.24.13'
+          cache: true
+          cache-dependency-path: packages/go-sdk/go.sum
       - run: pnpm install --frozen-lockfile
       - run: uv sync --project packages/python-sdk --frozen
       - run: uv sync --project packages/code-interpreter-python --frozen
       - run: node scripts/check-release-versions.mjs "${GITHUB_REF_NAME}"
+      - name: Verify matching Go module tag
+        run: |
+          go_tag="packages/go-sdk/${GITHUB_REF_NAME}"
+          go_commit=$(git ls-remote origin "refs/tags/${go_tag}^{}" | cut -f1)
+          test "$go_commit" = "$GITHUB_SHA"
+      - run: go test ./...
+        working-directory: packages/go-sdk
+      - run: make go-consumer-check
       - run: ./scripts/build-release.sh
       - run: node scripts/check-public-artifacts.mjs release
       - run: ./scripts/test-release-artifacts.sh
@@ -122,3 +135,17 @@ jobs:
             release/npm/*.tgz
             release/pypi/*
             release/pypi-code-interpreter/*
+
+  go-proxy-smoke:
+    needs: github-release
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.24.13'
+      - run: |
+          mkdir consumer
+          cd consumer
+          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
diff --git a/.tool-versions b/.tool-versions
@@ -1,4 +1,5 @@
 deno 2.8.1
+golang 1.24.13
 nodejs 22.18.0
 pnpm 10.34.5
 python 3.10

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,8 +1,17 @@
-Use pnpm for JavaScript packages and uv for Python packages.
+Use pnpm for JavaScript packages, uv for Python packages, and Go modules for Go packages.
 Use English exclusively in source code, comments, documentation, commit messages, and GitHub pull request titles and descriptions.
-Keep the JavaScript and Python SDKs, including sync and async Python APIs, behaviorally aligned.
-Run format checks, lint, type checks, unit tests, deterministic generation, builds, and package-install checks before committing.
+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.
 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.
+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.
 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.
+
+When a new Go version is released:
+
+- Treat the `packages/go-sdk/go.mod` directive as the only source of the minimum supported Go version. Raise it only when intentionally ending support for an older release.
+- Update the exact local patch version in `.tool-versions` and the Go builder in `codegen.Dockerfile`; generated code must still compile with the minimum version from `packages/go-sdk/go.mod`.
+- Keep `.github/workflows/ci.yml` on a continuous matrix of every Go minor release from the `packages/go-sdk/go.mod` minimum through the current stable release. Add new minors when released; remove old minors only when raising the minimum.
+- Update the Go toolchain used by `.github/workflows/release.yml` and the supported-version instructions in `RELEASING.md`.
+- For a patch release, update exact tooling pins. For a minor release, add the CI matrix entry. When raising the minimum, update `packages/go-sdk/go.mod`, all pins, CI, and documentation in the same change.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing
 
-Open an issue or pull request at [abox-dev/sdk](https://github.com/abox-dev/sdk). Include tests for behavior changes and keep JavaScript and Python APIs aligned where applicable.
+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`.
 
 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/LICENSE b/LICENSE
@@ -187,6 +187,7 @@
       identification within third-party archives.
 
    Copyright 2023 FoundryLabs, Inc.
+   Copyright 2026 RetailDriver LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/Makefile b/Makefile
@@ -1,6 +1,8 @@
 CODEGEN_IMAGE ?= agentbox-sdk-codegen
 
-.PHONY: generate generate-in-container codegen-image sync-specs
+.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
 
 # Generate exclusively from the checked-in snapshots under spec/.
 generate: codegen-image
@@ -12,9 +14,49 @@ codegen-image:
 generate-in-container:
 	cd packages/js-sdk && pnpm generate
 	cd packages/python-sdk && make generate
+	$(MAKE) generate-go
 	python scripts/generate-reference.py
 	python scripts/test-reference-contract.py
 
+generate-go:
+	redocly bundle go-sdk --config redocly.yaml -o spec/openapi_generated.go-sdk.yml
+	python scripts/filter-public-openapi.py spec/openapi_generated.go-sdk.yml
+	oapi-codegen --config packages/go-sdk/internal/gen/api/oapi-codegen.yaml spec/openapi_generated.go-sdk.yml
+	redocly bundle envd --config redocly.yaml -o spec/openapi_generated.go-envd.yml
+	python packages/go-sdk/scripts/filter-go-envd.py spec/openapi_generated.go-envd.yml
+	oapi-codegen --config packages/go-sdk/internal/gen/envdapi/oapi-codegen.yaml spec/openapi_generated.go-envd.yml
+	cd spec/envd && buf generate --template buf-go.gen.yaml
+	gofmt -w packages/go-sdk/internal/gen
+
+check-agent-instructions:
+	cmp -s AGENTS.md CLAUDE.md
+
+go-format-check:
+	cd packages/go-sdk && ./scripts/check-go-format.sh
+
+go-vet:
+	cd packages/go-sdk && go vet ./...
+
+go-build:
+	cd packages/go-sdk && go build ./...
+
+go-test:
+	cd packages/go-sdk && go test ./...
+
+go-race:
+	cd packages/go-sdk && go test -race ./...
+
+go-coverage:
+	cd packages/go-sdk && ./scripts/check-go-coverage.sh
+
+go-integration:
+	cd packages/go-sdk && go test -tags=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
+
 # Maintainer-only update from a local mono checkout.
 sync-specs:
 	@test -n "$(MONO_DIR)" || (echo "Usage: make sync-specs MONO_DIR=/path/to/mono" >&2; exit 2)

diff --git a/README.md b/README.md
@@ -6,15 +6,17 @@
 
 # AgentBox SDK
 
-Official JavaScript, Python, and CLI clients for running isolated AgentBox sandboxes and code interpreters.
-
-| Package                     | Install                                  | Import                       |
-| --------------------------- | ---------------------------------------- | ---------------------------- |
-| JavaScript SDK              | `npm install @abox-dev/sdk`              | `@abox-dev/sdk`              |
-| Python SDK                  | `pip install abox-sdk`                   | `agentbox`                   |
-| JavaScript Code Interpreter | `npm install @abox-dev/code-interpreter` | `@abox-dev/code-interpreter` |
-| Python Code Interpreter     | `pip install abox-code-interpreter`      | `agentbox_code_interpreter`  |
-| CLI                         | `npm install --global @abox-dev/cli`     | `agentbox`                   |
+Official Go, JavaScript, Python, and CLI clients for running isolated AgentBox sandboxes and code interpreters.
+
+| Package                     | Install                                                          | Import                                    |
+| --------------------------- |------------------------------------------------------------------|-------------------------------------------|
+| JavaScript SDK              | `npm install @abox-dev/sdk`                                      | `@abox-dev/sdk`                           |
+| Python SDK                  | `pip install abox-sdk`                                           | `agentbox`                                |
+| Go SDK                      | `go get github.com/abox-dev/sdk/packages/go-sdk`                 | `github.com/abox-dev/sdk/packages/go-sdk` |
+| JavaScript Code Interpreter | `npm install @abox-dev/code-interpreter`                         | `@abox-dev/code-interpreter`              |
+| Python Code Interpreter     | `pip install abox-code-interpreter`                              | `agentbox_code_interpreter`               |
+| Go Code Interpreter         | `go get github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter` | `github.com/abox-dev/sdk/packages/go-sdk/codeinterpreter` |
+| CLI                         | `npm install --global @abox-dev/cli`                             | `agentbox`                                |
 
 ## Quick start
 
@@ -48,9 +50,29 @@ with Sandbox.create() as sandbox:
     print(result.stdout)
 ```
 
+Go:
+
+```go
+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())
+
+result, err := sandbox.Commands.Run(context.Background(), "echo", &agentbox.CommandOptions{Args: []string{"Hello from AgentBox"}})
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Print(string(result.Stdout))
+```
+
 ## Configuration
 
-The SDKs use `AGENTBOX_API_KEY` and optionally `AGENTBOX_PROJECT_ID`, `AGENTBOX_DOMAIN`, `AGENTBOX_API_URL`, and `AGENTBOX_SANDBOX_URL`. The production defaults are `agentbox-runtime.ru`, `api.agentbox-runtime.ru`, and `sandbox.agentbox-runtime.ru`.
+The SDKs use `AGENTBOX_API_KEY` and optionally `AGENTBOX_PROJECT_ID`, `AGENTBOX_DOMAIN`, `AGENTBOX_API_URL`, and `AGENTBOX_SANDBOX_URL`. The production defaults are `agentbox-runtime.ru`, `api.agentbox-runtime.ru`, and `sandbox.agentbox-runtime.ru`. Go requires Go 1.24 or newer.
 
 The CLI stores local configuration in `~/.agentbox/config.json`; environment variables take precedence. See [CLI configuration](https://docs.agentbox.ru/en/cli/configuration/).
 

diff --git a/RELEASING.md b/RELEASING.md
@@ -5,10 +5,12 @@ releasing the AgentBox SDK packages. The SDK repository owns package-level and
 end-to-end SDK tests. The mono repository owns backend HTTP/Connect regression
 tests and does not duplicate SDK test implementations.
 
-All five public packages use one version:
+All six public packages use one version:
 
 - npm: `@abox-dev/sdk`, `@abox-dev/code-interpreter`, `@abox-dev/cli`;
 - PyPI: `abox-sdk`, `abox-code-interpreter`.
+- Go: `github.com/abox-dev/sdk/packages/go-sdk` (including
+  `codeinterpreter`).
 
 ## 1. Prepare the change
 
@@ -38,9 +40,9 @@ uv lock --project packages/code-interpreter-python
 node scripts/check-release-versions.mjs vX.Y.Z
 ```
 
-`release:version` updates the five workspace manifests and both Python
-`pyproject.toml` files. Regenerate both Python lock files rather than editing
-them by hand. Do not release the JavaScript and Python packages at different
+`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.
 
 ## 3. Verify source and release artifacts
@@ -55,6 +57,7 @@ pnpm format:check
 pnpm lint
 pnpm typecheck
 pnpm test
+make go-check
 make generate
 git diff --exit-code
 ./scripts/build-release.sh
@@ -77,9 +80,9 @@ published:
 ./scripts/test-release-runtime.sh
 ```
 
-The suite covers JavaScript, Python sync/async, Code Interpreter, CLI,
-private traffic, and a temporary template build. It owns and removes its test
-resources. A release must not be tagged if this suite fails.
+The suite covers JavaScript, Python sync/async, Go core and Code Interpreter,
+CLI, private traffic, and a temporary template build. It owns and removes its
+test resources. A release must not be tagged if this suite fails.
 
 ## 5. Merge and tag
 
@@ -91,17 +94,22 @@ commit:
 git switch main
 git pull --ff-only origin main
 node scripts/check-release-versions.mjs vX.Y.Z
+git tag -a packages/go-sdk/vX.Y.Z -m "AgentBox Go SDK vX.Y.Z"
 git tag -a vX.Y.Z -m "AgentBox SDK vX.Y.Z"
-git push origin vX.Y.Z
+git push --atomic origin packages/go-sdk/vX.Y.Z vX.Y.Z
 ```
 
-Do not move or reuse a published tag. If a release needs a correction, publish
-a new patch version.
+Do not move or reuse either published tag. If a release needs a correction,
+publish a new patch version.
 
 The tag workflow builds the artifacts once, verifies them, publishes npm via
 Trusted Publishing, publishes both PyPI projects via their GitHub environments,
-and creates a GitHub Release with checksums. An existing registry file is
-accepted only when its digest matches the newly built artifact.
+creates a GitHub Release with checksums, and asks the public Go proxy to index
+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.
 
 ## 6. Verify the published packages
 
@@ -112,6 +120,14 @@ packages into clean environments and repeat the KVM suite:
 ./scripts/test-published-runtime.sh X.Y.Z
 ```
 
+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`.
+
+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
+cross-builds run on 1.24.x and 1.27.x. Follow the Go-version maintenance
+checklist in `AGENTS.md`/`CLAUDE.md` whenever a new patch or minor is released.
+
 Verify the GitHub Release assets with its `SHA256SUMS`. Document public API
 changes in the AgentBox documentation repository. No SDK-version update is
 required in mono: its direct HTTP/Connect tests intentionally remain independent