khirotaka avatar

k8s-agent-sandbox-docs

Documentation for the kubernetes-sigs/agent-sandbox project

version
0.1.0

Install

/plugin install k8s-agent-sandbox-docs@khirotaka-cc-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add khirotaka/cc-plugins.

Contents

Discovered from source

Skills 1

Kubernetes Agent Sandbox

AIエージェントのための、Kubernetes上の分離された実行環境を管理するCRDとコントローラー。

リポジトリ: https://github.com/kubernetes-sigs/agent-sandbox

主な機能

  • Sandbox (Core): ステートフルPodのライフサイクル管理
  • 拡張機能: SandboxTemplate (テンプレート), SandboxClaim (オンデマンド作成), SandboxWarmPool (プリウォーム)
  • Python SDK: Kubernetes上のSandboxと対話するクライアント
  • NetworkPolicy統合: ネットワーク分離によるセキュア実行環境

アーキテクチャ概要

Core (agents.x-k8s.io)
  └─ Sandbox → Pod, Service, PVC管理

Extensions (extensions.agents.x-k8s.io)
  ├─ SandboxTemplate → テンプレート + NetworkPolicy
  ├─ SandboxClaim → テンプレートから作成
  └─ SandboxWarmPool → プール管理

Client: Python SDK → Sandbox Router → Sandbox Pod

詳細: ./references/README.md


CRD Reference Map

Sandbox (agents.x-k8s.io/v1alpha1)

目的: 単一ステートフルPod + Service + PVC管理

主要Specフィールド:

  • podTemplate.spec (必須) - Pod仕様
  • volumeClaimTemplates - PVCテンプレート
  • shutdownTime - 自動削除時刻 (RFC 3339)
  • replicas - 0または1

Statusフィールド: serviceFQDN, service, conditions, replicas

検索:

grep -A 15 "## Spec フィールド" ./references/CRDs/Sandbox.md
grep -A 15 "## 最小構成例" ./references/CRDs/Sandbox.md

詳細: ./references/CRDs/Sandbox.md


SandboxTemplate (extensions.agents.x-k8s.io/v1alpha1)

目的: 再利用可能テンプレート + NetworkPolicy

主要Specフィールド:

  • podTemplate (必須) - Pod定義
  • networkPolicy.ingress - Ingressルール
  • networkPolicy.egress - Egressルール

セキュア構成例:

spec:
  podTemplate:
    spec:
      runtimeClassName: gvisor
  networkPolicy:
    egress:
      - ports:
        - protocol: UDP
          port: 53  # DNS のみ

検索:

grep -A 40 "## セキュアな設定例" ./references/CRDs/SandboxTemplate.md

詳細: ./references/CRDs/SandboxTemplate.md


SandboxClaim (extensions.agents.x-k8s.io/v1alpha1)

目的: SandboxTemplateからSandbox作成要求

主要Specフィールド:

  • sandboxTemplateRef.name (必須) - SandboxTemplate名
  • sandboxTemplateRef.namespace - namespace

Statusフィールド: sandboxName, conditions

Python SDK統合: SandboxClientが内部的に使用

検索:

grep -A 20 "## 動作フロー" ./references/CRDs/SandboxClaim.md

詳細: ./references/CRDs/SandboxClaim.md


SandboxWarmPool (extensions.agents.x-k8s.io/v1alpha1)

目的: Sandboxプール (コールドスタート削減)

主要Specフィールド:

  • replicas (必須) - プール内Sandbox数
  • sandboxTemplateRef.name (必須) - SandboxTemplate名

Statusフィールド: replicas, readyReplicas, conditions

検索:

grep -A 20 "## HPA" ./references/CRDs/SandboxWarmPool.md

詳細: ./references/CRDs/SandboxWarmPool.md


Python SDK Reference

インストール

pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@main#subdirectory=clients/python/agentic-sandbox-client"

SandboxClient

コンストラクタ主要パラメータ:

パラメータ型デフォルト説明
template_namestr(必須)SandboxTemplate名
namespacestr"default"namespace
gateway_namestr | NoneNoneGateway名 (Production)
api_urlstr | NoneNone直接URL (Direct)
server_portint8888Sandboxサーバーポート

コアメソッド:

メソッド戻り値説明
run(command, timeout=60)ExecutionResultコマンド実行
write(path, content, ...)Noneファイル書き込み
read(path, timeout=60)bytesファイル読み込み
is_ready()bool接続確認

接続モード:

  • Tunnel (デフォルト): kubectl port-forward - ローカル開発用
  • Gateway: gateway_name指定 - 本番環境用
  • Direct: api_url指定 - クラスタ内部用

使用例:

from agentic_sandbox import SandboxClient

with SandboxClient(template_name="python-sandbox-template") as sandbox:
    result = sandbox.run("python -c 'print(42)'")
    print(result.stdout)  # "42\n"

    sandbox.write("/tmp/test.py", "print('Hello')")
    result = sandbox.run("python /tmp/test.py")

検索:

