
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-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add khirotaka/cc-plugins.
Contents
Discovered from sourceSkills 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_name | str | (必須) | SandboxTemplate名 |
namespace | str | "default" | namespace |
gateway_name | str | None | None | Gateway名 (Production) |
api_url | str | None | None | 直接URL (Direct) |
server_port | int | 8888 | Sandboxサーバーポート |
コアメソッド:
| メソッド | 戻り値 | 説明 |
|---|---|---|
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/フィールドクエリ
- SKILL.mdのCRD Reference Map確認
- grepで詳細抽出
- 必要なら完全ファイル読み込み
実装ガイダンス
- Common Query Patterns確認
- Implementation Examples Index参照
- 該当例ファイル読み込み
SDK使用方法
- Python SDK Reference確認
- 基本用法はSKILL.mdで完結
- 高度な用法は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.io | Core API (Sandbox) |
extensions.agents.x-k8s.io | Extensions API (Template, Claim, WarmPool) |
CRD 一覧
Core
| Kind | 説明 | ドキュメント |
|---|---|---|
| Sandbox | 単一のステートフル Pod を管理 | 詳細 |
Extensions
| Kind | 説明 | ドキュメント |
|---|---|---|
| SandboxTemplate | 再利用可能なテンプレート + NetworkPolicy | 詳細 |
| SandboxClaim | テンプレートから Sandbox を要求 | 詳細 |
| SandboxWarmPool | Sandbox のプリウォームプール | 詳細 |
リソース関係
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 Group | agents.x-k8s.io |
| Version | v1alpha1 |
| Kind | Sandbox |
| Scope | Namespaced |
| Short Name | sandbox |
Spec フィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
podTemplate | PodTemplate | ✓ | Pod の定義 |
podTemplate.spec | corev1.PodSpec | ✓ | Pod の spec |
podTemplate.metadata | PodMetadata | - | labels, annotations |
volumeClaimTemplates | []PersistentVolumeClaimTemplate | - | PVC テンプレート |
shutdownTime | metav1.Time | - | 自動削除時刻 (RFC 3339形式) |
replicas | int32 | - | 0 または 1 のみ。デフォルト: 1 |
Status フィールド
| フィールド | 型 | 説明 |
|---|---|---|
serviceFQDN | string | 内部 DNS 名 (例: sandbox-example.default.svc.cluster.local) |
service | string | Service 名 |
conditions | []metav1.Condition | 状態 (Ready 等) |
replicas | int32 | 実際のレプリカ数 |
selector | string | Pod セレクター |
最小構成例
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 Group | extensions.agents.x-k8s.io |
| Version | v1alpha1 |
| Kind | SandboxClaim |
| Scope | Namespaced |
| Short Name | sandboxclaim |
Spec フィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
sandboxTemplateRef | SandboxTemplateRef | ✓ | 参照するテンプレート |
sandboxTemplateRef.name | string | ✓ | テンプレート名 |
Status フィールド
| フィールド | 型 | 説明 |
|---|---|---|
conditions | []metav1.Condition | 状態 |
sandbox.Name | string | 作成された 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 Group | extensions.agents.x-k8s.io |
| Version | v1alpha1 |
| Kind | SandboxTemplate |
| Scope | Namespaced |
| Short Name | sandboxtemplate |
Spec フィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
podTemplate | sandboxv1alpha1.PodTemplate | ✓ | Pod の定義 (Sandbox と同じ形式) |
networkPolicy | NetworkPolicySpec | - | ネットワーク分離設定 |
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 Group | extensions.agents.x-k8s.io |
| Version | v1alpha1 |
| Kind | SandboxWarmPool |
| Scope | Namespaced |
| Short Name | swp |
Spec フィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
replicas | int32 | ✓ | プール内の Sandbox 数 (0以上) |
sandboxTemplateRef | SandboxTemplateRef | ✓ | 参照するテンプレート |
sandboxTemplateRef.name | string | ✓ | テンプレート名 |
Status フィールド
| フィールド | 型 | 説明 |
|---|---|---|
replicas | int32 | 現在のプール内 Sandbox 数 |
readyReplicas | int32 | Ready 状態の 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
関連ドキュメント
- CRDリファレンス: 各CRDの詳細な仕様
- Python SDK: Python クライアントライブラリ
- 実践例: ユースケース別のサンプル
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 内のサーバーが以下のエンドポイントを実装:
| エンドポイント | メソッド | リクエスト | レスポンス |
|---|---|---|---|
/execute | POST | {"command": "..."} | {"stdout": "...", "stderr": "...", "exit_code": 0} |
/upload | POST | multipart/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
前提条件
- Gemini API キーを Secret として作成
export GEMINI_API_KEY="your-api-key"
kubectl create secret generic gemini-api-key --from-literal=key=$GEMINI_API_KEY
- 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
| エンドポイント | メソッド | 説明 |
|---|---|---|
/execute | POST | コマンド実行 |
/upload | POST | ファイルアップロード |
/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 |
| Kata | MicroVM | runtimeClassName: 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 等)
- ブラウザ拡張で以下のヘッダーを追加:
X-Sandbox-ID: sandbox-exampleX-Sandbox-Port: 13337
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)
前提条件
- Gemini Computer Use ランタイムイメージをビルド済み
gemini-api-keySecret が作成済み
kubectl create secret generic gemini-api-key --from-literal=key=$GEMINI_API_KEY
関連
Python SDK
Sandbox とプログラム的に対話するための Python クライアントライブラリ。
モジュール構成
| モジュール | 説明 | ドキュメント |
|---|---|---|
agentic_sandbox.SandboxClient | メインクライアント | 詳細 |
agentic_sandbox.extensions.ComputerUseSandbox | Computer 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!
詳細ドキュメント
- SandboxClient: 接続モード、メソッド、内部動作
- SandboxRouter: ルーティング、デプロイ方法
- ComputerUseExtension: Gemini CU 連携
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
接続モード
| モード | 設定方法 | ユースケース |
|---|---|---|
| Production | gateway_name を指定 | 本番環境、外部アクセス |
| Tunnel | 何も指定しない | ローカル開発、CI |
| Direct | api_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'")
前提条件
- Sandbox Router がデプロイ済み
- SandboxTemplate が作成済み
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 | - | default | Sandbox の namespace |
X-Sandbox-Port | - | 8888 | Sandbox 内サーバーのポート |
デプロイ
# イメージのビルド
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
エンドポイント
| パス | メソッド | 説明 |
|---|---|---|
/healthz | GET | ヘルスチェック ({"status": "ok"}) |
/{path} | ALL | Sandbox へのプロキシ |
Sponsors
Details
- Marketplace
- khirotaka/cc-plugins
- Source
- plugins/agent-sandbox-docs
- Category
- Community