app-platform-sandbox

サンドボックススキル

AI エージェントやテストワークフロー向けの分離された実行環境です。

基本方針

Lambda/Functions: Fast cold start, 15-min limit, stateless, per-ms billing
App Platform Sandbox: 30s cold start (or instant with pool), unlimited duration, stateful, per-hour billing

Sweet spot: Long-running, stateful, iterative workflows where agents need to
install packages, run code, check results, modify, repeat.

選択の目安

┌─────────────────────────────────────────────────────────────┐
│         Need isolated execution environment?                 │
└─────────────────────────────────────────────────────────────┘
                            │
              Is this for debugging an EXISTING app?
                            │
            ┌───────────────┴───────────────┐
            │                               │
           YES                              NO
            │                               │
            ▼                               ▼
   ┌─────────────────┐           ┌─────────────────┐
   │ troubleshooting │           │ Need real-time  │
   │ skill           │           │ streaming or    │
   │                 │           │ port exposure?  │
   │ Sandbox.get_    │           │                 │
   │ from_id()       │           └────────┬────────┘
   └─────────────────┘                    │
                          ┌───────────────┴───────────────┐
                          │                               │
                         YES                              NO
                          │                               │
                          ▼                               ▼
                 ┌─────────────────┐           ┌─────────────────┐
                 │ SERVICE MODE    │           │ Is low latency  │
                 │ exec_stream()   │           │ critical?       │
                 │ expose_port()   │           │                 │
                 └─────────────────┘           └────────┬────────┘
                                                        │
                                        ┌───────────────┴───────────────┐
                                        │                               │
                                       YES                              NO
                                        │                               │
                                        ▼                               ▼
                               ┌─────────────────┐           ┌─────────────────┐
                               │ HOT POOL        │           │ COLD SANDBOX    │
                               │ SandboxManager  │           │ Sandbox.create()│
                               │ ~50ms acquire   │           │ ~30s startup    │
                               └─────────────────┘           └─────────────────┘

---

前提条件

# Verify doctl is installed and authenticated
doctl auth whoami

# Install the SDK (choose one)
uv pip install do-app-sandbox
# OR
pip install do-app-sandbox

# For Spaces support (large file transfers)
pip install "do-app-sandbox[spaces]"

要件：

• Python 3.10.12+
• doctl CLI がインストールされ、認証済みであること
• App Platform にアクセスできる DigitalOcean アカウント

---

クイックスタート：コールドサンドボックス

起動時間約 30 秒で、単一のサンドボックスを作成します。

from do_app_sandbox import Sandbox

# Create sandbox with Python image
sandbox = Sandbox.create(
    image="python",           # or "node"
    name="my-sandbox",
    region="nyc",
    instance_size="apps-s-1vcpu-1gb"
)

# Execute code
result = sandbox.exec("python3 -c 'import sys; print(sys.version)'")
print(result.stdout)

# File operations
sandbox.filesystem.write_file("/tmp/script.py", "print('hello')")
result = sandbox.exec("python3 /tmp/script.py")

# Clean up
sandbox.delete()

詳しいガイド：cold-sandbox.md を参照してください。

---

クイックスタート：ホットプール

すぐに取得できるよう事前にウォームアップされたサンドボックスです。

import asyncio
from do_app_sandbox import SandboxManager, PoolConfig

async def main():
    # 1. Configure pool
    manager = SandboxManager(
        pools={"python": PoolConfig(target_ready=3)},
    )

    # 2. Start and warm up (blocks until pool is ready)
    await manager.start()
    await manager.warm_up(timeout=180)

    # 3. Acquire instantly (~500ms from pool vs 30s cold start)
    sandbox = await manager.acquire(image="python")
    result = sandbox.exec("python3 -c 'print(2+2)'")
    print(result.stdout)

    # 4. Delete when done - YOUR responsibility!
    sandbox.delete()

    # 5. Shutdown (cleans up pool, not acquired sandboxes)
    await manager.shutdown()

