AIO Sandbox入門：AIエージェント実行環境をDocker1つで構築する方法

AIエージェントを開発するとき、ブラウザ自動化・ターミナル・ファイル操作・MCPサーバーを個別にセットアップしていないだろうか。AIO Sandbox（agent-infra/sandbox）は、これら6つの機能を単一のDockerコンテナに統合し、docker run 1回で完結する実行環境を提供する。GitHub Stars 4,200超、Apache 2.0ライセンスで公開されているOSSだ。

この記事ではAIエージェントに特化して解説します。AIエージェント全般は AIエージェントフレームワーク比較2026年版 をご覧ください。

AIO Sandboxとは：AIエージェント向け統合サンドボックス環境

AIO Sandboxは、AIエージェントの実行に必要な機能を1つのDockerコンテナに集約するオープンソースプロジェクトだ。従来のサンドボックスはブラウザ特化（Browserless）やシェル特化など単一目的だったが、AIO Sandboxはブラウザ自動化（VNC/CDP）、シェル、ファイルシステム、MCPサーバー、VSCode Server、Jupyter Notebookの6つを統合する。

統合の最大のメリットはファイルシステムの共有にある。ブラウザでダウンロードしたファイルをシェルでそのまま処理し、Jupyterで分析する。コンテナ内のファイルシステムが一つだからこそ可能なワークフローだ。

従来は機能ごとに別コンテナを立て、ボリュームマウントやネットワーク共有でファイルを受け渡していた。AIO Sandboxでは1コンテナ・1ファイルシステムで完結するため、データ連携の設計負荷が激減する。特にAIエージェントが「スクレイピング → 解析 → レポート生成」のような連鎖タスクを実行する際、この統合性が開発スピードを左右する。

クイックスタート：Docker 1コマンドで起動する手順

起動はDockerコマンド1つで完了する。

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

起動後、以下のURLでサービスにアクセスできる。

特定バージョンを指定する場合は、イメージタグにバージョン番号を付与する。

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:1.0.0.150

--security-opt seccomp=unconfined はブラウザ（Chromium）がサンドボックス内で起動するために必要な指定だ。Chromiumはユーザーネームスペースやseccomp-bpfを使うため、デフォルトのDockerプロファイルでは制限に引っかかる。本番運用では専用のseccompプロファイルを作成して絞り込むのが望ましい。

初回起動時はイメージプル（約1.5GB）が発生するため、ネットワーク帯域を確認しておくとよい。起動後の内部サービスは以下の順で準備される。

1. ベースプロセス（supervisord）の起動
2. VNC / noVNCサーバーの起動
3. code-server（VSCode Server）の起動
4. Jupyter Notebookサーバーの起動
5. MCPエンドポイントの公開
6. REST APIゲートウェイの待受開始

http://localhost:8080/v1/sandbox にGETリクエストを送り、200レスポンスが返れば全サービスの準備完了だ。起動ログは docker logs <container> で確認できる。

Python / TypeScript SDKでエージェントから操作する

AIO SandboxはPython、TypeScript、Goの3言語でSDKを公式提供している。SDKを通じてシェル実行、ファイル操作、ブラウザ自動化をプログラムから制御できる。

SDKのインストールは以下の通り。

# Python
pip install agent-sandbox

# TypeScript / JavaScript
npm install @agent-infra/sandbox

# Go
go get github.com/agent-infra/sandbox-sdk-go

Python SDKでシェルコマンドの実行とファイル読み込みを行う基本例を示す。

from agent_sandbox import Sandbox

# クライアント初期化
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir

# シェルコマンド実行
result = client.shell.exec_command(command="ls -la")
print(result.data.output)

# ファイル読み込み
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)

# ブラウザのスクリーンショット取得
screenshot = client.browser.screenshot()

TypeScriptでも同等の操作が可能だ。

import { Sandbox } from '@agent-infra/sandbox';

const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });

// シェルコマンド実行
const result = await sandbox.shell.exec({ command: 'ls -la' });
console.log(result.output);

// ファイル読み込み
const content = await sandbox.file.read({ path: '/home/gem/.bashrc' });
console.log(content);

// ブラウザのスクリーンショット取得
const screenshot = await sandbox.browser.screenshot();

