feat(sdk): add Go SDK for OpenShell by rhuss · Pull Request #5 · rhuss/OpenShell

rhuss · 2026-07-11T10:26:07Z

Summary

Add a Go SDK that provides typed clients for the OpenShell gateway and edge APIs. The SDK wraps the gRPC transport layer and exposes idiomatic Go types with functional option configuration.

This PR addresses #2044.

Features

Gateway and Edge API clients with full CRUD operations for sandboxes, providers, services, exec, files, SSH, TCP forwarding, and network policies
In-memory fakes for testing that mirror real client input validation
OIDC authentication with automatic token refresh and device-code flow
Proto generation automation via mise task with CI freshness check
Fern documentation covering getting started, architecture, error handling, and authentication

File Tree

sdk/go/                              # Go SDK (self-contained module)
├── go.mod                           # Module: github.com/NVIDIA/OpenShell/sdk/go
├── Makefile, mise.toml              # Build configuration
├── openshell/v1/                    # Public API
│   ├── gateway/                     # Gateway client (reads CLI config)
│   ├── edge/                        # Edge API client
│   ├── fake/                        # In-memory test fakes
│   ├── types/                       # Domain types and errors
│   ├── oidc/                        # OIDC authentication
│   └── internal/                    # Proto conversion, gRPC connection
└── proto/                           # Proto definitions + generated .pb.go

docs/sdks/go/                        # Fern MDX documentation
├── getting-started.mdx
├── architecture.mdx
├── error-handling.mdx
└── authentication.mdx

tasks/go.toml                        # Monorepo mise tasks (go:proto, go:lint, etc.)
.github/workflows/branch-checks.yml  # Go CI job added
docs/index.yml                       # SDKs navigation section added

Development Methodology

This SDK was developed using spec-driven development. Design specifications are available in a follow-up PR (#6) for transparency and review.

Testing

1035 unit tests pass across 11 packages
All tests use testify (assert/require)
Integration tests are gated behind //go:build integration
In-memory fakes mirror real client validation for test parity

Build & CI

The Go CI job mirrors the existing Rust and Python jobs:

cd sdk/go
mise install --locked
mise run lint          # golangci-lint
mise run build         # go build ./...
mise run test          # go test ./...
mise run proto:check   # Verify generated .pb.go freshness

Examples

The interactive TUI example (oshell) has been extracted to a separate repository: rhuss/openshell-examples. This keeps the upstream SDK library-only.

…VIDIA#2178) * feat(cli): add --secret-material-env to provider refresh configure * feat(cli): reject duplicate secret material keys Signed-off-by: Hung Le <[email protected]> --------- Signed-off-by: Hung Le <[email protected]>

…IA#2190) * docs(telemetry): add community telemetry reports page Add telemetry/README.md to publish aggregate usage trends every two weeks, and link to it from the Telemetry section of the main README. First report covers the July 8, 2026 window. Signed-off-by: Kirit Thadaka <[email protected]> * docs(telemetry): note telemetry start date (June 1, 2026) Clarify that all-time figures are cumulative from NVIDIA#1433, so readers know when the all-time counts begin. Signed-off-by: Kirit Thadaka <[email protected]> --------- Signed-off-by: Kirit Thadaka <[email protected]>

Signed-off-by: Adam Miller <[email protected]>

…VIDIA#2197) Add regression coverage for parser differentials in the egress proxy's CONNECT hostname handling and OPA wildcard policy matching. Signed-off-by: Shane Utt <[email protected]>

…2210) * fix(tui): route warning logs to status bar instead of stderr tracing::warn/info/debug calls in the TUI crate write to stderr via the global tracing subscriber. In ratatui's alternate-screen/raw-mode, stderr writes corrupt the terminal layout. Error-state sandboxes amplify this as background gRPC polls fail every 2s tick. Replace all 25 tracing calls with app.status_text assignments for direct-access sites, and Vec<String> accumulation for the spawned start_port_forwards task. Add ForwardWarnings event variant to decouple forward warning delivery from the sandbox name in CreateResult, preventing downstream gRPC lookup failures. Closes NVIDIA#2120 Signed-off-by: Ian Miller <[email protected]> * feat(tui): add ForwardWarnings event variant New event type for non-fatal port-forward warnings during sandbox creation. Keeps warning delivery separate from the sandbox name in CreateResult to avoid corrupting downstream gRPC lookups. Signed-off-by: Ian Miller <[email protected]> * chore(tui): remove tracing dependency Compile-time guard against reintroducing stderr-writing tracing calls in the TUI crate. 14 other crates retain the dependency. Signed-off-by: Ian Miller <[email protected]> --------- Signed-off-by: Ian Miller <[email protected]>