asyncio.run(main())

**所有権モデル：**サンドボックスを acquire() した時点で、そのサンドボックスの所有者になります。使用後は必ず sandbox.delete() を呼び出してください。shutdown() がクリーンアップするのは、プールにまだ残っているサンドボックスのみです。

詳しいガイド：hot-pool.md を参照してください。

---

クイックリファレンス：サンドボックスを使う場面

シナリオ	推奨
AI コードインタープリター	ホットプール（即時応答）
複数ステップのエージェントワークフロー	単一のサンドボックス（1 つのサンドボックス内で状態が保持されます）
単発のスクリプトテスト	コールドサンドボックス（シンプル）
CI 統合テスト	コールドサンドボックス（ジョブごと）
短時間のタスク（< 30s）	代わりに Lambda を検討してください
高い同時実行性（1000+）	代わりに Lambda を検討してください

---

クイックリファレンス：利用可能なイメージ

イメージ	レジストリ	用途
python	ghcr.io/bikramkgupta/sandbox-python	Python 3.13、uv、pip
node	ghcr.io/bikramkgupta/sandbox-node	Node.js 24、nvm

作業ディレクトリ：/home/sandbox/app（/app のシンボリックリンクあり）。ポート：8080（ユーザーアプリ）、9090（ヘルスチェック）。

カスタムイメージにも対応しています。HTTP サーバー機能を備えた任意の Docker イメージを使用できます。

---

クイックリファレンス：SDK メソッド

メソッド	目的
Sandbox.create(image, mode=...)	サンドボックスを作成します（WORKER または SERVICE モード）
Sandbox.get_from_id()	既存のアプリに接続します
sandbox.exec(cmd)	シェルコマンドを実行します
sandbox.exec_stream(cmd)	出力をストリーミングします（SERVICE モード）
sandbox.expose_port(port)	ポートの公開 URL を取得します（SERVICE モード）
sandbox.hibernate()	コスト削減のため、スナップショットを作成して削除します
Sandbox.wake(hibernated)	休止状態のサンドボックスを復元します
sandbox.filesystem.read_file()	ファイルの内容を読み取ります
sandbox.filesystem.write_file()	ファイルを書き込みます
sandbox.delete()	サンドボックスを削除します（使用後は必ず呼び出してください）
SandboxManager(pools={...})	ホットプールを設定します
manager.start()	バックグラウンドでプール管理を開始します
manager.warm_up(timeout)	プールが目標数に達するまで待機します（非同期）
manager.acquire(image=...)	プールからサンドボックスを取得します（非同期）
manager.acquire_with_snapshot()	事前設定された状態のサンドボックスを取得します
manager.shutdown()	プールを停止します（プールのみをクリーンアップします）

---

リファレンスファイル

• cold-sandbox.md — 単一サンドボックスのライフサイクル、ファイル操作、クリーンアップ
• hot-pool.md — プール管理、サイズ設定、コスト最適化
• service-mode.md — ストリーミング、ポート公開、AI エージェントのパターン
• use-cases.md — AI エージェントのパターン、テストのパターン
• positioning.md — Lambda とサンドボックスの選択ガイド

---

コストに関する考慮事項

Sandbox billing: ~$0.01-0.03/hour per container (apps-s-1vcpu-1gb)

Hot Pool trade-off:
- Pool of 5 sandboxes running 8 hours = ~$0.80-2.40/day
- Eliminates 30s cold start per request
- Worth it for interactive AI agents, not for batch jobs

---

他のスキルとの連携

方向	スキル	場面
→	troubleshooting	既存のサンドボックスをデバッグする場合（Sandbox.get_from_id() を使用）
→	designer	アプリの仕様にサンドボックス対応ワーカーを含める場合
←	deployment	サンドボックスは独立しており、メインアプリのデプロイには含まれません