ai-sdk-sandbox-gce weekly downloads statistics

ai-sdk-sandbox-gce

<p align="center"> <a href="https://www.npmjs.com/package/ai-sdk-sandbox-gce"><img alt="npm" src="https://img.shields.io/npm/v/ai-sdk-sandbox-gce" /></a> <a href="https://github.com/fpasquet/ai-sdk-harness/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/fpasquet/ai-sdk-harness/actions/workflows/ci.yml/badge.svg" /></a> <img alt="Node &gt;= 24" src="https://img.shields.io/badge/node-%3E%3D24-3c873a" /> <img alt="TypeScript strict" src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" /> <a href="https://github.com/fpasquet/ai-sdk-harness/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg" /></a> </p>

Run AI SDK harness agents (Claude Code, Codex…) in Compute Engine virtual machines on Google Cloud: one machine per sandbox, Docker and Docker Compose included, stopped between turns.

The package gives HarnessAgent.createSession({ sandboxSession }) what it expects, a HarnessV1NetworkSandboxSession, the same way ai-sdk-sandbox-cloud-run does for Cloud Run sandboxes, and speaks the same protocol:

• A virtual machine per sandbox: the isolation boundary is a hypervisor, and the firewall is applied outside the guest, by the VPC. Docker, docker compose and PostgreSQL run in it as on any machine.
• Nothing running between turns: stop() stops the machine and keeps its disk; a resume starts it again on the same disk. A stopped sandbox costs its disk only.
• No network of its own: the machine has no external address and the firewall only lets it reach an egress proxy, which only lets out the hosts you allow, over HTTPS.
• Credentials stay outside: the harness hands the sandbox a placeholder, and the proxy swaps the real value in on the way to the model API. A real credential never enters the machine, nor any log. The machine has no service account either.
• The harness is installed once: pass agent.getSandboxTemplate() and the first sandbox's disk is saved as an image; every later sandbox boots from it.

How it works

The package comes in four parts: the client your application calls, and three programs you deploy, all in the same package (ai-sdk-sandbox-gce <serve|proxy|agent>):

flowchart TB
  subgraph app["Your application"]
    agent["HarnessAgent"] --> client["createGceNetworkSandboxSession()"]
  end
  subgraph run["Cloud Run, VPC egress into the sandboxes' network"]
    service["ai-sdk-sandbox-gce serve"]
  end
  subgraph vpc["VPC of the sandboxes, no external address"]
    subgraph vm["One machine per sandbox, no service account"]
      vmagent["ai-sdk-sandbox-gce agent"] --> bridge["Harness bridge: Claude Code, Codex"]
      docker["Docker, docker compose"]
    end
    proxy["Egress proxy machine: ai-sdk-sandbox-gce proxy"]
  end
  compute[("Compute Engine API: machines, disks, images")]
  api["Model APIs, allowed hosts"]

  client -- "HTTPS, IAM identity token" --> service
  agent -. "WebSocket, through the service" .-> bridge
  service -- "create, stop, start, delete" --> compute
  service -- "commands, files, ports: port 8100" --> vmagent
  service -- "hosts, credentials: port 3129" --> proxy
  vm -- "the firewall's only way out: port 3128" --> proxy
  proxy -- "its own external address, HTTPS, real credentials put in" --> api

• The client (this package's API) creates, resumes, stops and deletes sandboxes, and runs commands, files and ports through the service. It is the client of ai-sdk-sandbox-cloud-run, under other names.
• The sandbox service (ai-sdk-sandbox-gce serve) runs in a Cloud Run service, with VPC egress into the sandboxes' network. It keeps nothing: what a machine is, Compute Engine says; what it may reach and its credentials, the proxy holds; its processes, its agent runs. Any instance serves any sandbox, and it scales to zero.
• The agent (ai-sdk-sandbox-gce agent) runs in every sandbox machine, started by systemd from the sandbox image. It runs the commands as the sandbox's user, and passes a tunnel on to a port of the machine. It only answers the service, with a token derived for its machine.
• The egress proxy (ai-sdk-sandbox-gce proxy) runs on a machine of its own, the only one with a way out, through an external address of its own. It knows each sandbox by its machine's internal address, and holds its allowed hosts and credentials in memory.

Requirements

• Node.js 24 or later: in your application, the service's image, the sandbox image and the proxy's machine.
• A Google Cloud project with Compute Engine, Cloud Run and Cloud DNS, and the gcloud CLI.
• @ai-sdk/harness and a harness adapter, such as @ai-sdk/harness-claude-code.

Deploying

The commands below set up everything once. Every name is yours to change.

PROJECT=my-project REGION=europe-west1 ZONE=europe-west1-b
gcloud config set project $PROJECT

1. The network

One VPC, three subnetworks: the sandboxes, the proxy, and the service's egress from Cloud Run.

gcloud compute networks create sandboxes --subnet-mode=custom
gcloud compute networks subnets create sandboxes --network=sandboxes --region=$REGION --range=10.8.0.0/20
gcloud compute networks subnets create proxy --network=sandboxes --region=$REGION --range=10.8.16.0/28
gcloud compute networks subnets create service --network=sandboxes --region=$REGION --range=10.8.17.0/26
gcloud compute addresses create sandbox-proxy --region=$REGION --subnet=proxy --addresses=10.8.16.2…