Claude Agent Server: Bun E2B で Claude の WebSocket ラッパーを構築

Claude Agent SDK を WebSocket インターフェースで公開する、クリーンで実績のある方法をお探しなら、claude‑agent‑server リポジトリが最適です。このリポジトリは、三つの世界のベストを統合しています。

1. Claude Agent SDK – Claude モデルと対話する強力な API。
2. Bun – 高速実行のためにマシンコードへコンパイルされる JavaScript ランタイム。
3. E2B サンドボックス – 必要なときに起動する安全で分離された環境。

この記事では、コードのインストール、E2B サンドボックスの構築、クライアント接続、サーバー設定の微調整を通じて、終盤には ChatGPT スタイルのアシスタントをあらゆる環境で実行できるようにします。

1. リポジトリの目的

claude‑agent‑server は、二つの主要サブパッケージを持つモノリポジトリです。

主な特徴:

• E2B デプロイ – build:e2b スクリプトがリポジトリを再利用可能なサンドボック​ス テンプレートにパッケージ化します。
• ワン・トゥ・ワン WebSocket – 同時に接続できるクライアントは 1 つだけです。競合を簡単に管理できます。
• カスタムツール – /config で許可するツール、システムプロンプト、モデルを選択できます。
• ローカルテストクライアント – bun run test:local を実行して localhost:3000 でバンドルされた例をテストします。
• 拡張性 – packages/server/index.ts や message‑handler.ts を編集してエージェントの振る舞いを変更したり、新しいコマンドを追加したりできます。

2. 前提条件

Bun が初めての場合は、以下でインストールします。

curl fnm.vercel.app | bash -s -- -b "$HOME/.bun"
source "$HOME/.bun/completion.bash"

3. リポジトリのクローンと依存関係のインストール

git clone https://github.com/dzhng/claude-agent-server.git
cd claude-agent-server
bun install

リポジトリには .env.example が付属しており、必要なキーを定義しています。

cp .env.example .env

ファイルを編集して API キーを設定します。

ANTHROPIC_API_KEY=sk-ant-·····
E2B_API_KEY=e2b_your-key-here

注意： キーは秘密に保ち、実際の .env ファイルをコミットしないでください。

4. E2B サンドボック​ス テンプレートの作成

E2B はオンデマンドで分離されたサンドボックスを提供します。サーバーは claude‑agent‑server という名前のデプロイ可能テンプレートにパッケージ化されます。

bun run build:e2b

裏で起こっていることは次のとおりです。

1. ベースとなる Bun‑1.3 イメージを作成。
2. リポジトリをサンドボックスにクローン。
3. bun install で実行時依存関係をインストール。
4. サーバーが自動的にポート 3000 で起動。
5. 生成されたテンプレートが E2B ワークスペースに公開。

ビルド完了後、claude‑agent‑server というエントリが E2B テンプレート リストに表示され、必要なときに新しいサンドボックスを起動できます。

5. クライアントライブラリの使用

@dzhng/claude‑agent パッケージは、サンドボックス作成、WebSocket 接続、メッセージ処理を担う薄いラッパーです。プロジェクトにインストールします。

# 自身のプロジェクトディレクトリ内で
npm i @dzhng/claude-agent
# あるいは Bun を使用
bun add @dzhng/claude-agent

5.1. クイックスタート例

import { ClaudeAgentClient } from '@dzhng/claude-agent';

const client = new ClaudeAgentClient({
  e2bApiKey: process.env.E2B_API_KEY!,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
  template: 'claude-agent-server', // E2B テンプレート名を使用
  debug: true,
});

await client.start();

client.onMessage((msg) => {
  if (msg.type === 'sdk_message') {
    console.log('Claude:', msg.data);
  }
});

await client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'my-session',
    message: {
      role: 'user',
      content: 'Hello, Claude!',
    },
  },
});

// 使い終わったら:
await client.stop();

サンドボックスライフサイクル： クライアントは新しいサンドボックスを作成し、stop() を呼び出すまで存続させ、終了後は自動的に破棄してリソースを解放します。

5.2. ローカルサーバーへの接続

開発時にローカルサーバーでテストしたい場合、connectionUrl を指定して同じクライアントを使用できます。

const client = new ClaudeAgentClient({
  connectionUrl: 'http://localhost:3000',
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
});

これで、bun run start:server を実行してローカル Bun サーバーを起動し、コンソールでリアルタイム出力を確認できます。

6. サーバーのカスタマイズ

サーバーは軽量設計であるため、簡単に拡張できます。

6.1. コアの編集

メインエントリポイントは packages/server/index.ts です。HTTP および WebSocket ルートを設定し、設定を処理し、Claude SDK にメッセージを転送します。

6.2. メッセージハンドリングの変更

packages/server/message-handler.ts は SDK の応答を JSON メッセージに変換するロジックを含みます。必要に応じてハンドラを追加または変更してください。

6.3. 新しいツールの追加

/config コールの allowedTools 配列は、エージェントが使用できるツール（例：read_file、write_file）を制限します。カスタムツール定義を追加し、SDK 経由で公開できます。

7. ローカルでのテスト

ローカルインスタンスを起動し、バンドルされたクライアントでテストします。

# リポジトリのルートで
bun run start:server   # http://localhost:3000 で起動

別のターミナルを開き、テストクライアントを起動します。

bun run test:local

このクライアントは localhost:3000 に接続し、いくつかのテストメッセージを送信し、SDK の応答を表示します。E2B イメージを再ビルドする前に変更を確認するのに最適です。

8. カスタム E2B テンプレート名の構築

デフォルトのテンプレート名は claude-agent-server ですが、クライアントコンストラクタやビルドスクリプトを編集することで変更できます。

const client = new ClaudeAgentClient({
  template: 'my-custom-claude-template',
  ...
});

または packages/e2b-build/build.prod.ts の Template() インスタンス化を変更します。

9. セキュリティとクリーンアップ

• サンドボックスはクライアント接続が開いている間のみ存続します。stop() が呼ばれると E2B が自動的にサンドボックスを終了します。
• API キーは環境変数または /config エンドポイントを通じて渡されます。SDK は提供されたキーを尊重し、クライアントに漏らすことはありません。
• サーバーは同時に 1 つの WebSocket 接続のみを許可し、誤って過負荷になるのを防ぎます。

10. まとめと次のステップ

再利用可能な Claude Agent WebSocket ラッパーを手に入れ、サンドボックス化された隔離環境でデプロイし、TypeScript あるいは JavaScript の任意のアプリケーションに簡単に統合できます。

• ボットのデプロイ – Telegram、Discord、Slack などのボットにクライアントライブラリを使用。
• カスタムエージェントの作成 – サーバーを拡張し、ドメイン固有のツールを追加。
• スタータキットの公開 – サンドボックステンプレートを他者と共有。

さらに詳細については、常に完全に文書化された README とリポジトリ内のインラインコードコメントを参照してください。ハッピーコーディング！