grep -A 15 "^```python" ./references/python-sdk/SandboxClient.md
grep -A 30 "## 内部動作" ./references/python-sdk/SandboxClient.md

詳細: ./references/python-sdk/SandboxClient.md


SandboxRouter

目的: X-Sandbox-IDヘッダーベース動的ルーティングプロキシ

詳細: ./references/python-sdk/SandboxRouter.md

ComputerUseExtension

目的: Gemini Computer Use統合 (agent(query: str)メソッド)

詳細: ./references/python-sdk/ComputerUseExtension.md


Implementation Examples Index

場所: ./references/examples/

例難易度ユースケースファイル
python-runtime-sandbox⭐基本コマンド実行API./references/examples/python-runtime-sandbox.md
aio-sandbox⭐All-in-One (VNC, VSCode, Jupyter)./references/examples/aio-sandbox.md
gemini-cu-sandbox⭐⭐Gemini Computer Use (ブラウザ)./references/examples/gemini-cu-sandbox.md
vscode-sandbox⭐⭐VSCode + gVisor/Kata分離./references/examples/vscode-sandbox.md

python-runtime-sandbox (⭐)

最小FastAPI実装。/execute, /upload, /download エンドポイント。カスタムランタイムの出発点。

aio-sandbox (⭐)

VNC, VSCode Server, Jupyter統合環境。agent-infra/sandbox ベース。

gemini-cu-sandbox (⭐⭐)

Gemini Computer Use。/agent エンドポイントで自然言語タスク実行。要: Gemini API keySecret。

vscode-sandbox (⭐⭐)

VSCode Server + gVisor/Kata。Sandbox Router経由アクセス。

検索:

grep -A 10 "## API" ./references/examples/<example-name>.md
grep -A 20 "## マニフェスト" ./references/examples/<example-name>.md

Common Query Patterns

"セキュアなSandboxを作成するには?"

→ SandboxTemplate + gVisor + NetworkPolicy (DNS egress のみ)

grep -A 40 "## セキュアな設定例" ./references/CRDs/SandboxTemplate.md

"[CRD名] のフィールドは?"

→ CRD Reference Map参照、または:

grep -A 20 "## Spec フィールド" ./references/CRDs/<CRD名>.md

"Sandboxに接続するには?"

→ SandboxClient(template_name="...") 使用 (上記Python SDK参照)

"特定ランタイム実装は?"

→ Implementation Examples Index参照