Signed-off-by: Kirit93 <[email protected]>

Bumps [astral-sh/setup-uv](https://github.com/astral-sh/setup-uv) from 8.3.1 to 8.3.2. - [Release notes](https://github.com/astral-sh/setup-uv/releases) - [Commits](astral-sh/setup-uv@f98e069...11f9893) --- updated-dependencies: - dependency-name: astral-sh/setup-uv dependency-version: 8.3.2 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

…or OpenShift overrides (NVIDIA#2125) Signed-off-by: ChristianZaccaria <[email protected]>

Signed-off-by: Evan Lezar <[email protected]>

NVIDIA#2070) * fix(core): pin supervisor image tag to gateway version for all drivers The Podman and Kubernetes drivers defaulted the supervisor image to `:latest` via DEFAULT_SUPERVISOR_IMAGE, while the Docker driver already resolved a version-pinned tag. Extract the tag resolution logic into openshell-core so all three drivers use the same OPENSHELL_IMAGE_TAG > IMAGE_TAG > CARGO_PKG_VERSION priority chain. Closes NVIDIA#2068 Signed-off-by: Florent Benoit <[email protected]> * refactor(core): simplify supervisor image tag resolver to slice-based API Remove the Docker driver's wrapper functions and call openshell_core::config::default_supervisor_image() directly. Simplify resolve_supervisor_image_tag to accept &[&str] instead of three separate parameters. Signed-off-by: Florent Benoit <[email protected]> Signed-off-by: Florent Benoit <[email protected]> --------- Signed-off-by: Florent Benoit <[email protected]> Signed-off-by: Florent Benoit <[email protected]>

Signed-off-by: Taylor Mutch <[email protected]>

* feat(kubernetes): add sidecar supervisor topology Add the Kubernetes sidecar supervisor topology, its Helm/Skaffold configuration, topology documentation, and sidecar e2e matrix coverage. Skip root-only sandbox identity rewriting when process enforcement is network-only so the low-permission sidecar process container can start successfully. Signed-off-by: Taylor Mutch <[email protected]> * fix(supervisor): avoid similar process id names Signed-off-by: Taylor Mutch <[email protected]> * fix(supervisor): avoid similar process id names Signed-off-by: Taylor Mutch <[email protected]> * fix(sandbox): avoid similar proxy id names Signed-off-by: Taylor Mutch <[email protected]> * docs(kubernetes): clarify sidecar topology limits Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): keep sidecar process leaf capless Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): refresh sidecar provider env snapshots Signed-off-by: Taylor Mutch <[email protected]> * test(supervisor): align hot-swap identity regression Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): stage sidecar mtls files before proxy chown Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): simplify sidecar supervisor topology Signed-off-by: Taylor Mutch <[email protected]> * chore(helm): reuse sidecar skaffold values Signed-off-by: Taylor Mutch <[email protected]> * fix(supervisor): avoid similar iptables helper names Signed-off-by: Taylor Mutch <[email protected]> * fix(e2e): harden kube gateway wrapper setup Signed-off-by: Taylor Mutch <[email protected]> * fix(supervisor): avoid nft batch rollback on OCP Run nftables setup as individual commands so optional conntrack and log expressions can fail without rolling back required table, chain, and reject rules. Signed-off-by: Seth Jennings <[email protected]> Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): preserve process identity in sidecar topology Render sidecar pods with a shared process namespace, keep binary-aware network policy enabled, and move Kubernetes sidecar settings under the nested sidecar config table. Also apply unprivileged Landlock/seccomp setup in NetworkOnly supervisor mode so sidecar topology keeps sandbox child hardening without privileged process setup. Signed-off-by: Taylor Mutch <[email protected]> * refactor(kubernetes): replace sidecar snapshots with control socket Coordinate sidecar policy and provider bootstrap over a local Unix socket so the process leaf no longer reads policy/provider snapshot files. Report entrypoint startup through the control channel and keep gateway credentials confined to the network sidecar. Signed-off-by: Taylor Mutch <[email protected]> * feat(kubernetes): support relaxed sidecar network identity Signed-off-by: Taylor Mutch <[email protected]> * fix(sandbox): satisfy sidecar clippy lint Signed-off-by: Taylor Mutch <[email protected]> * refactor(kubernetes): standardize topology naming Signed-off-by: Taylor Mutch <[email protected]> * fix(sandbox): satisfy linux clippy timeout import Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): support kata sidecar on ipv4 pods Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): satisfy linux clippy for sidecar fallback Signed-off-by: Taylor Mutch <[email protected]> * chore(kubernetes): remove stale supervisor topology references Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): enable sidecar binary policy inspection Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): harden sidecar control boundary Signed-off-by: Taylor Mutch <[email protected]> * fix(kubernetes): couple sidecar supervisor lifecycles Signed-off-by: Taylor Mutch <[email protected]> --------- Signed-off-by: Taylor Mutch <[email protected]> Signed-off-by: Seth Jennings <[email protected]> Co-authored-by: Seth Jennings <[email protected]>

