コンテンツにスキップ

ヘッドレスサーバーを実行

常時稼働するマシンで cc_server を実行し、デスクトップ、ブラウザー、またはスマートフォンから接続します。サーバーは純粋な Dart のネイティブバイナリで、Flutter エンジンを必要としないため、macOS、Linux、Windows 上でヘッドレスに動作します。サーバーがデータベースを所有し、 エージェントを実行し、すべての外部 API 呼び出しを行います。クライアントは描画するだけです。

各リリースでは、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 のビルド フックは、そこでステージングされたものをそのままバンドルに再出力するため、このステップを飛ばすと ビルドがそのまま失敗するか、後述の回避手段を使った場合は、起動前チェックで不足している ライブラリ名が示されて起動が拒否されるバイナリができあがります。

ターミナルウィンドウ
cd apps/cc_server
fvm 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.dev

cc_server pair で発行された資格情報も、アプリで発行されたものと同じく 30 日で失効します。同じデバイスに新しいものを発行するには pair を再度実行してください。CLI で発行したデバイスは、使い終わったら 設定 → 自分 → 自分のデバイス から取り消してください。

ペアリングキーは必須の Noise ハンドシェイクを認証します。各セッションは新しいトラフィック キーを導出し、サーバーの署名済み識別情報を検証します。ペアリングキーは保護し、信頼できる 情報源(信頼できる QR コードを含む)から入手してください。新しいサーバーのフィンガープリントは、 別の信頼できるチャネルを通すか、既知のピンと照合して検証してください。変更されたピンを 黙って受け入れないでください。サーバーの識別情報を意図的に置き換える場合は、信頼できる チャネルで再ペアリングします。TLS だけでは、このエンドツーエンドの識別情報ピンを確立できません。

ループバックの場合 — 既定であり、同じマシン上のクライアントにはこれだけで十分です:

ターミナルウィンドウ
./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 で決めます。サンドボックスポリシーを設定を参照してください。

クライアントを、ステップ 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 リクエストは拒否されます。リソースには 認証済みの暗号化セッションが必要です。

サーバー所有者として最初に接続したクライアントは、このサーバーが 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 は誰に対してもそれだけの情報を開示するという意味でもあります。