ls ./references/examples/*.md

"NetworkPolicy設定は?"

→ ingress/egress定義 (デフォルト全拒否)

grep -A 10 "### NetworkPolicySpec" ./references/CRDs/SandboxTemplate.md

How to Use This Skill

ファイル構成

skills/references/
├── README.md              # プロジェクト概要 (94行)
├── CRDs/
│   ├── README.md            # CRD一覧 (63行)
│   ├── Sandbox.md           # (101行)
│   ├── SandboxTemplate.md   # (122行)
│   ├── SandboxClaim.md      # (75行)
│   └── SandboxWarmPool.md   # (97行)
├── python-sdk/
│   ├── README.md            # (23行)
│   ├── SandboxClient.md     # (161行)
│   ├── SandboxRouter.md     # (57行)
│   └── ComputerUseExtension.md # (51行)
└── examples/
    ├── README.md            # (50行)
    ├── python-runtime-sandbox.md # (76行)
    ├── aio-sandbox.md       # (87行)
    ├── gemini-cu-sandbox.md # (102行)
    └── vscode-sandbox.md    # (82行)

合計: 16ファイル、~1,147行

検索戦略

API/フィールドクエリ

  1. SKILL.mdのCRD Reference Map確認
  2. grepで詳細抽出
  3. 必要なら完全ファイル読み込み

実装ガイダンス

  1. Common Query Patterns確認
  2. Implementation Examples Index参照
  3. 該当例ファイル読み込み

SDK使用方法

  1. Python SDK Reference確認
  2. 基本用法はSKILL.mdで完結
  3. 高度な用法はgrepまたはファイル読み込み

優先度

Tier 1 (最頻):

  • ./references/python-sdk/SandboxClient.md
  • ./references/CRDs/Sandbox.md
  • ./references/CRDs/SandboxTemplate.md

Tier 2 (コンテキスト):

  • ./references/README.md
  • ./references/examples/python-runtime-sandbox.md

Tier 3 (オンデマンド): その他

Web フォールバック

ローカル不十分時:

CodeWiki: https://codewiki.google/github.com/kubernetes-sigs/agent-sandbox

使用時:

  • references/に無い実装詳細
  • 最新変更/アップデート
  • 高度なトラブルシューティング
  • Controller実装詳細

便利なgrep パターン

# 全CRDのSpecフィールド
grep -A 15 "## Spec フィールド" ./references/CRDs/*.md

# YAML例検索
grep -n "^```yaml" ./references/CRDs/<file>.md

# NetworkPolicy
grep -A 30 "networkPolicy" ./references/CRDs/SandboxTemplate.md

# Python例
grep -A 15 "^```python" ./references/python-sdk/*.md

# 全体検索
grep -r "keyword" ./references/

言語注記

  • ドキュメント: 日本語
  • grepキーワード: 日本語 (例: "フィールド", "設定例")
  • セクションヘッダー: ## 統一
  • コード例: 言語非依存

バージョン

  • CRD: v1alpha1
  • 更新: 2025-12-21
  • ソース: kubernetes-sigs/agent-sandbox (main)

Agents 15

CRD リファレンス

Agent Sandbox が提供する Custom Resource Definition の一覧。

API Groups

Group説明
agents.x-k8s.ioCore API (Sandbox)
extensions.agents.x-k8s.ioExtensions API (Template, Claim, WarmPool)

CRD 一覧

Core

Kind説明ドキュメント
Sandbox単一のステートフル Pod を管理詳細

Extensions

Kind説明ドキュメント
SandboxTemplate再利用可能なテンプレート + NetworkPolicy詳細
SandboxClaimテンプレートから Sandbox を要求詳細
SandboxWarmPoolSandbox のプリウォームプール詳細

リソース関係

flowchart TB
    subgraph Core["agents.x-k8s.io"]
        Sandbox[Sandbox]
    end
    
    subgraph Extensions["extensions.agents.x-k8s.io"]
        Template[SandboxTemplate]
        Claim[SandboxClaim]
        WarmPool[SandboxWarmPool]
    end
    
    subgraph "Kubernetes Resources"
        Pod
        Service
        PVC
        NetworkPolicy
    end
    
    Template -->|参照| Claim
    Template -->|参照| WarmPool
    Claim -->|作成| Sandbox
    WarmPool -->|作成| Sandbox
    
    Sandbox -->|管理| Pod
    Sandbox -->|管理| Service
    Sandbox -->|管理| PVC
    Template -->|作成| NetworkPolicy

Version 情報

現在のすべての CRD は v1alpha1 バージョン。

Sandbox CRD

コア CRD。単一の Pod とそれに付随する Service、PVC を管理。

API 情報

項目値
API Groupagents.x-k8s.io
Versionv1alpha1
KindSandbox
ScopeNamespaced
Short Namesandbox

Spec フィールド

フィールド型必須説明
podTemplatePodTemplate✓Pod の定義
podTemplate.speccorev1.PodSpec✓Pod の spec
podTemplate.metadataPodMetadata-labels, annotations
volumeClaimTemplates[]PersistentVolumeClaimTemplate-PVC テンプレート
shutdownTimemetav1.Time-自動削除時刻 (RFC 3339形式)
replicasint32-0 または 1 のみ。デフォルト: 1

Status フィールド

フィールド型説明
serviceFQDNstring内部 DNS 名 (例: sandbox-example.default.svc.cluster.local)
servicestringService 名
conditions[]metav1.Condition状態 (Ready 等)
replicasint32実際のレプリカ数
selectorstringPod セレクター

最小構成例

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
    name: my-sandbox
spec:
    podTemplate:
        spec:
            containers:
                - name: runtime
                  image: python:3.11
                  command: ["sleep", "infinity"]
                  ports:
                      - containerPort: 8888

自動削除の設定

spec:
    shutdownTime: "2025-12-31T23:59:59Z" # この時刻に自動削除

PVC 付きの例

spec:
    podTemplate:
        spec:
            containers:
                - name: runtime
                  image: python:3.11
                  volumeMounts:
                      - name: workspace
                        mountPath: /workspace
            volumes:
                - name: workspace
                  persistentVolumeClaim:
                      claimName: workspace-pvc
    volumeClaimTemplates:
        - metadata:
              name: workspace-pvc
          spec:
              accessModes: ["ReadWriteOnce"]
              resources:
                  requests:
                      storage: 10Gi

Controller が作成するリソース

flowchart LR
    Sandbox --> Pod
    Sandbox --> Service
    Sandbox --> PVC
    
    Service -->|ClusterIP| Pod
  • Pod: podTemplate に基づいて作成
  • Service: Sandbox と同名、headless ではない ClusterIP Service
  • PVC: volumeClaimTemplates から作成

SandboxClaim CRD

テンプレートから Sandbox を作成するリクエスト。ユーザーが直接 Sandbox 定義を書く必要がなくなる。

API 情報

項目値
API Groupextensions.agents.x-k8s.io
Versionv1alpha1
KindSandboxClaim
ScopeNamespaced
Short Namesandboxclaim

Spec フィールド

フィールド型必須説明
sandboxTemplateRefSandboxTemplateRef✓参照するテンプレート
sandboxTemplateRef.namestring✓テンプレート名

Status フィールド

フィールド型説明
conditions[]metav1.Condition状態
sandbox.Namestring作成された Sandbox 名

使用例

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
    name: my-sandbox-claim
    namespace: default
spec:
    sandboxTemplateRef:
        name: python-sandbox-template # 同一 namespace の SandboxTemplate

動作フロー

sequenceDiagram
    participant User
    participant K8s as Kubernetes API
    participant Ctrl as Extensions Controller
    participant Sandbox as Sandbox CRD
    
    User->>K8s: SandboxClaim 作成
    K8s->>Ctrl: 検知
    Ctrl->>K8s: SandboxTemplate 取得
    Ctrl->>Sandbox: Sandbox 作成 (Template の podTemplate + NetworkPolicy)
    Sandbox-->>Ctrl: Ready 状態
    Ctrl->>K8s: SandboxClaim.status 更新

Python SDK との連携

Python SDK は内部で SandboxClaim を使用:

from agentic_sandbox import SandboxClient

# 内部で SandboxClaim を作成
with SandboxClient(
    template_name="python-sandbox-template",
    namespace="default"
) as sandbox:
    result = sandbox.run("echo 'Hello'")
    print(result.stdout)
# 終了時に SandboxClaim (と Sandbox) を削除

SandboxTemplate CRD

Sandbox の再利用可能なテンプレート。NetworkPolicy による分離設定も可能。

API 情報

項目値
API Groupextensions.agents.x-k8s.io
Versionv1alpha1
KindSandboxTemplate
ScopeNamespaced
Short Namesandboxtemplate

Spec フィールド

フィールド型必須説明
podTemplatesandboxv1alpha1.PodTemplate✓Pod の定義 (Sandbox と同じ形式)
networkPolicyNetworkPolicySpec-ネットワーク分離設定

NetworkPolicySpec

フィールド型説明
ingress[]networkingv1.NetworkPolicyIngressRule許可する Ingress ルール
egress[]networkingv1.NetworkPolicyEgressRule許可する Egress ルール

注意: PodSelector と PolicyTypes はコントローラーが管理するため設定不可。デフォルトは全拒否。

基本例

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
    name: python-sandbox-template
spec:
    podTemplate:
        spec:
            containers:
                - name: python
                  image: python:3.11
                  ports:
                      - containerPort: 8888

セキュアな設定例

gVisor + NetworkPolicy による厳格な分離:

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
    name: secure-sandbox-template
spec:
    podTemplate:
        spec:
            runtimeClassName: gvisor # サンドボックスランタイム
            securityContext:
                runAsUser: 1000
                runAsGroup: 3000
                runAsNonRoot: true
            containers:
                - name: runtime
                  image: my-runtime:latest
                  ports:
                      - containerPort: 8888

    networkPolicy:
        # Ingress: 特定の Gateway からのみ許可
        ingress:
            - from:
                  - namespaceSelector:
                        matchLabels:
                            istio-injection: enabled
                    podSelector:
                        matchLabels:
                            app: istio-ingressgateway

            # Egress: DNS のみ許可 (API Server アクセスをブロック)
        egress:
            - ports:
                  - protocol: UDP
                    port: 53
                  - protocol: TCP
                    port: 53

NetworkPolicy の動作

flowchart TB
    subgraph "Default Deny"
        Sandbox1[Sandbox A]
        Sandbox2[Sandbox B]
    end
    
    Gateway[Ingress Gateway]
    DNS[DNS Server]
    APIServer[K8s API Server]
    
    Gateway -->|✓ 許可| Sandbox1
    Gateway -->|✓ 許可| Sandbox2
    Sandbox1 -.->|✗ ブロック| Sandbox2
    Sandbox1 -->|✓ DNS許可| DNS
    Sandbox1 -.->|✗ ブロック| APIServer

SandboxClaim との関係

flowchart LR
    Template[SandboxTemplate]
    Claim[SandboxClaim]
    Sandbox[Sandbox]
    
    Claim -->|参照| Template
    Claim -->|作成| Sandbox

SandboxWarmPool CRD

Sandbox の事前作成プール。コールドスタートを回避するためのウォームプール管理。

API 情報

項目値
API Groupextensions.agents.x-k8s.io
Versionv1alpha1
KindSandboxWarmPool
ScopeNamespaced
Short Nameswp

Spec フィールド

フィールド型必須説明
replicasint32✓プール内の Sandbox 数 (0以上)
sandboxTemplateRefSandboxTemplateRef✓参照するテンプレート
sandboxTemplateRef.namestring✓テンプレート名

Status フィールド

フィールド型説明
replicasint32現在のプール内 Sandbox 数
readyReplicasint32Ready 状態の Sandbox 数

kubectl 出力

NAME                    READY   AGE
sandboxwarmpool-example 3       10m

使用例

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
    name: python-sandbox-pool
spec:
    replicas: 3
    sandboxTemplateRef:
        name: python-sandbox-template

動作イメージ

flowchart TB
    subgraph WarmPool
        WP[SandboxWarmPool<br/>replicas: 3]
    end
    
    subgraph "Pre-created Sandboxes"
        S1[Sandbox-1<br/>Ready]
        S2[Sandbox-2<br/>Ready]
        S3[Sandbox-3<br/>Ready]
    end
    
    Template[SandboxTemplate]
    
    WP -->|参照| Template
    WP -->|維持| S1
    WP -->|維持| S2
    WP -->|維持| S3

HPA との連携

SandboxWarmPool は /scale subresource をサポート:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
    name: sandbox-pool-hpa
spec:
    scaleTargetRef:
        apiVersion: extensions.agents.x-k8s.io/v1alpha1
        kind: SandboxWarmPool
        name: python-sandbox-pool
    minReplicas: 1
    maxReplicas: 10
    metrics:
        - type: External
          external:
              metric:
                  name: queue_length
              target:
                  type: AverageValue
                  averageValue: 1

Agent Sandbox 概要

AI エージェントのための、Kubernetes 上の分離された実行環境を管理する CRDとコントローラー。

Repo: https://github.com/kubernetes-sigs/agent-sandbox

何ができるか

  • Sandbox: 単一のステートフルな Pod をライフサイクル管理 (作成、削除スケジュール、一時停止/再開)
  • 拡張機能: テンプレート化 (SandboxTemplate)、要求ベースの作成 (SandboxClaim)、プリウォーム (SandboxWarmPool)

アーキテクチャ

flowchart TB
    subgraph "Kubernetes Cluster"
        subgraph "Core Controller"
            SandboxCRD[Sandbox CRD]
            SandboxController[Sandbox Controller]
        end
        
        subgraph "Extensions Controller"
            SandboxTemplateCRD[SandboxTemplate CRD]
            SandboxClaimCRD[SandboxClaim CRD]
            SandboxWarmPoolCRD[SandboxWarmPool CRD]
            ExtController[Extensions Controller]
        end
        
        subgraph "Managed Resources"
            Pod[Pod]
            Service[Service]
            PVC[PVC]
            NetworkPolicy[NetworkPolicy]
        end
        
        SandboxController --> Pod
        SandboxController --> Service
        SandboxController --> PVC
        SandboxCRD --> SandboxController
        
        ExtController --> SandboxCRD
        SandboxTemplateCRD --> ExtController
        SandboxClaimCRD --> ExtController
        SandboxWarmPoolCRD --> ExtController
        ExtController --> NetworkPolicy
    end
    
    subgraph "Client Access"
        PythonSDK[Python SDK]
        SandboxRouter[Sandbox Router]
        Gateway[K8s Gateway]
    end
    
    PythonSDK --> Gateway
    PythonSDK --> SandboxRouter
    Gateway --> SandboxRouter
    SandboxRouter --> Service

ディレクトリ構造

agent-sandbox/
├── api/v1alpha1/           # Core CRD (Sandbox)
├── controllers/            # Core Controller
├── extensions/
│   ├── api/v1alpha1/       # 拡張 CRDs (Template, Claim, WarmPool)
│   └── controllers/        # 拡張 Controller
├── clients/python/         # Python SDK
├── examples/               # サンプル実装
└── k8s/                    # マニフェスト (CRD, RBAC)

インストール

# バージョン指定 (例: v0.1.0)
export VERSION="vX.Y.Z"

# Core のみ
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml

# 拡張機能も含む
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml

関連ドキュメント

Examples 一覧

ユースケース別のサンプル実装。

サンプル構成

例難易度説明
python-runtime-sandbox⭐基本: コマンド実行 API
aio-sandbox⭐All-in-One: VNC, VSCode, Jupyter 統合
gemini-cu-sandbox⭐⭐Computer Use: Gemini ブラウザ操作
vscode-sandbox⭐⭐VSCode + gVisor/Kata 分離
chrome-sandbox⭐⭐Chrome ブラウザ自動化

典型的なファイル構成

examples/<name>/
├── README.md              # セットアップ手順
├── Dockerfile             # ランタイムイメージ
├── main.py                # サーバー実装
├── sandbox-*.yaml         # Sandbox / SandboxTemplate 定義
├── run-test-docker.sh     # Docker での単体テスト
└── run-test-kind.sh       # Kind クラスタでの E2E テスト

ランタイムの API 規約

Python SDK と連携するには、Sandbox 内のサーバーが以下のエンドポイントを実装:

エンドポイントメソッドリクエストレスポンス
/executePOST{"command": "..."}{"stdout": "...", "stderr": "...", "exit_code": 0}
/uploadPOSTmultipart/form-data-
/download/{path}GET-file content

クイックスタート

# 1. SandboxTemplate 適用
kubectl apply -f examples/python-runtime-sandbox/sandbox-python-kind.yaml

# 2. Python SDK で接続
python3 -c "
from agentic_sandbox import SandboxClient
with SandboxClient(template_name='sandbox-python-example') as sb:
    print(sb.run('echo Hello').stdout)
"

aio-sandbox

All-in-One Sandbox。VNC、VSCode、Jupyter、Terminal を統合した環境。

Repo: https://github.com/kubernetes-sigs/agent-sandbox/tree/main/examples/aio-sandbox

概要

agent-infra/sandbox を使用したフル機能の開発環境。

flowchart TB
    subgraph AIO[AIO Sandbox Pod]
        VNC[VNC Server]
        VSCode[VSCode Server]
        Jupyter[Jupyter Lab]
        Terminal[Terminal]
    end
    
    Browser[Browser] --> Port8080[Port 8080]
    Port8080 --> AIO

マニフェスト

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
    name: aio-sandbox-example
spec:
    podTemplate:
        metadata:
            labels:
                sandbox: aio-sandbox-example
        spec:
            containers:
                - name: aio-sandbox
                  image: ghcr.io/agent-infra/sandbox:1.0.0.152
                  securityContext:
                      allowPrivilegeEscalation: false
                  ports:
                      - containerPort: 8080
                  resources:
                      limits:
                          memory: "4Gi"
                          cpu: "2000m"

アクセス方法

# Sandbox 作成
kubectl apply -f aio-sandbox.yaml
kubectl wait --for=condition=Ready sandbox aio-sandbox-example

# ポートフォワード
kubectl port-forward pod/aio-sandbox-example 8080:8080

# ブラウザでアクセス
open http://localhost:8080

Python SDK (agent-sandbox)

AIO 内部のツール制御には別の SDK を使用:

pip install agent-sandbox==0.0.18
from agent_sandbox import Sandbox

sandbox = Sandbox(base_url="http://localhost:8080")

# ブラウザ操作
screenshot = sandbox.browser.screenshot()

# シェル実行
result = sandbox.shell.run("ls -la")
print(result.output)

注意: agentic-sandbox-client は K8s リソース管理用、agent-sandbox は AIO 内操作用。

gemini-cu-sandbox

Gemini Computer Use (CU) エージェントを実行するサンドボックス。

Repo: https://github.com/kubernetes-sigs/agent-sandbox/tree/main/examples/gemini-cu-sandbox

概要

ブラウザを自動操作する Gemini エージェントを隔離環境で実行。

flowchart LR
    subgraph Sandbox
        FastAPI[FastAPI Server]
        Agent[Gemini CU Agent]
        Chrome[Headless Chrome]
    end
    
    Client[Client] -->|POST /agent| FastAPI
    FastAPI --> Agent
    Agent -->|操作| Chrome

前提条件

  1. Gemini API キーを Secret として作成
export GEMINI_API_KEY="your-api-key"
kubectl create secret generic gemini-api-key --from-literal=key=$GEMINI_API_KEY
  1. computer-use-preview リポジトリ (ビルド時に自動クローン)

マニフェスト

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
    name: sandbox-python-computeruse-template
spec:
    podTemplate:
        metadata:
            labels:
                app: sandbox
                sandbox: sandbox-python-computeruse
        spec:
            containers:
                - name: sandbox-python-computeruse
                  image: sandbox-gemini-runtime:latest
                  imagePullPolicy: IfNotPresent
                  ports:
                      - containerPort: 8888
                  env:
                      - name: GEMINI_API_KEY
                        valueFrom:
                            secretKeyRef:
                                name: gemini-api-key
                                key: key

API

/agent

curl -X POST http://localhost:8888/agent \
  -H "Content-Type: application/json" \
  -d '{"query": "Go to google.com and search for Kubernetes"}'
{
    "stdout": "Task completed. Found 10 results.",
    "stderr": "",
    "exit_code": 0
}

Python SDK

from agentic_sandbox.extensions import ComputerUseSandbox

with ComputerUseSandbox(
    template_name="sandbox-python-computeruse-template"
) as sandbox:
    result = sandbox.agent("Navigate to github.com")
    print(result.stdout)

テスト

# Docker テスト
./run-test-docker.sh

# Kind E2E テスト
./run-test-kind.sh

python-runtime-sandbox

最小構成の Python 実行環境。コマンド実行 API を提供。

Repo: https://github.com/kubernetes-sigs/agent-sandbox/tree/main/examples/python-runtime-sandbox

構成

flowchart LR
    Client[Client] --> FastAPI[FastAPI Server<br/>Port 8888]
    FastAPI --> Shell[Shell 実行]

API

エンドポイントメソッド説明
/executePOSTコマンド実行
/uploadPOSTファイルアップロード
/download/{path}GETファイルダウンロード

/execute

curl -X POST http://localhost:8888/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "python -c \"print(1+1)\""}'
{ "stdout": "2\n", "stderr": "", "exit_code": 0 }

マニフェスト

# sandbox-python-kind.yaml
apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
    name: sandbox-python-example
spec:
    podTemplate:
        metadata:
            labels:
                sandbox: my-python-sandbox
        spec:
            containers:
                - name: python-sandbox
                  image: sandbox-runtime:latest
                  imagePullPolicy: IfNotPresent
                  ports:
                      - containerPort: 8888

ローカルテスト

# Docker で実行
./run-test-docker.sh

# Kind クラスタで E2E テスト
./run-test-kind.sh

Python SDK から使用

from agentic_sandbox import SandboxClient

with SandboxClient(template_name="sandbox-python-example") as sandbox:
    result = sandbox.run("python -c \"import sys; print(sys.version)\"")
    print(result.stdout)

vscode-sandbox

VSCode Server を実行するサンドボックス。gVisor / Kata Containersによる分離オプション付き。

Repo: https://github.com/kubernetes-sigs/agent-sandbox/tree/main/examples/vscode-sandbox

概要

flowchart TB
    subgraph Sandbox[Sandbox Pod]
        Envbuilder[Envbuilder<br/>初期化]
        VSCode[VSCode Server<br/>Port 13337]
    end
    
    Envbuilder --> VSCode
    Browser[Browser] --> VSCode

ランタイムオプション

オプション分離レベル設定
Standardコンテナデフォルト
gVisorユーザースペースカーネルruntimeClassName: gvisor
KataMicroVMruntimeClassName: kata-qemu

デプロイ

# Standard
kubectl apply -k base

# gVisor
kubectl apply -k overlays/gvisor

# Kata Containers
kubectl apply -k overlays/kata

アクセス

Standard Runtime

kubectl wait --for=condition=Ready sandbox sandbox-example
kubectl port-forward pod/sandbox-example 13337:13337
open http://localhost:13337

gVisor / Kata (Router 経由)

直接の port-forward は非対応。Sandbox Router を使用:

# Router デプロイ
kubectl apply -f clients/python/agentic-sandbox-client/sandbox-router/sandbox_router.yaml

# Router へ port-forward
kubectl port-forward svc/sandbox-router-svc 8080:8080

# curl でアクセス (ヘッダー指定)
curl -H "X-Sandbox-ID: sandbox-example" \
     -H "X-Sandbox-Port: 13337" \
     http://localhost:8080

ブラウザでのアクセス (ModHeader 等)

  1. ブラウザ拡張で以下のヘッダーを追加:
    • X-Sandbox-ID: sandbox-example
    • X-Sandbox-Port: 13337
  2. http://localhost:8080 にアクセス

パスワード取得

認証が有効な場合:

kubectl exec sandbox-example -- cat /root/.config/code-server/config.yaml

ComputerUseSandbox 拡張

Gemini Computer Use エージェント向けの拡張クライアント。

概要

ComputerUseSandbox は SandboxClient を継承し、Computer Use(ブラウザ操作等)に特化した agent() メソッドを追加。

クラス定義

from agentic_sandbox.extensions import ComputerUseSandbox

class ComputerUseSandbox(SandboxClient):
    def __init__(
        self,
        template_name: str,
        namespace: str = "default",
        server_port: int = 8080  # Computer Use runtime のデフォルト
    )
    
    def agent(self, query: str, timeout: int = 60) -> ExecutionResult:
        """自然言語クエリをエージェントに実行させる"""

使用例

from agentic_sandbox.extensions import ComputerUseSandbox

with ComputerUseSandbox(
    template_name="sandbox-python-computeruse-template",
    namespace="default"
) as sandbox:
    result = sandbox.agent("Go to google.com and search for 'Kubernetes'")
    print(result.stdout)

前提条件

  1. Gemini Computer Use ランタイムイメージをビルド済み
  2. gemini-api-key Secret が作成済み
kubectl create secret generic gemini-api-key --from-literal=key=$GEMINI_API_KEY

関連

Python SDK

Sandbox とプログラム的に対話するための Python クライアントライブラリ。

モジュール構成

モジュール説明ドキュメント
agentic_sandbox.SandboxClientメインクライアント詳細
agentic_sandbox.extensions.ComputerUseSandboxComputer Use 拡張詳細

インフラストラクチャ

コンポーネント説明ドキュメント
Sandbox Router動的ルーティングプロキシ詳細

クイックスタート

pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@main#subdirectory=clients/python/agentic-sandbox-client"
from agentic_sandbox import SandboxClient

with SandboxClient(template_name="python-sandbox-template") as sandbox:
    result = sandbox.run("echo 'Hello, World!'")
    print(result.stdout)  # Hello, World!

詳細ドキュメント

Python SDK (agentic-sandbox-client)

Kubernetes 上の Sandbox と対話するための Python クライアント。

インストール

# Git から直接
pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@main#subdirectory=clients/python/agentic-sandbox-client"

# ローカルから (開発用)
pip install -e clients/python/agentic-sandbox-client/

アーキテクチャ

flowchart LR
    subgraph "Client Modes"
        SDK[Python SDK]
    end
    
    subgraph "Gateway Mode (Production)"
        GW[K8s Gateway<br/>Public IP]
    end
    
    subgraph "Tunnel Mode (Development)"
        PF[kubectl port-forward]
    end
    
    subgraph "Kubernetes"
        Router[Sandbox Router]
        Sandbox[Sandbox Pod]
    end
    
    SDK -->|gateway_name 指定| GW
    SDK -->|未指定| PF
    GW --> Router
    PF --> Router
    Router -->|X-Sandbox-ID| Sandbox

接続モード

モード設定方法ユースケース
Productiongateway_name を指定本番環境、外部アクセス
Tunnel何も指定しないローカル開発、CI
Directapi_url を指定クラスタ内部、カスタムドメイン

SandboxClient クラス

コンストラクタ

SandboxClient(
    template_name: str,           # 必須: SandboxTemplate 名
    namespace: str = "default",   # Sandbox の namespace
    gateway_name: str | None = None,     # Gateway リソース名 (Production Mode)
    gateway_namespace: str = "default",  # Gateway の namespace
    api_url: str | None = None,          # 直接 URL 指定 (Direct Mode)
    server_port: int = 8888,             # Sandbox 内サーバーのポート
    sandbox_ready_timeout: int = 180,    # Sandbox Ready 待機タイムアウト (秒)
    gateway_ready_timeout: int = 180,    # Gateway IP 取得タイムアウト (秒)
    port_forward_ready_timeout: int = 30 # Port Forward 確立タイムアウト (秒)
)

メソッド

メソッド戻り値説明
run(command, timeout=60)ExecutionResultコマンド実行
write(path, content, timeout=60)Noneファイル書き込み
read(path, timeout=60)bytesファイル読み込み
is_ready()bool接続可能かどうか

ExecutionResult

@dataclass
class ExecutionResult:
    stdout: str
    stderr: str
    exit_code: int

使用例

基本 (Tunnel Mode)

from agentic_sandbox import SandboxClient

with SandboxClient(
    template_name="python-sandbox-template",
    namespace="default"
) as sandbox:
    # コマンド実行
    result = sandbox.run("python -c \"print('Hello')\"")
    print(result.stdout)  # Hello
    
    # ファイル操作
    sandbox.write("/tmp/script.py", "print('World')")
    result = sandbox.run("python /tmp/script.py")
    print(result.stdout)  # World

Production Mode

with SandboxClient(
    template_name="python-sandbox-template",
    gateway_name="external-http-gateway",
    gateway_namespace="default"
) as sandbox:
    sandbox.run("echo 'From Production'")

Direct Mode (クラスタ内部)

with SandboxClient(
    template_name="python-sandbox-template",
    api_url="http://sandbox-router-svc.default.svc.cluster.local:8080"
) as sandbox:
    sandbox.run("echo 'Internal Access'")

前提条件

  1. Sandbox Router がデプロイ済み
  2. SandboxTemplate が作成済み
  3. kubectl が設定済み (Tunnel Mode の場合)

内部動作

sequenceDiagram
    participant Client as SandboxClient
    participant K8s as Kubernetes API
    participant Router as Sandbox Router
    participant Sandbox as Sandbox Pod
    
    Client->>K8s: SandboxClaim 作成
    K8s-->>Client: Sandbox Ready
    
    alt Tunnel Mode
        Client->>Client: kubectl port-forward 開始
    else Gateway Mode
        Client->>K8s: Gateway IP 取得
    end
    
    Client->>Router: POST /execute + X-Sandbox-ID
    Router->>Sandbox: Proxy Request
    Sandbox-->>Router: Response
    Router-->>Client: Response
    
    Client->>K8s: SandboxClaim 削除

Sandbox Router

Sandbox への動的ルーティングを行うリバースプロキシ。

役割

  • 単一エンドポイントで多数の Sandbox にアクセス
  • X-Sandbox-ID ヘッダーで宛先を決定
  • K8s 内部 DNS で Sandbox Service を解決

ルーティング

flowchart LR
    Client[Client]
    Router[Sandbox Router]
    SB1[sandbox-1.default.svc.cluster.local]
    SB2[sandbox-2.default.svc.cluster.local]
    
    Client -->|X-Sandbox-ID: sandbox-1| Router
    Router --> SB1
    
    Client -->|X-Sandbox-ID: sandbox-2| Router
    Router --> SB2

ヘッダー

ヘッダー必須デフォルト説明
X-Sandbox-ID✓-Sandbox 名 (Service 名)
X-Sandbox-Namespace-defaultSandbox の namespace
X-Sandbox-Port-8888Sandbox 内サーバーのポート

デプロイ

# イメージのビルド
docker build -t your-registry/sandbox-router:latest -f sandbox-router/Dockerfile .
docker push your-registry/sandbox-router:latest

# デプロイ
export SANDBOX_ROUTER_IMG=your-registry/sandbox-router:latest
sed -i "s|IMAGE_PLACEHOLDER|${SANDBOX_ROUTER_IMG}|g" sandbox_router.yaml
kubectl apply -f sandbox_router.yaml

# Gateway (Production Mode 用、GKE 専用)
kubectl apply -f gateway.yaml

エンドポイント

パスメソッド説明
/healthzGETヘルスチェック ({"status": "ok"})
/{path}ALLSandbox へのプロキシ

Sponsors

Details

Marketplace
khirotaka/cc-plugins
Source
plugins/agent-sandbox-docs
Category
Community