* feat(kubernetes): support PVC subPath driver config Signed-off-by: mjamiv <[email protected]> * test(kubernetes): cover writable PVC driver config Signed-off-by: mjamiv <[email protected]> * fix(kubernetes): address PVC subPath review feedback Signed-off-by: mjamiv <[email protected]> * fix(kubernetes): address PVC config review follow-up Signed-off-by: mjamiv <[email protected]> * fix(kubernetes): address PVC review follow-ups --------- Signed-off-by: mjamiv <[email protected]>

Parent brainstorm (01) defines the layered measurement approach for evaluating Agent Sandbox warm pooling on OpenShift. Child documents cover cluster setup (02), measurements (03), and results synthesis (04). Assisted-By: 🤖 Claude Code

Assisted-By: 🤖 Claude Code Signed-off-by: Roland Huß <[email protected]>

coderabbitai · 2026-07-11T10:26:20Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0a367910-adb6-484f-8209-92aa1747930e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch go-sdk

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

Add a Go SDK that provides typed clients for the OpenShell gateway and edge APIs. The SDK wraps the gRPC transport layer and exposes idiomatic Go types with functional option configuration. Includes: - Gateway and Edge API clients with full CRUD operations - In-memory fakes for testing (matching real client validation) - OIDC authentication with automatic token refresh - Proto generation automation (mise task + CI check) - Fern documentation (getting-started, architecture, auth, errors) Resolves: NVIDIA#2044 Assisted-By: 🤖 Claude Code Signed-off-by: Roland Huß <[email protected]>

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

rhuss · 2026-07-11T10:36:14Z

Closing to recreate with clean diff after rebasing on updated main.

hunglp6d and others added 16 commits July 9, 2026 08:58

change packit target to new correct copr project (NVIDIA#2185)

4970108

Signed-off-by: Adam Miller <[email protected]>

test(supervisor-network): add proxy hostname parser regression tests (N…

420a855

…VIDIA#2197) Add regression coverage for parser differentials in the egress proxy's CONNECT hostname handling and OPA wildcard policy matching. Signed-off-by: Shane Utt <[email protected]>

fix(mcp): include tool names in policy logs (NVIDIA#2189)

ccdac9c

Signed-off-by: Kirit93 <[email protected]>

docs(openshift): simplify install steps and add Helm README entries f…

8c0ecac

…or OpenShift overrides (NVIDIA#2125) Signed-off-by: ChristianZaccaria <[email protected]>

docs(issues): require release and duplicate checks (NVIDIA#2214)

233d207

Signed-off-by: Evan Lezar <[email protected]>

fix(helm): propagate supervisor image overrides (NVIDIA#2216)

bebf440

Signed-off-by: Taylor Mutch <[email protected]>

docs: add brainstorm for K8s watch stream crash fix (NVIDIA#2211)

6e11634

Assisted-By: 🤖 Claude Code Signed-off-by: Roland Huß <[email protected]>

docs: update brainstorm overview

99801e3

Assisted-By: 🤖 Claude Code Signed-off-by: Roland Huß <[email protected]>

rhuss requested a review from Copilot July 11, 2026 10:26

Copilot AI reviewed Jul 11, 2026

rhuss force-pushed the go-sdk branch from a811220 to b3bcf4b Compare July 11, 2026 10:28

rhuss marked this pull request as ready for review July 11, 2026 10:28

rhuss marked this pull request as draft July 11, 2026 10:29

rhuss force-pushed the go-sdk branch from b3bcf4b to 61496f8 Compare July 11, 2026 10:32

rhuss requested a review from Copilot July 11, 2026 10:33

rhuss mentioned this pull request Jul 11, 2026

docs(sdk): add Go SDK design specifications #6

Closed

Copilot AI reviewed Jul 11, 2026

rhuss closed this Jul 11, 2026

rhuss deleted the go-sdk branch July 11, 2026 10:41

Navigation Menu

Repository navigation

feat(sdk): add Go SDK for OpenShell - #5

feat(sdk): add Go SDK for OpenShell#5
rhuss wants to merge 17 commits into
mainfrom
go-sdk

rhuss commented Jul 11, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading

Review skipped

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

rhuss commented Jul 11, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

Conversation

rhuss commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

File Tree

Development Methodology

Testing

Build & CI

Examples

Uh oh!

coderabbitai Bot commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

rhuss commented Jul 11, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

rhuss commented Jul 11, 2026 •

edited

Loading

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading