メインコンテンツへ移動
AIチュートリアル

Agentboxをデプロイし、ブラウザからClaude CodeまたはCodexを実行する方法

このチュートリアルでは、Agentboxのインストール、Claude CodeまたはCodexアカウントの接続、永続的なDockerワークスペースの作成、コーディング作業の完了、変更内容の確認、使用状況の監視について説明します。さらに、ソースからのビルド、安全なリモートアクセス、プライベートネットワークトンネル、バックアップ、重要な運用上の制限についても解説します。

約22分で読了
Agentboxをデプロイし、ブラウザからClaude CodeまたはCodexを実行する方法

Agentboxとは？

Agentboxは、ブラウザからClaude CodeとCodex CLIを実行するためのセルフホスト環境です。AIチャット、ターミナル、プロジェクトファイル、Gitレビュー、アカウント管理、使用状況の追跡を、独自サーバー上でホストされる永続的なワークスペースに統合します。

サーバーは、TypeScriptフロントエンドを組み込んだ単一のGoバイナリとして配布されます。アプリケーションの状態とチャット履歴はSQLiteに保存し、Dockerコンテナを使用してコーディング用ワークスペースを分離します。永続ディレクトリにより、コンテナのライフサイクルとは独立して、プロジェクトファイル、ホーム設定、共有リソースが保持されます。

Agentboxは、あるデバイスでコーディング作業を開始し、環境を再構築せずに別のデバイスで再開したい場合に特に便利です。タスク指向の作業にはストリーミング対応のWebチャットを使用したり、ブラウザターミナルを開いて、元のClaude CodeまたはCodex CLIを直接操作したりできます。

主な機能

  • 永続的なワークスペース：プロジェクトファイル、ホーム設定、共有ファイル、チャット履歴がサーバー上に保持されます。
  • 2つのエージェントインターフェース：ブラウザチャットと、元のコマンドラインツールを切り替えて使用できます。
  • 統合された成果物作成ワークフロー：プロジェクトをアップロードまたはクローンし、タスクを割り当て、ファイルを確認し、Gitの差分をレビューして、結果をコミットまたはダウンロードできます。
  • 一元管理されたアカウントプール：管理者は、ClaudeおよびCodexのOAuthサブスクリプション、APIキー、リレーエンドポイント、アクセススコープ、送信プロキシを設定できます。
  • 使用状況とコストの記録：ユーザー、モデル、期間で使用状況を絞り込み、トークン数、料金情報源、レイテンシ、記録されたコストを確認できます。
  • 再利用可能なリソース：各ユーザーには共有ディレクトリが割り当てられ、すべてのワークスペースで/sharedとしてマウントされます。ホームテンプレート、Claudeスキル、MCP設定にも対応しています。
  • 任意のプライベートネットワークアクセス：abox-linkクライアントを使用すると、明示的に許可したリポジトリ、データベース、サービスをクラウドホストのワークスペースに公開できます。
  • レスポンシブインターフェース：コンソールはディープリンク、ライトテーマとダークテーマ、モバイルレイアウトに対応しています。

アーキテクチャを理解する

ブラウザはHTTPまたはHTTPS、およびWebSocket接続を介してAgentboxサーバーに接続します。サーバーはローカルDocker APIを通じてワークスペースコンテナを制御し、アプリケーションの記録をSQLiteに保存します。各ワークスペースには専用のコンテナと永続ディレクトリがあります。

1つのワークスペースに複数のチャットスレッドを含めることができますが、そのワークスペースで同時に実行できるWebチャットのターンは1つだけです。主な永続保存場所は/workspace、/home/agent、/sharedです。コンテナの置き換え後も保持する必要があるファイルは、これらの場所のいずれかに保存してください。

重要：永続ファイルは、プロセスが永続することを意味しません。ターミナルのネットワークが中断した後に再接続するとtmuxセッションを復元できますが、コンテナを停止または再構築すると、実行中のプロセスは終了します。

前提条件

最も簡単なインストール方法は、systemdを備えたLinuxサーバーを対象としています。リリースパッケージはLinux x86_64およびarm64に対応しています。

  • Ubuntu 22.04以降、またはDebian 12以降では、不足している依存関係とDockerを自動的にインストールできます。
  • その他のLinuxディストリビューションでは、Python 3.9以降、Git、curl、CA証明書、タイムゾーンデータ、ローカルDocker Engineが必要です。
  • 最初のワークスペースイメージのビルドでは、コンテナレジストリ、Debianパッケージリポジトリ、npmにアクセスする必要があります。
  • リモートアクセスには、SSH転送またはリバースプロキシを使用しない限り、TCPポート8180をサーバーのファイアウォールまたはセキュリティグループで許可する必要があります。

