メインコンテンツへスキップ
自宅ラボのサーバーはローカルネットワーク内では問題なくモデルを提供している。しかし同じネットワーク外にいるチームメンバーやアプリからのアクセスを可能にするには困難が伴う。特にISP側のCGNATによりポートフォワーディングが不可能な場合はなおさらだ。tokios-connectorをランタイムの隣で実行すれば、https://api.tokios.comという認証付きエンドポイントが生成される。招待した者なら誰でもこのエンドポイントを呼び出せるが、ポート開放やルーター設定の変更、サーバーへの直接アクセス権付与は一切不要だ。

自宅ラボ環境におけるアクセス性の問題

自宅ラボ用GPUサーバーは通常ヘッドレス状態でクローゼットやラック内に設置され、LAN内の利用者向けにOllamaやvLLM、llama.cppが稼働している。だがそれをLAN外へ公開するにはいくつかの障壁が存在する。
  • 外部に転送可能なパブリックIPが存在しない。 ISPがキャリアグレードNAT(CGNAT)を適用している場合、ポートフォワーディング用の固有な外部アドレスそのものが存在しない。なぜこれが自分で修正できないルーター設定なのかは、CGNAT環境下でローカルLLMを公開する方法を参照されたい。
  • たとえ可能でも外部公開したくない。 ランタイムを0.0.0.0にバインドしポートを開放すれば、GPUサーバーはインターネット上で認証なしのサービスとなってしまう。該当ポートを知った者なら誰でもリクエストを送信できる。
  • アクセス権を共有すれば全機能が共有される。 チームメンバーにTailscaleノードや直接バインドされたポートを渡せば、その者やその端末上の全アプリケーションが自分と同等のアクセス権を得ることになる。個人ごとにキーを設定することもできず、一人のアクセスを制限しようとすると他全員の利用も阻害されてしまう。
Tokiosは既存のランタイムの上に機能するコネクター層であり、OllamaやvLLM、llama.cppを置き換えるものではない。

サーバー上で設定を行う

1

サーバー上でランタイムを実行する

通常通りにモデルサーバーを起動してください。例えば次のようにします:
あるいは
サーバーをデフォルトのループバックアドレスで待ち受け状態にしておきます。コネクターを追加する前に、サーバーが独自のOpenAI互換 /v1 APIに応答することを確認してください。
2

ペアリングコードを取得してコネクタをペアリングします

まずdashboardで Setup タブを開き、Start pairing を選択すると、TKS-XXXX-XXXX 形式の一度だけ使えるペアリングコード(約15分間有効)が発行されます。サーバー上で次を実行してください:
Linux
既に tokios-connectorがインストール済みですか?その場合はコードを直接渡してください:
ダッシュボードに戻り、デバイスを approve してください。Setup タブまたは Connectors タブで操作できます。承認されると、コネクターのトークン(ct-tok-…)がトンネル経由で配信されます。画面に表示されたり、ファイルに貼り付けたりすることはありません。
3

コネクターをアップストリームモデルIDに向けます

コネクターのアップストリームは、サーバー上にあるランタイム自身のOpenAI互換APIであり、外部に公開するポートではありません。デフォルトのポートは次の通りです:Ollama 11434、llama.cpp 8080、vLLM 8000、LM Studio 1234。いずれも末尾に /v1 を付けます。Ollamaの場合は、OpenAI互換の /v1 APIを指定してください。ネイティブの /api ではありません。インバウンドのファイアウォールルールは不要です。コネクターは外向きの接続のみを行います。
4

各モデルごとにデプロイを登録します

次に Models タブで、各アップストリームモデルID(例:llama3.1)を、チームが使用する公開デプロイ名(例:homelab-llama)に紐付けます。クライアントはすべてのリクエストの model フィールドにこのデプロイ名を送信し、アップストリームIDは送信しません。
5

チームメンバーごとにスコープ付きのAPIキーを作成します

続いて Keys タブで、チームメイトやアプリごとに Create key をクリックします。チームメイトが意図したモデルにのみアクセスできるよう、各キーを特定のデプロイ名パターン(カンマ区切りのグロブ、すべての場合は *)にスコープします。キーは sk-tok-… 形式のBearerトークンで、作成時に一度だけ表示されます。ページを離れる前にコピーしてください。

複数のモデルを同時に提供する方法

複数のモデルを同一のサーバーで実行する場合や、Ollama、llama.cpp、vLLMに同時にトラフィックを分散する場合は、単一アップストリームのペアリングフローではなくコネクター設定ファイルを使用してください。tokios-connector.json では、Routes と Upstreams を Connector セクションの下に定義します。バックエンドごとに Upstream をひとつずつ用意し、それぞれに独自の BaseUrl(/v1 を含む)を設定し、--config でファイルを渡します。同じエンドポイントの背後で生成されたデプロイを登録・切り替える方法については、モデルルーティングを参照してください。

どこからでも利用可能

常に model フィールドには登録済みの deployment 名を指定し、アップストリームモデルIDは指定しません。詳しくは Claude Codeの使用 を参照してください。claude --model homelab-llama で自宅ラボサーバーを呼び出せます。

なぜチーム全体で一つのエンドポイントで良いのか

  • サーバー側に受信用ポートは一切存在しません。 コネクターは送信接続のみ行うため、チームメイトはVPNピアやSSHトンネル、あるいは開放された 0.0.0.0 ポートすら必要とせずにサーバーにアクセスできます。CGNAT環境下でも同様です。
  • 特定のチームメイトのAPIキーのみ無効化しても他者に影響はない。 各ユーザーはそれぞれ固有の sk-tok-… キーを持つため、Keysタブで該当者のキーを無効化または削除すれば即座にその人物のアクセスが停止し、他の全ユーザーのキーは引き続き有効なままです。
  • クライアント側の設定変更なしにモデルを切り替え可能。 デプロイ名を別のアップストリームモデルやバックエンドに紐付け直すだけで、homelab-llamaを利用している全チームメイトやスクリプトがそのまま正常に動作し続けます。

次のステップ

クイックスタート

手順に従うだけで、コネクター、デプロイ、APIキーをすぐに利用可能な状態にできます。

CGNATの背後で動作するLLM

住宅用ISPではなぜポートフォワーディングが機能しないのか、そしてコネクターがそれをどう回避するのか。

コネクター設定の参照ガイド

一台のサーバーから複数のモデルを tokios-connector.json で提供します。

モデルのルーティング処理

一つのエンドポイントの背後で複数のデプロイを登録・切り替える手順