OpenHandsのようなAIコーディングエージェントを構築する際に、このSDKを通じてサンドボックス内でコード実行やファイル操作を安全に行える。SDKはすべて同じREST APIを叩く薄いラッパーなので、言語を跨いだ挙動の差異はほぼない。チームのスキルセットに合わせて自由に選べる。

SDKが提供する主なモジュールは以下の4カテゴリに整理される。

エージェントの実装では、LLMのfunction callingスキーマにこれらのメソッドを登録して呼び出す形が一般的だ。ツールごとの入出力が明確なので、Claude / GPT / Geminiのどのモデルでも扱いやすい。

MCPサーバー統合：4つのプリセットツールで即座に接続

AIO Sandboxには4種類のMCPサーバーがプリセットで組み込まれている。エージェントはMCPプロトコル経由でブラウザ操作、ファイル管理、シェル実行、ドキュメント変換を利用できる。MCPサーバーの仕組みを理解していれば、追加のMCPサーバーを接続することも可能だ。

MCPエンドポイントは http://localhost:8080/mcp で公開される。Claude DesktopやClineなどのMCPクライアントから接続すれば、エージェントがサンドボックス内のリソースに安全にアクセスできる。

Claude Desktopから接続する場合の設定例は以下の通り。

{
  "mcpServers": {
    "aio-sandbox": {
      "url": "http://localhost:8080/mcp",
      "transport": "sse"
    }
  }
}

SSE（Server-Sent Events）トランスポートでMCPエンドポイントに接続すれば、Claude Desktopから直接ブラウザ・シェル・ファイル操作をツールとして呼び出せる。ローカルのClaude Desktopに「この画面をスクショして」「このディレクトリをlsして」と指示するだけで、サンドボックス内の操作が実行される。

実践例：Webページをスクレイピングしてマークダウンに変換

公式READMEに記載されている実践的な例として、Webページをブラウザで取得し、Jupyter上でマークダウンに変換するワークフローがある。ブラウザ・Jupyter・シェル・ファイル操作の4機能を横断する処理が、共有ファイルシステムのおかげでシームレスに動作する。

import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox

async def site_to_markdown():
    c = Sandbox(base_url="http://localhost:8080")
    home_dir = c.sandbox.get_context().home_dir

    # ブラウザ: CDPでページを取得しスクリーンショットを撮影
    async with async_playwright() as p:
        browser_info = c.browser.get_info().data
        page = await (await p.chromium.connect_over_cdp(
            browser_info.cdp_url
        )).new_page()
        await page.goto("https://example.com", wait_until="networkidle")
        html = await page.content()
        screenshot_b64 = base64.b64encode(
            await page.screenshot()
        ).decode('utf-8')

    # Jupyter: HTML→マークダウン変換をサンドボックス内で実行
    c.jupyter.execute_code(code=f"""
from markdownify import markdownify
md = markdownify('''{html}''')
with open('{home_dir}/site.md', 'w') as f:
    f.write(md)
print("変換完了")
""")

    # シェル: 生成ファイルを確認
    list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
    print(list_result.data.output)

    # ファイル: 生成したマークダウンを取得
    return c.file.read_file(file=f"{home_dir}/site.md").data.content

asyncio.run(site_to_markdown())

この例では、CDP（Chrome DevTools Protocol）でブラウザを操作し、取得したHTMLをJupyter Notebookで変換し、シェルとファイルAPIで結果を確認している。すべてが1コンテナ内で完結するため、ファイルパスの受け渡しに外部ストレージは不要だ。

このワークフローを別の構成（例: Playwright専用コンテナ + Jupyterコンテナ）で組む場合、共有ボリュームの設計、ネットワーク分離、タイムアウト設定など考慮すべき項目が一気に増える。AIO Sandboxなら同じファイルシステムを全機能が参照するため、/home/gem/site.md のような絶対パス1つですべての機能が協調動作する。

Docker Compose / Kubernetes本番デプロイ構成

開発環境から本番環境まで、Docker ComposeとKubernetesの両方に対応している。

Docker Composeで永続化ボリュームとメモリ制限を設定した構成例を示す。

version: '3.8'
services:
  sandbox:
    container_name: aio-sandbox
    image: ghcr.io/agent-infra/sandbox:latest
    volumes:
      - /tmp/gem/workspace:/home/gem/workspace
    security_opt:
      - seccomp:unconfined
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      TZ: Asia/Tokyo
      WORKSPACE: "/home/gem"

