DeskVNCServer - ガイド

Mac で標準的な VNC サーバーを動かし、QuickRemote から画面・クリップボード・ファイル・さらには IME まで共有 — クラウドリレーを介さず、すべてローカルネットワーク上で完結します。

はじめに

1. パスワードを設定する

設定（下部ツールバーの歯車アイコン）を開き、VNC password を入力します。標準的な VNC クライアントは RFB DES チャレンジを使用し、ASCII 互換の先頭 8 バイトしか有効になりません — 8 文字以内のパスワードを選んでください。

短いパスワードについて: これは DeskVNCServer ではなく RFB プロトコル自体の制限です。より強固な認証が必要な場合は、サーバーをプライベートネットワークに限定するか、QREX フロー（PIN ペアリング後の Bearer トークン）を利用して VNC password を無効化してください。

2. サーバーを起動する

メインウィンドウで Start をクリックします。ステータスインジケーターが Running に切り替わります。
4 つのリスナーが同時に立ち上がります: VNC 5900、QREX control 5911、QREX media 4010、File API 8766。
Copy Info をクリックすると、ホスト、ポート、現在の PIN を含む 1 行の情報をクリップボードへコピーできます。

3. クライアントを接続する

標準的な VNC ビューア（macOS Screen Sharing、RealVNC、TightVNC、モバイル VNC アプリ）の場合:

ビューアを開き、アドレスとして vnc://<your-mac-ip>:5900 を入力します
手順 1 で設定した VNC password を入力します
すぐに Mac を操作できます — キーボード、マウス、コピー&ペーストを RFB 越しに利用可能

QuickRemote アプリの場合:

スマートフォンまたはタブレットで QuickRemote を開き、Add Mac を選択します
DeskVNCServer に表示される 6 桁のペアリング PIN を入力します（QuickRemote のビルドが対応していれば QR コードをスキャンしても構いません）
QuickRemote が返却された Bearer トークンを保存し、拡張機能 — IME、オーディオ、クリップボード同期、ファイル転送 — が解放されます

インターフェース概要

ステータス行

要素	説明
サーバーラベル	このパネルを識別します。
ステータスバッジ	リスナーが稼働中は Running、それ以外は Stopped。

アクションボタン

Start — 4 つすべてのリスナーを起動します。
Stop — すべてのリスナーを閉じ、アクティブなセッションを切断します。
Copy Info — 短い接続情報（ホスト、VNC ポート、コントロールポート、PIN）をクリップボードへコピーし、クライアントへ簡単に共有できます。

接続パネル

バインドホスト、ポート、現在の Server ID、有効なペアリング PIN を表示します。設定が変更されると自動で更新されます。

QuickRemote API パネル

サーバーが話すプロトコルのクイックリファレンスです。サポートする RFB バージョン、QREX エンドポイントの形、IME コマンドセットを一覧表示し、QuickRemote（または独自クライアント）が利用可能な機能を把握できます。

プロトコルとポート

サービス	デフォルトポート	プロトコル	利用クライアント
VNC / RFB	TCP 5900	RFB 3.8 / 3.7 / 3.3	任意の標準 VNC クライアント
QREX control	TCP 5911	HTTP JSON RPC + WebSocket	QuickRemote およびその他の QREX クライアント
QREX media	UDP 4010	QuickRemote 互換パケット	IME メッセージ、オーディオストリーミング
File API	TCP 8766	QuickRemote 互換 HTTP	ファイルの閲覧と転送

認証

VNC クライアント — RFB DES パスワード（設定したパスワードのうち ASCII 互換の先頭 8 バイト）。
QREX クライアント — POST /qr/v1/pair での初回 6 桁 PIN 交換により Bearer トークンが返されます。以降の QREX HTTP 呼び出しと WebSocket フレームには必ず Authorization: Bearer <token> を含める必要があります。
VNC password が空の場合、サーバーは標準の RFB no-auth モードを通知します。信頼できる LAN セグメントでのみ利用してください。

QREX エンドポイントのクイックリファレンス

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

設定

設定	デフォルト	説明
Bind host	0.0.0.0	待ち受けるインターフェース。ローカルホスト限定にするには `127.0.0.1` を指定します。
VNC port	5900	標準 RFB リスナー用の TCP ポート。
QREX control port	5911	HTTP + WebSocket QREX 通信用の TCP ポート。
QREX media UDP port	4010	IME とオーディオのサイドチャネルパケット用の UDP ポート。
QuickRemote file API port	8766	ファイル閲覧・転送 API 用の TCP ポート。
VNC password	(空)	ASCII 互換の最大 8 バイト。空の場合、VNC チャネルは no-auth となります。
QREX bearer token	(生成)	ペアリング時に発行される有効なトークン。再ペアリングまたはこの欄を編集して再生成します。
Pairing PIN	(生成)	ペアリング時に QuickRemote へ提示する 6 桁の PIN。再生成すると更新されます。
Stable server ID	(生成)	QuickRemote がこの Mac を識別するための長期的な識別子。
Start server automatically	Off	アプリ起動時にリスナーを自動で立ち上げます。
Allow remote keyboard and mouse	On	オフにするとセッションが閲覧のみになります。
Enable IME bridge	On	QREX クライアントが macOS の入力メソッドを照会・制御できるようにします。
Enable audio API	Off	QREX media UDP 経由で Opus オーディオストリーミングを許可します。CPU 節約のためデフォルトはオフ。
Enable clipboard sync	On	Mac とリモートクライアントの間でクリップボードの内容をミラーリングします。
Enable file transfer	On	QuickRemote によるファイル一覧と読み取りを許可します。変更機能も有効化しない限り読み取り専用です。
Enable file mutations	Off	アップロード、リネーム、削除を許可します。デフォルトはオフ — 信頼できるクライアントに限定して有効化してください。
Max frame width	1440	画面キャプチャ幅の上限。値を下げると帯域を節約できます。
Max frame height	900	画面キャプチャ高さの上限。
Frame rate	12	クライアントへ送信するフレームレートの目標値。

クライアント例

macOS Screen Sharing

Finder → 移動 → サーバへ接続
vnc://<your-mac-ip>:5900 を入力
VNC password を入力

cURL — capabilities を取得する

curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — ペアリングして IME bridge を呼び出す

# 1. Exchange the PIN for a Bearer token
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Commit text via the IME bridge
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

ヒント

遅い Wi-Fi 回線や VPN 経由で接続する場合は、フレームレートと最大フレームサイズを下げてください。
すべてのデバイスを 1 度だけペアリングします。初回の PIN 交換後、Bearer トークンは再起動後も保持されるため、QuickRemote は静かに再接続します。
チャットやメールで接続情報を送る手早い方法として Copy Info を利用してください — クライアントが必要とする情報がすべて含まれます。
アップロードが本当に必要でなければ Enable file mutations はオフのままにしてください。スクリーンショット、ノート、ダウンロードの閲覧であれば読み取り専用モードで十分です。
使用していないときは Audio API を無効化してください。アイドル状態のコーデックでもエンコード経路で僅かに CPU を消費します。

トラブルシューティング

サーバーが起動しない

別の VNC サーバー（例: macOS Screen Sharing）が既にポート 5900 を使用している可能性があります。System Settings → General → Sharing から停止するか、DeskVNCServer の設定でポートを変更してください。
ポート 5911 / 4010 / 8766 はすべて空いている必要があります。lsof -i :5911 などで確認してください。

VNC クライアントの認証に失敗する

パスワードが ASCII 互換で 8 バイト以下であることを確認してください。マルチバイト文字や長い文字列は RFB DES 認証によって暗黙的に切り捨てられます。
意図的にパスワード無しで使う場合は、欄を空のままにし、VNC no-auth に対応するビューアで接続してください。

QuickRemote がペアリングできない

スマートフォンまたはタブレットが Mac と同じ Wi-Fi に接続されているか確認してください。
接続パネルを開いて PIN を再確認してください。PIN は設定から再生成できます。
macOS のファイアウォール設定を確認してください — QREX ポートへの着信接続が許可されている必要があります。

リモート操作の反応が遅い

設定でフレームレートと最大フレームサイズを下げてください。
使用していない機能（オーディオ、クリップボード、IME）を無効化して CPU を解放してください。

ファイルが転送できない

Enable file transfer がオンになっているか確認してください。読み取り専用の一覧は Enable file mutations なしでも動作します。
アップロードが失敗する場合は Enable file mutations も有効にしてください。それ以外の場合、File API は読み取り要求にのみ応答します。

プライバシー

すべてのセッションはクライアントと Mac の間で直接実行されます。クラウドリレー、テレメトリ、アナリティクスはありません。
VNC password、QREX Bearer トークン、ペアリング PIN、Stable Server ID はローカルのアプリ設定にのみ保存されます。
ファイル変更機能はデフォルトでオフです。明示的に書き込み権限を付与するまで、リモートクライアントは読み取りしかできません。
いつでも任意の拡張機能（オーディオ、クリップボード、ファイル転送、IME、リモート入力）を無効化することで、その機能を即座に取り消せます。
サーバーを Mac の中だけに留めたい場合は、バインドホストを 127.0.0.1 に設定してください。