ヘッドレスサーバーを実行
常時稼働するマシンで cc_server を実行し、デスクトップ、ブラウザー、またはスマートフォンから接続します。サーバーは純粋な Dart のネイティブバイナリで、Flutter
エンジンを必要としないため、macOS、Linux、Windows 上でヘッドレスに動作します。サーバーがデータベースを所有し、
エージェントを実行し、すべての外部 API 呼び出しを行います。クライアントは描画するだけです。
Docker で実行する(ビルド済みイメージ)
「Docker で実行する(ビルド済みイメージ)」というセクション各リリースでは、4 つの GHCR イメージからなるセルフホスト用スタック — バックエンド、
2 つの静的なシンクライアント、任意のペアリングリレー — に加えて、任意の
cc-connect サインインサービス(Connect サーバーを実行)と、
公開デモホスト用の別個の cc-server-demo イメージが公開されます。セルフホストでのインストールにソースのチェックアウトは
不要です。バージョンタグ(ghcr.io/samuelalev/<image>:v0.0.1-rc.1)を固定するか、latest を使い続けます。
| イメージ | 内容 | 公開ポート |
|---|---|---|
ghcr.io/samuelalev/cc-server |
バックエンド: データベース、エージェント、MCP、Webhook | -p 9030:9030 |
ghcr.io/samuelalev/cc-webapp |
Web クライアント(静的な nginx) | -p 8080:8080 |
ghcr.io/samuelalev/cc-remote |
スマートフォンコンパニオン PWA(静的な nginx) | -p 8081:8080 |
ghcr.io/samuelalev/cc-signaling-server |
暗号化された接続リレー(任意) | -p 8788:8788 |
スタック全体を Compose ファイルにしたもの:
services: server: image: ghcr.io/samuelalev/cc-server:latest ports: ["9030:9030"] volumes: ["cc_data:/data"] restart: unless-stopped web: image: ghcr.io/samuelalev/cc-webapp:latest ports: ["8080:8080"] restart: unless-stopped remote: image: ghcr.io/samuelalev/cc-remote:latest ports: ["8081:8080"] restart: unless-stopped signaling: image: ghcr.io/samuelalev/cc-signaling-server:latest ports: ["8788:8788"] restart: unless-stopped
volumes: cc_data:これをループバックの外に公開する前に知っておくべきこと:
-
cc-serverイメージはCC_SERVER_INSECURE=1を同梱しています(公開ポートの トラフィックを受け取るには0.0.0.0にバインドする必要があるためです)。信頼できる ネットワーク上で TLS を終端するリバースプロキシ — Caddy、Traefik、nginx、Cloudflare Tunnel — を使うか、証明書をマウントしてCC_SERVER_TLS_CERT/CC_SERVER_TLS_KEYを設定します (そのうえでCC_SERVER_INSECUREを解除します)。この設定が制御するのは、サーバーの 外側の HTTP/WebSocket リスナーだけです。必須のエンドツーエンド暗号化クライアント セッションを無効にすることは決してありません。TLS はログイン/ブートストラップの トラフィック、接続メタデータ、公開エンドポイント、Web クライアントの配信を引き続き 保護します。すべてはdocker run -e …または Compose のenvironment:ブロックで 上書きできます。 -
/dataが唯一の状態です。 SQLite データベース、ペアリング済みデバイスのシークレット、 ダウンロードしたモデル、ミーティングの音声はすべてこのボリュームにあります — これを バックアップしておけば、コンテナは使い捨てにできます。 -
プロバイダーのシークレットはマウントした
.envに置き、-eでは渡しません。GITHUB_APP_PRIVATE_KEY、GITHUB_CLIENT_SECRET、GOOGLE_OAUTH_CLIENT_SECRET、LINEAR_API_KEY、またはSLACK_*SECRET*がプロセス環境にあると、サーバーは起動を 拒否します。ファイルを/app/bin/.envに読み取り専用でマウントする (-v /secure/cc.env:/app/bin/.env:ro)か、アプリを設定画面で構成してください。 -
最初の接続の前に、イメージの内部からクライアントをペアリングします — ステップ 3 の コンテナ版です:
ターミナルウィンドウ docker run --rm -it -v cc_data:/data \--entrypoint /app/bin/cc_server ghcr.io/samuelalev/cc-server:latest pair -
2 つのクライアントイメージは静的な nginx ホストです。 埋め込みブラウザーエディターは、 同じアプリのオリジンと同じ暗号化接続を使います。詳しくは 後述を参照してください。 各クライアントの接続フォームに、サーバー URL、デバイス ID、ペアリングキーを入力します。 シグナリングリレーが必要とするのはポートだけです(
SIGNALING_HOST/SIGNALING_PORTは 上書き可能)。リレーはステートレスで、ペアリングキーを保持せず、あくまで フォールバックです — スマートフォンは到達可能な経路(ループバック、LAN、tailnet、 直接のwss://)があればそれを使い、どれも使えないときにだけリレーにフォールバックします。 クライアントが常にサーバーに直接到達できるなら、リレーは省略してください。ブローカーは ルーティング識別子、IP アドレス、サイズ、タイミングを見ることができ、トラフィックを 中断することもできます。クライアント/サーバー間のリソースストリームを復号することは できません。
このガイドの残りでは、サーバーをソースからビルドします。ここで扱うフラグと挙動は、 イメージの環境変数が渡すものと同じです。
前提条件
「前提条件」というセクション- Dart SDK。このリポジトリは SDK を fvm で固定しているため、すべてのコマンドの先頭に
fvmを付けます。 - このリポジトリをチェックアウト済みであること。
- ステージングスクリプトが必要とするネイティブツールチェーン — Rust/
cargo、およびmeson、ninja、pkg-config、gitと C++ コンパイラー。各ビルドスクリプトは、見つからないものとそのインストール方法を明示します。 - 到達可能なホスト: ローカルで使うならループバック、リモートクライアントから使うなら TLS 付きの LAN/公開アドレス。
ステップ 1: ネイティブライブラリをステージングする
「ステップ 1: ネイティブライブラリをステージングする」というセクションネイティブは必須です — 劣化モードはありません。何よりも先に、リポジトリの ルートからビルドします:
scripts/natives/build_natives.shこれにより rift、fff、tree-sitter とその文法、aec、lame、
ccpty、cc_watcher、cc_inference、および SAML ネイティブが
build/natives/ にビルドされます。cc_server のビルド
フックは、そこでステージングされたものをそのままバンドルに再出力するため、このステップを飛ばすと
ビルドがそのまま失敗するか、後述の回避手段を使った場合は、起動前チェックで不足している
ライブラリ名が示されて起動が拒否されるバイナリができあがります。
ステップ 2: バイナリをビルドする
「ステップ 2: バイナリをビルドする」というセクションcd apps/cc_serverfvm dart build cliバンドルには libsqlite3 とステージング済みのネイティブがバイナリと一緒に含まれます —
システムの SQLite も Flutter エンジンも不要です。実行ファイルは
./build/cli/<os_arch>/bundle/bin/cc_server に生成されます。
ステップ 3: 初回起動の前にクライアントをペアリングする
「ステップ 3: 初回起動の前にクライアントをペアリングする」というセクション新しいデータディレクトリにはペアリング済みデバイスも事前共有キーもないため、クライアントの
ペアリングキーの入力をまだ満たすことができません。pair サブコマンドで発行します。
これは global.db と secrets.json を直接書き込みます。すでにそのデータディレクトリを
提供しているサーバーは、再起動なしで新しいデバイスを認識します:
./build/cli/<os_arch>/bundle/bin/cc_server pair --data-dir ./data --port 9030クライアントの接続フォームに貼り付ける 3 つの値が出力されます:
Connect a thin client (paste into its connect form): Server ws://localhost:9030/rpc Device id web-client Pairing key <a freshly generated key>便利なフラグ: --device(既定は web-client。この id はデバイス
階層も決めます — desktop、ios、android、それ以外はすべて Web クライアント)、--label
(既定はプラットフォーム名とこのマシンのホスト名)、--host(URL に出力する
ホスト。ループバックは別のマシンから到達できないためです)、--client-url。pair を
再実行すると、そのデバイスのキーがローテーションされ、ライブセッションが切断されます。ペアリングで
ワークスペースが作成されることはありません。ワークスペースを作成できるのはサーバーオーナーだけです。オーナーのクライアントでは、オンボーディングで最初のワークスペースに名前を付けて作成します。それ以外の人は、オーナーが自分のためにワークスペースを作成するか、ワークスペース管理者が招待するまで待ちます。
--client-url を付けると、入力済みの Web
クライアントを開く、ターミナルでスキャン可能な QR も出力されます:
./build/cli/<os_arch>/bundle/bin/cc_server pair --data-dir ./data --port 9030 \ --bind any --host 192.168.1.42 --client-url https://app.usectrl.devcc_server pair で発行された資格情報も、アプリで発行されたものと同じく 30 日で失効します。同じデバイスに新しいものを発行するには pair を再度実行してください。CLI で発行したデバイスは、使い終わったら 設定 → 自分 → 自分のデバイス から取り消してください。
ペアリングキーは必須の Noise ハンドシェイクを認証します。各セッションは新しいトラフィック キーを導出し、サーバーの署名済み識別情報を検証します。ペアリングキーは保護し、信頼できる 情報源(信頼できる QR コードを含む)から入手してください。新しいサーバーのフィンガープリントは、 別の信頼できるチャネルを通すか、既知のピンと照合して検証してください。変更されたピンを 黙って受け入れないでください。サーバーの識別情報を意図的に置き換える場合は、信頼できる チャネルで再ペアリングします。TLS だけでは、このエンドツーエンドの識別情報ピンを確立できません。
ステップ 4: サーバーを起動する
「ステップ 4: サーバーを起動する」というセクションループバックの場合 — 既定であり、同じマシン上のクライアントにはこれだけで十分です:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030別のマシンから到達させたい場合は、すべてのインターフェースにバインドします。TLS なしの
非ループバックバインドは起動時に拒否されるため(Refusing to bind non-loopback address … without TLS)、証明書を指定します:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030 \ --bind any --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem \ --public-url wss://server.example:9030/rpcまたは、信頼できるプライベートネットワーク上のリバースプロキシで TLS を終端し、 その背後で平文バインドを有効にします:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030 \ --bind any --insecure --public-url wss://server.example/rpc--tls-cert と --tls-key の両方が設定されている場合、--insecure は無視されます — TLS
が常に優先されます。サーバーは外側のリスナーの平文状態を GET /healthz で insecure: true
として通知します。これは、クライアントが直接接続するかリレー経由かにかかわらず、/rpc の
Noise 暗号化を無効にするものではありません。サーバー、リレー、クライアントはまとめて
アップグレードしてください。旧来の平文 RPC クライアントは拒否され、互換性のための
フォールバックはありません。機密のリソースルート(バックアップ転送を含む)への公開
リクエストは、ループバックからでも HTTP 426 を返します。ペアリング済みクライアントは
代わりに暗号化されたトンネルを使います。
サーバーは SIGINT/SIGTERM まで動作し続け、その後クリーンにシャットダウンします。
起動時の行を読む
「起動時の行を読む」というセクション2 行で、このサーバーの設定が分かります。準備完了のバナーの隣に表示される公開状態の行は cc_server exposure: で始まり、どこまで到達できるか(bind、tls、relay、tunnel)、サーバーオーナーが記録されているか(owner)、このマシンでエージェントがどのように動くか(sandbox)を示します。
sandbox=native: すべてのエージェントの実行が OS のサンドボックスで包まれます。sandbox=off:--sandbox offを付けてサーバーを起動したため、すべてのメンバーのエージェントがこのマシン上で制限なしに動きます。sandbox=unavailable: ホストにサンドボックスのバックエンドがないため(Windows、またはbwrapとsocatがない Linux)、サーバーオーナーが責任を負うエージェントの実行だけが開始されます。それ以外の人の実行は「このサーバーにはサンドボックスがないため、ここでエージェントを実行できるのはそのオーナーだけです。」で拒否されます。
ログの前のほうにあるサンドボックスの行は、同じ内容を文章で示し、バックエンドがない場合は何をインストールすべきかを示します。他人のエージェントをサンドボックスなしで実行するかどうかは、サーバーオーナーが全員のために一度だけ、--sandbox off で決めます。サンドボックスポリシーを設定を参照してください。
ステップ 5: クライアントを接続する
「ステップ 5: クライアントを接続する」というセクションクライアントを、ステップ 3 のサーバー URL とペアリングキーに向けます:
- デスクトップアプリ: 初回起動画面でサーバーに接続をクリックします。あるいは後から設定 → サーバー → 接続とステータスでサーバーを追加します。リモートサーバーに接続を参照してください。
- Web クライアント: app.usectrl.dev(または自分でホストしている Web ビルドのコピー)を開き、サーバーに接続をクリックして、サーバー URL と、ペアリングキーを使用でデバイス ID とペアリングキーを入力します。
- スマートフォン: 稼働中のクライアントから Remote アプリをペアリングします — デバイスをペアリングを参照してください。
ブラウザーエディターのリソース
「ブラウザーエディターのリソース」というセクションエディターフロントエンドは信頼されたアプリケーションコードであり、Web アプリ自身の
オリジンで動作します。その Service Worker は、クライアントの他の部分と同じ
認証済みの暗号化セッションを通して HTTP と WebSocket のトラフィックを
ルーティングします。cc_server は各リクエストを復号し、ローカルの
code-server バックエンドに転送し、応答をクライアントへ暗号化して返します。
ファイルは引き続きサーバーが所有します。
エディターはサーバー上で、サーバー自身のユーザーとして、ターミナル、タスク、拡張機能とともに動作するため、開けるのは サーバーオーナー だけです。セッションは、それを開いたデバイスと人に属します。VS Code のワークスペースの信頼が有効な状態で開くため、VS Code はフォルダーを信頼する前に確認を求め、自動タスクはオフになっています。そのためリポジトリのタスクが開いたときに起動することはありません。それ以外の人は、アプリの組み込みエディターとファイルビューを引き続き使います。フルエディターは提供されません。
Service Worker が動作できるよう、Web クライアントを HTTPS または安全な ループバックオリジンでホストしてください。通常の Web ビルドとリリーススクリプトには 共有リソースファイルが含まれます。バンドルを手動でビルドする場合は、その後 リポジトリのルートからこれらのファイルを配置します:
node tool/stage_resource_assets.mjs build/webスマートフォン用の Web ビルドでは、apps/cc_remote/build/web に置き換えます。
これは cc_resource_bridge.js、cc_resource_worker.js、
cc_resource_ws_shim.js をアプリのバンドルにコピーします。
ネイティブのエディタートラフィックは代わりにケイパビリティで制限された ループバックファサードを使います。サーバーが起動するエディター 拡張のプライベートなループバック報告/コマンドゲートウェイを、公開プロキシ経由で 公開しないでください。機微な公開 HTTP リクエストは拒否されます。リソースには 認証済みの暗号化セッションが必要です。
ステップ 6: サインイン方法を選ぶ
「ステップ 6: サインイン方法を選ぶ」というセクションサーバー所有者として最初に接続したクライアントは、このサーバーが GitHub、Google Calendar、 Linear へのサインインをどう処理するかを尋ねられます: Control Centerのアプリを使う、 自分のアプリを使う、カスタムConnectサーバーを使う のいずれかです。ターミナルからは、 同じ選択を次のように行います:
./build/cli/<os_arch>/bundle/bin/cc_server connect status --data-dir ./data./build/cli/<os_arch>/bundle/bin/cc_server connect enable --url https://connect.example.com --data-dir ./data./build/cli/<os_arch>/bundle/bin/cc_server connect disable --data-dir ./data代わりに、サーバーの環境または .env で CC_CONNECT_URL(hosted、off、または URL)を
指定すると、選択が固定されます。自分のアプリを使う の場合は、各プロバイダーを
設定 → サーバー → シングルサインオン → プロバイダーアプリ で登録します。自分のGitHubアプリを作成
で GitHub を 1 ステップで設定できます。プロバイダーのシークレットは、エクスポートされた環境
ではなく、サーバーの .env ファイルに置きます。GitHub App を作成
と Control Center Connect を参照してください。
Connect を通じたサインインは、ブラウザーに表示されるコードで完了するため、サーバーに
公開アドレスは必要ありません。サーバー自身のアプリを通じたサインインは、ブラウザーを
サーバーの公開 URL に戻すため、--public-url には人々のブラウザーから到達できるアドレスを
設定してください。
これはサーバーの既定値です。ワークスペース管理者は、設定 → ワークスペース → 連携 で 1 つのワークスペースに別の選択を与えることができます。CC_CONNECT_URL が設定されている場合、ワークスペースは自分のアプリに切り替えることはできますが、独自の Connect には切り替えられません。詳しくは ワークスペースごとの選択 を参照してください。
このサーバーから他のサーバー向けに Connect をホストするには、CC_SERVER_CONNECT_HOST=on を
設定します。Connect サーバーを実行を参照してください。
これまでに使ったフラグは、最初のセットアップに必要なものです。完全なサーフェス — 23
組のフラグと環境変数、4 つのサブコマンド、データディレクトリの
レイアウト — は cc_server CLI リファレンスにあります。
もっとも必要になる可能性が高い 4 つ:
| フラグ | 既定値 | 意味 |
|---|---|---|
--data-dir |
OS のユーザーごとのアプリケーションデータディレクトリ | データベース、シークレット、モデル、キャッシュされたメディア |
--port |
9030 |
TCP ポート(0 = エフェメラル) |
--bind |
loopback |
loopback、または全インターフェースなら any(TLS または --insecure が必要) |
--public-url |
バインドから導出 | ペアリング済みクライアントに通知される RPC URL。プロキシ、NAT、トンネルの背後では明示的に設定してください |
既定のデータディレクトリは、macOS では ~/Library/Application Support/control-center、
Windows では %APPDATA%\control-center、それ以外では $XDG_DATA_HOME/control-center(なければ
~/.local/share/control-center)です。カレントディレクトリ相対の .cc_server が使われるのは、
ホームディレクトリもアプリデータディレクトリも解決できない場合だけです。
サーバーが提供するもの
「サーバーが提供するもの」というセクションcc_server は製品サーフェスの一部ではなく、その全体です。リポジトリ RPC のデータ経路
とサブスクリプション、同じポート上の POST /mcp と GET /sse にある MCP ツール
エンドポイント、受信 Webhook、メディアとフォントのプロキシ、シングルサインオン
のコールバック、フリートリースプロトコル、30 分間隔のサーバー側 RSS 取得、そして
ベクター検索(sqlite_vector 拡張は
プロセス全体の自動拡張として登録され、拡張が利用できない場合にのみ
全文検索にフォールバックします)です。
ディスパッチャーはステートレスです。セッションごとのワークスペースの紐づけは
ありません。ワークスペースを対象とするすべての呼び出しが自身の workspace_id を持ち、アクセスは
呼び出し元のワークスペースのメンバーシップとロールによって決まります — ペアリングキーを
保持しているかどうかでは決まりません。
ポートをループバックの外に公開する前に知っておくべき 2 つのこと(TLS だけでは、ペアリング済みクライアントのエンドツーエンド暗号化は提供されず、リソースも認可されません):
- MCP は常にトークンが必要です。 サーバーは最初の起動時に MCP トークンを作成し、すべてのリクエストは、ループバックを含めて、それを
Authorization: Bearer <token>として送らなければなりません。オフにはできません。サーバーオーナーは 設定 → サーバー → MCPサーバー で読み取りとローテーションを行います。Web ページからのリクエスト、未知のHostへのリクエスト、JSON ではないPOSTは、トークンが確認される前に拒否されます。詳しくは MCP サーバーを使う を参照してください。 GET /healthzは設計上認証を必要としません。 ワイルドカード CORS を備え、サーバーの ID、名前、アイデンティティフィンガープリント、ビルドバージョンを公開します。クライアントはサーバーをピン留めするためにフィンガープリントを必要とするため、これは意図的なものです — ただし、到達可能なcc_serverは誰に対してもそれだけの情報を開示するという意味でもあります。