ビルド済みのインストールでは、サーバーにGoやNode.jsをインストールする必要はありません。

リリースインストーラーでAgentboxをインストールする

1. インストーラーを実行する

Linuxサーバーに接続し、次のコマンドを実行します。

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

インストーラーは、デフォルトで最新の安定版を選択します。READMEでは、現在の安定版としてv0.1.5が示されています。このバージョンに固定するには、次を実行します。

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --version v0.1.5

インストールプロセスでは、リリースパッケージを検証し、ツールのバージョンを固定してワークスペースイメージをビルドし、設定を作成し、ランダムな管理者パスワードを生成して、agentbox.serviceを起動します。初回のイメージビルドには数分かかる場合があります。

2. コンソールを開く

インストールが完了したら、ターミナルに表示された管理者パスワードを控えてください。次のアドレスのプレースホルダーをサーバーアドレスに置き換えて開きます。

http://YOUR_SERVER_IP:8180

ユーザー名boxadminと生成されたパスワードでサインインします。Agentboxを継続的に一般公開する前に、HTTPSを設定してください。

3. リバースプロキシにAgentboxを限定する

Agentboxがローカル接続のみを受け付けるようにするには、インストール時にlistenオプションを追加します。

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --listen 127.0.0.1:8180

その後、WebSocketに対応したHTTPSリバースプロキシをサービスの前段に配置できます。リリース版のインストールでは、設定が/etc/agentboxに、アプリケーションデータが/var/lib/agentboxに保存されます。

ClaudeまたはCodexアカウントを設定する

サインイン後、システム設定 → アカウントプールを開きます。現在の中国語インターフェースでは系统设置 → 账号池と表示されます。ClaudeまたはCodexのアカウントを追加します。

ClaudeとCodexのアカウントプール設定

Agentboxは次の接続方法に対応しています。

  • Claudeサブスクリプション：「Subscription OAuth」を選択し、認証コードを貼り付けます。
  • Codexサブスクリプション：「Subscription OAuth」を選択し、完全なコールバックURLを貼り付けます。
  • APIまたはリレーアカウント：プロバイダーのエンドポイントとキーを入力します。Codexリレーは、プロバイダーが想定するプロトコルに一致している必要があります。

識別しやすいアカウント名、必要に応じて使用する送信プロキシ、アクセス範囲を設定します。アカウントは、すべてのユーザー、選択したユーザー、または管理者のみが利用できるように設定できます。管理者は設定済みのすべてのアカウントを使用できます。

ターミナルアクセス権を持つワークスペースユーザーは、コンテナ内でコマンドラインツールに渡された認証情報を読み取ることができます。そのため、共有アカウントプールは信頼できるユーザーに限定してください。アクセスを取り消すと、新しい操作と認証情報の同期は停止しますが、完全に取り消すには、影響を受けるコンテナの停止と上流の認証情報のローテーションも必要になる場合があります。

最初のワークスペースを作成する

  1. ワークスペースを作成し、わかりやすい名前を付けます。
  2. エージェントとしてClaude CodeまたはCodex CLIを選択します。
  3. ユーザーに使用権限があるアカウントを選択します。
  4. Filesからアップロードするか、Terminalでクローンしてプロジェクトをインポートします。
  5. Chatを開き、具体的なコーディングタスクを送信します。
  6. 編集されたファイルを確認し、ChangesでGitの差分をレビューします。
  7. 変更をローカルでコミットするか、プロジェクトファイルをダウンロードします。

プロジェクトファイルをアップロードして確認する

Filesインターフェースでは、プロジェクトディレクトリと共有ディレクトリのディレクトリツリー、アップロード、編集、プレビュー、アーカイブのダウンロードを利用できます。ソースビューアーには、行番号、構文ハイライト、行と列の移動、現在行のハイライト、全画面表示モードが備わっています。

プロジェクトファイル、アップロード、プレビュー、ダウンロード

Web上のファイル操作では、制限付きのディレクトリハンドルを使用し、シンボリックリンクをたどりません。アップロードは一時ディレクトリで検証され、エディターの保存にはアトミックな置換が使用されます。ただし、コンテナ内のコマンドラインツールでは、テンプレートから提供されたリンクを引き続き使用できます。

