Documentation on go-runtime-sandbox

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

The fastest path to a working sandbox is the one-shot kind script. It builds the runtime image, brings up a kind cluster, installs the agent-sandbox controller and router, deploys the SandboxTemplate, and runs the demo end-to-end.

Prerequisites

Tool	Version
Docker	20.10+
Go	1.26+
`kubectl`	1.30+
`kind`	0.20+

Run it

From the repo root:

./scripts/run-test-kind.sh

Expected output (tail):

=== single-file smoke flow ===
-- go run main.go [exit=0] -- hello from the sandbox! sum(1..100)=5050, go=go1.26.3/linux/amd64
-- ./app (re-runs the binary built in the previous call) -- hello from the sandbox! ...

=== multi-file module flow ===
-- ./app [exit=0] -- hello, Alice — from the multi-file sandbox sample
 hello, Bob — ...
 hello, Carol — ...
-- go test ./... [exit=0] -- ok example.com/multifile/greet 0.004s

==> PoC complete

That confirms three things end-to-end: the runtime image builds and runs, the agent-sandbox client can ship files into it via the router, and arbitrary Go programs (including multi-file modules) build and execute inside.

Install

Mon, 01 Jan 0001 00:00:00 +0000

This walks you through running the cmd/demo program end-to-end against a Kubernetes cluster. Two paths are supported:

A. Local kind cluster — recommended for the first run. One script.
B. GKE cluster — for running the demo against real cloud infrastructure (and the eventual gVisor-isolated runtime path).

Both paths exercise the same demo: ship a Go source file into a sandbox, compile it, run it, then do the same for a multi-file module.

MCP server

Mon, 01 Jan 0001 00:00:00 +0000

cmd/mcp-server is a Model Context Protocol server that exposes one tool — run_go_code — backed by pkg/goruntime. Any MCP client (Claude Code, Claude Desktop, Cursor, etc.) can use it to build and execute Go programs in an isolated Kubernetes sandbox.

This guide covers: registering the server in Claude Code, what the tool does, a smoke-test path that doesn’t require an LLM, and prompts to try once it’s wired up.

Prerequisites

You need everything from howto.md — a Kubernetes cluster (kind or GKE) with the agent-sandbox controller installed, the sandbox-router deployed in your target namespace, and the go-runtime-template SandboxTemplate applied. Easiest path: run ./scripts/run-test-kind.sh once; the script’s cleanup trap removes the per-test resources at the end, so before using the MCP server you’ll want to re-apply just the router and template:

How it works

Mon, 01 Jan 0001 00:00:00 +0000

Derived from spec.md. The spec answers what; this document answers how.

1. Overview

Two artifacts, one HTTP contract, one end-to-end test:

┌──────────────────────────────┐ port-forward ┌────────────────────────────┐
│ host │ ──────────────▶│ sandbox pod │
│ cmd/demo (Go) │ HTTP :8888 │ server (Go, net/http) │
│ └─ sigs.k8s.io/agent-sandbox│ │ └─ shells out: go, tar │
│ /clients/go/sandbox │ │ workdir: /app │
└──────────────────────────────┘ └────────────────────────────┘

The pod’s container image (go-runtime-sandbox) bundles the Go toolchain plus our server binary. The server speaks the same HTTP contract as upstream’s Python runtime so the agent-sandbox Go client’s Write / Run / Read / List / Exists methods work without modification.