@pai/sandbox-gke

Package: @pai/sandbox-gke

@pai/sandbox-gke configures a standalone @pai/gke-sandbox-sdk client behind PAI's provider-neutral SandboxProvider. The Kubernetes lifecycle, command, and file implementation lives in the SDK rather than being duplicated inside the adapter.

import { createAgentRuntime } from "@pai/core";
import { sandboxCapability } from "@pai/sandbox";
import { createGkeSandboxProvider } from "@pai/sandbox-gke";

const runtime = createAgentRuntime({
  agent,
  scopeKey: (identity) => identity.workspaceId,
  capabilities: {
    sandbox: sandboxCapability({
      provider: createGkeSandboxProvider({
        namespace: "pai-sandboxes",
        templates: [
          {
            name: "pai-node-runtime",
            network: { access: "none" },
            containerName: "runtime",
            defaultCwd: "/workspace",
          },
        ],
      }),
      createOptions: { network: { access: "none" } },
    }),
  },
});

The adapter maps command, file, keepalive, and kill operations and normalizes SDK errors into the public @pai/sandbox error types. bindingKey passes straight through, so the session manager's one-sandbox-per-conversation guarantee holds across replicas on GKE. create({ template }) selects one of the client's declared templates; the SDK refuses any other. Use adaptGkeSandboxClient(client) only when an application already owns an SDK client, such as a lazy client initialized after startup.

Use @pai/gke-sandbox-infra to deploy the GKE substrate and read the SDK page for network, credentials, persistence, and security details.

Conformance

Offline tests cover the adapter mapping. The full @pai/sandbox/test conformance suite, including the binding-key cases, runs against a real cluster only when PAI_GKE_SANDBOX_TEMPLATE is configured and the selected template has the closed network policy required by the provider contract's default create path. The same gate enables a race test that forks two Node processes creating with one key and asserts they converge on one sandbox.