ターミナルからリポジトリをクローンする

Terminalを開き、通常のシェルコマンドを実行します。例：

cd /workspace
git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
git status

Agentboxのワークスペースイメージには、元のエージェントCLIと一般的な開発ツールが含まれています。ターミナルセッションではtmuxを使用するため、ブラウザーやネットワークが切断された後でも再接続できます。

シェルとテスト出力を表示する永続ブラウザーターミナル

Webチャットでタスクを割り当てる

Chatを開き、要求する変更、関連する制約、期待する検証内容を説明します。例：

このプロジェクトを確認し、ユーザー登録エンドポイントに入力検証を追加してください。既存のAPIレスポンス形式を維持し、無効なメールアドレスのテストを追加して、関連するテストスイートを実行してください。

Chatでは、モデルと推論 effortを選択できます。各レスポンスには、時刻、モデル、設定スナップショット、コストが記録されます。Claudeはストリーミング方式のヘッドレスターンを実行します。Codexはアプリサーバー統合を優先し、ハンドシェイクに失敗した場合は実行モードにフォールバックします。

結果をレビューして提供する

エージェントが完了したら、Changesを開いて変更されたファイルと色付きの差分を確認します。差分だけでは十分なコンテキストが得られない場合は、ファイル全体を確認してください。

Gitファイル一覧と色付きの変更レビュー

Webからのコミットはローカルで行われ、リモートリポジトリへ自動的にプッシュされません。また、Gitフックや署名も実行されません。フックや署名付きコミットが必要な場合は、ターミナルを使用してください。

Agentboxには、リポジトリ接続、クローン、フェッチ、ファストフォワードプル、プレビュー付きプッシュ、ブランチ操作、GitHubまたはGitLabのプルリクエストとマージリクエストの作成に対応したGit管理機能もあります。リポジトリ接続には、HTTPSトークンまたはSSH秘密鍵を使用できます。

ソースからビルドして実行する

Agentboxを変更したり、プロジェクトに貢献したりする場合は、ソースワークフローを使用します。ドキュメントに記載されたビルド環境では、Dockerを搭載したLinux、Go 1.26.6または互換性のある自動ツールチェーン、Git、Python 3、curl、iproute2、OpenSSLを使用します。Node.js 22とnpmは、メインのTypeScriptコンソールを編集する場合にのみ必要です。

1. クローンしてビルドする

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox

go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh

イメージをビルドするユーザーには、Dockerへのアクセス権が必要です。起動時には、サーバーがマウントされたディレクトリの所有者を1000:1000にも設定する必要があります。付属のsystemdサービスはrootとして実行されます。

2. 設定を作成する

cp config.example.json config.json
openssl rand -hex 24

生成されたランダム値をauth_tokenにコピーします。初回テストでは、accountsとproxiesを空のままにし、後でWeb UIから実際のアカウントを追加します。

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

起動前にプレースホルダーを置き換えてください。置き換えない場合、設定の検証で拒否されます。

3. サーバーを起動する

sudo ./agentbox -config config.json

localhostのみで待ち受けるサーバーの場合は、コンピューターからSSHトンネルを作成します。

ssh -N -L 8180:127.0.0.1:8180 user@your-server

ローカルで http://127.0.0.1:8180 を開き、boxadmin と設定済みの auth_token でサインインします。管理者アカウントを作成すると、そのパスワードは SQLite に保存されます。後から auth_token を変更しても、このパスワードはリセットされません。

4. systemd サービスをインストールする

フォアグラウンドプロセスを停止した後、リポジトリからサービスをインストールしてデプロイします。

sudo ./deploy/install.sh
sudo ./deploy/deploy.sh

最初のスクリプトはサービスとタイマーをインストールします。2 番目のスクリプトはバイナリをビルドして置き換え、サービスを再起動し、ヘルスチェックを実行します。

使用状況とコストを監視する

Usage ページにはモデルの利用状況が記録され、ユーザー、モデル、時間で管理者が絞り込めます。各レコードにはトークン使用量、コストの内訳、レイテンシが含まれます。一般ユーザーは自分のレコードを確認でき、管理者は全ユーザーのレコードを確認できます。

トークン、料金、コスト、レイテンシのフィルターを備えた使用状況レコード

料金カタログでは、models.dev のソースプリセットまたはカスタム HTTPS ソースを使用できます。料金を更新しても過去のスナップショットは保持され、カスタム料金は保護されたままです。Web ターンには、ターン開始時に固定された料金表が適用されます。