Kubernetesで2レプリカのデプロイメントを構成する場合は以下の通り。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aio-sandbox
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aio-sandbox
  template:
    metadata:
      labels:
        app: aio-sandbox
    spec:
      containers:
      - name: aio-sandbox
        image: ghcr.io/agent-infra/sandbox:latest
        ports:
        - containerPort: 8080
        resources:
          limits:
            memory: "2Gi"
            cpu: "1000m"

複数エージェントを同時に運用する場合は、Kubernetesのレプリカ数を増やすだけで独立したサンドボックス環境を水平スケールできる。ForgeCodeのようなAIコーディングツールのバックエンドとして、サンドボックスを複数並列実行する運用にも向いている。

本番運用では以下の観点を押さえておくとよい。

特にshm_sizeは指定を忘れると数時間で「Chromium crashed」エラーが頻発するため、最初に必ず設定しておきたい。

競合比較：単機能サンドボックスとの違い

AIO Sandboxの最大の差別化ポイントは「統合度」にある。従来のサンドボックスは単一機能に特化していたが、AIO Sandboxはエージェント開発に必要な要素をすべて1つのイメージに統合する。

Browserlessはブラウザ特化で高性能だが、シェル・ファイル操作との連携には別サービスが必要になる。E2Bはコード実行環境としては優秀だが、ブラウザ自動化が限定的でMCP統合もない。AIO Sandboxは「すべてを1コンテナに」というアプローチで、エージェントのブラウザ自動化からファイル操作まで統合的に扱える点が強みだ。

どのツールを選ぶべきかは、ユースケースによって変わる。

• ブラウザ単機能で高スケールが必要→Browserless
• コード実行サンドボックスのSaaSで楽をしたい→E2B（有料）
• AWSリソースをローカルで模倣したい→LocalStack
• AIエージェント向けの統合環境をセルフホストしたい→AIO Sandbox

「複数機能 × セルフホスト × 商用利用可（Apache 2.0）」という組み合わせを満たすのはAIO Sandboxのみだ。特にオンプレ要件やデータ主権要件がある企業では、SaaS型のE2Bが使えないケースが多く、AIO Sandboxの価値が際立つ。

REST APIエンドポイント一覧

AIO SandboxはREST APIを提供しており、SDKを使わずにHTTPリクエストで操作できる。

APIドキュメントは起動後に http://localhost:8080/v1/docs で確認できる。OpenAPI仕様に準拠しているため、任意のHTTPクライアントやLLMのfunction callingから利用可能だ。

OpenAPI仕様に準拠しているため、LLMのfunction callingに直接流し込んで利用することも可能だ。/v1/docs のJSON定義をツール定義に変換すれば、エージェントが能動的にサンドボックスを操作できる。

📌 まとめ：AIエージェント開発環境の選び方

AIO Sandboxは「AIエージェントに必要な実行環境を、Docker 1コマンドで手に入れる」という明確なコンセプトを持つ。ブラウザ自動化・シェル・ファイル・MCP・VSCode・Jupyterの6機能が単一コンテナで動作し、共有ファイルシステムにより機能間のデータ連携もシームレスだ。

Python / TypeScript / GoのSDKが揃っており、既存のエージェントフレームワークとの統合も容易になっている。Apache 2.0ライセンスで商用利用も可能なため、プロトタイプから本番環境まで一貫して使える選択肢となる。

導入を検討する際のチェックリストをまとめておく。

• セルフホスト要件があるか（SaaS禁止ならAIO Sandbox一択）
• ブラウザ自動化とコード実行を同時に必要とするか
• MCPクライアントとの接続を想定しているか
• Docker Compose / Kubernetesでの運用体制があるか
• shm_size 2GB以上を確保できるホストか
• 成果物の永続化ボリュームを用意できるか

これらを満たすなら、AIO Sandboxはエージェント開発環境の有力な第一候補となる。まずはローカルで docker run 1コマンドを試し、SDKから基本操作を確認してから本番構成に進むのが定石だ。

参照ソース

• agent-infra/sandbox GitHub リポジトリ
• AIO Sandbox 公式ドキュメント
• AIO Sandbox API リファレンス
• 関連論文（arXiv）