クレジット上限はリアルタイムの厳格な上限ではありません。Web ターンは完了後に精算されるため、残高を使い切ったターンでは超過する可能性があります。後から取り込まれたターミナル使用量は記録されますが、クレジットは差し引かれません。

高度なヒント

ワークスペース間で共有リソースを使用する

各ユーザーの共有ディレクトリは、そのユーザーのすべてのワークスペースで /shared にマウントされます。再利用するスクリプト、参照ファイル、成果物は各プロジェクトにコピーせず、そこに保存してください。Agentbox はシステム用およびユーザーごとのホームテンプレートにも対応しています。

abox-link でプライベートサービスに接続する

オプションの abox-link クライアントを使用すると、クラウドワークスペースから、コンピューターまたは別のプライベートマシンで利用可能な許可リスト登録済みサービスに接続できます。ローカルパネル経由で実行することも、--server を指定してコマンドラインのサーバーモードで実行することもできます。

プライベートネットワークトンネルの状態と許可リスト登録済みサービス

許可リストは狭く設定し、ワークスペースに必要なリポジトリ、データベース、サービスだけを公開してください。Agentbox には、クライアントとワークスペースの接続準備状況が表示されます。通常のブラウザー利用に abox-link は必要ありません。

コンテナ容量を計画する

各ワークスペースコンテナのデフォルト設定は、メモリ 2048 MiB、2 CPU、512 プロセスです。同時に実行するワークスペース数の見込みに応じてサーバーの容量を決めてください。管理者は、コンテナの全体およびユーザーごとの上限、予約ディスク容量も設定できます。

正しいデータをバックアップする

システムのデフォルトバックアップには、データベース、設定、アカウント認証情報、テンプレートレイヤーが含まれますが、ワークスペースデータは含まれません。ユーザーファイルと履歴も取得する必要がある場合は、agentbox backup --full を使用してください。完全バックアップを作成するには、先にサービスと関連コンテナを停止する必要があります。backup-verify でアーカイブを検証し、restore --to で新しいディレクトリに復元できます。

セキュリティ境界を理解する

エージェントはワークスペースコンテナ内でコードを実行できます。デフォルトの権限モードは bypassPermissions です。コンテナはリソース制限と no-new-privileges が適用された非 root ユーザーとして実行されますが、Agentbox サーバー自体は Docker にアクセスできます。そのため、デプロイと管理は信頼できる運用担当者が行う必要があります。

オプションのリモートブラウザーを慎重に使用する

Agentbox では、永続的なログイン状態、タブ、フルスクリーン、画質調整、クリップボード対応、ダウンロード機能を備えた完全なデスクトップブラウザーをワークスペース内で提供できます。管理者はオプションの agentbox-agent:browser イメージをビルドして選択する必要があります。Web サイトの認証は、Claude または Codex CLI の認証とは別に管理されます。

覚えておくべき運用上の制限

  • 特定の data_dir を使用できる Agentbox プロセスは 1 つだけです。
  • 現在の本番アーキテクチャは、1 台のマシン、1 つのサーバープロセス、ローカル Docker デーモンで構成されます。
  • デプロイと再起動の際、接続中のクライアントは一時的に切断されます。
  • リモート Git の状態を更新してもフェッチは実行されません。ahead と behind の値はローカルキャッシュから取得されます。
  • アカウントを無効にしても、実行中のコンテナにすでに渡された認証情報は削除されません。
  • ワークスペースコンテナを停止または再ビルドすると、そのプロセスは終了しますが、永続ファイルは残ります。
  • Git レビューでは停止中のワークスペースが起動することがあり、ターミナルアクセスと同じクレジット利用可否チェックが適用されます。

まとめ

Agentbox は、Linux サーバーを Claude Code と Codex CLI 用の永続的なブラウザベースのコーディング環境に変えます。リリースインストーラーから始め、アカウントを追加し、ワークスペースを作成して、チャットタスクから統合された Files、Terminal、Changes ビューを通じてレビュー済みコードへ進めます。本番環境で使用する場合は、HTTPS を追加し、アカウントアクセスを慎重に管理し、リソース使用量を監視し、必要に応じてワークスペースデータを含めるバックアップ計画を策定してください。

より詳しい設定と運用方法については、Agentbox リポジトリ、ドキュメントインデックス、デプロイと運用ガイドを参照してください。