環境変数

Current code が明示的に読む変数だけがサポート対象です。NEKO_ prefix を優先し、一部 network helper は bare name も互換用に受け付けます。

変数	既定値	Service
NEKO_MAIN_SERVER_PORT	48911	Main Web/API
NEKO_MEMORY_SERVER_PORT	48912	Memory
NEKO_MONITOR_SERVER_PORT	48913	Monitor
NEKO_COMMENTER_SERVER_PORT	48914	Commenter
NEKO_TOOL_SERVER_PORT	48915	Agent/Tool
NEKO_USER_PLUGIN_SERVER_PORT	48916	User-plugin host

Optional Monitor service

Preferred variable	Default	Description
NEKO_MONITOR_HOST	0.0.0.0	Monitor の bind address（互換用に MONITOR_HOST も使用可能）。IPv6 は角括弧の有無どちらでも可。:: は IPv6 のみを listen します
NEKO_MONITOR_TOKEN	empty	静的モデル asset を除く全 Monitor HTTP/WebSocket route 用の optional フルアクセス token。Main server が書き込む /sync* も含みます（MONITOR_TOKEN も使用可能）
NEKO_MONITOR_VIEWER_TOKEN	empty	Viewer ページ、API、/ws、/subtitle_ws 用の optional 読み取り専用 token。/sync* には使えません。NEKO_MONITOR_TOKEN 設定時のみ有効（MONITOR_VIEWER_TOKEN も使用可能）

Token が空の場合は旧クライアント互換のため認証なしです。既定の open listener は信頼できる LAN だけで使い、local-only では host を 127.0.0.1 に設定してください。Token をログや source control に含めないでください。Main server は NEKO_MONITOR_HOST にそのまま接続し（wildcard は同じ family の loopback に変換: 0.0.0.0 → 127.0.0.1、:: → [::1]）、token を自動で送ります。

Token を有効にした場合、native client は Authorization: Bearer <token>（または X-Monitor-Token）を送ります。Browser では viewer を一度 http://<host>:<port>/<name>?token=<token> で開きます。Monitor は address bar から token を除く redirect を返し、HttpOnly の neko_monitor_session_<port> cookie を設定します。Viewer リンクの共有には NEKO_MONITOR_VIEWER_TOKEN を使ってください。NEKO_MONITOR_TOKEN を含むリンクは /sync* への書き込み権限も与えるため、受け取った人は全 viewer に字幕やチャットを注入できます。

Cookie には token ではなく 30 日有効の署名付き session が入り、viewer route のみ許可します（/sync* は不可）。この cookie を使う WebSocket handshake は同じ host と port からのみ受け付け、どちらかの token を変更すると無効になります。Browser は同じ host の全 port に cookie を送るため、他のローカルサービス（main server、plugin host）も受け取り、期限まで Monitor の viewer データ読み取りに再利用できます。全 session を取り消すには token を変更してください。TLS を終端する reverse proxy の背後では元の Host header を保持し（nginx: proxy_set_header Host $http_host;。保持しないとリアルタイム WebSocket が拒否されます）、proxy を uvicorn の FORWARDED_ALLOW_IPS（既定 127.0.0.1）に含めると cookie に Secure が付きます。

Runtime では NEKO_INSTANCE_ID、NEKO_AUTOSTART_CSRF_TOKEN、NEKO_AUTOSTART_ALLOWED_ORIGINS、NEKO_BEHIND_PROXY、NEKO_LOG_LEVEL、NEKO_MERGED を使います。Storage root は NEKO_STORAGE_SELECTED_ROOT と NEKO_STORAGE_ANCHOR_ROOT です。

Local vectors は NEKO_VECTORS_ENABLED と NEKO_VECTORS_QUANTIZATION（auto/int8/fp32）を受け付けます。Boolean は 1/true/yes/on と 0/false/no/off です。利用可能 RAM の下限は現在、固定の実行時定数 VECTORS_MIN_RAM_GB = 4.0 であり、環境変数による上書きはありません。

プロセスモデルと単一インスタンス

launcher は foreground プロセスです。daemon 化して親から離脱することはなく、所有者 プロセスが消えた時点でサービス構成全体を片付けます。また OS のファイルロックで唯一性 を自己証明し、その隣に権威ある runtime record（pid、instance id、確定したポート）を 書き出します。

変数	デフォルト	説明
NEKO_OWNER_PID	本プロセスの親	親プロセス死亡ガードが監視する pid。所有者が直接の親でない場合に設定します（例：storage 移行の世代交代で生成された次の launcher。その spawn 元は意図的に終了します）。 launcher.json を読んでランタイムを識別する所有者はこれを設定してください: レコードの owner_pid になり、照合すべきはこちらです。parent_pid と照合しないでください — Windows の開発実行では Popen(sys.executable) が実インタプリタを起動し直すシムを起動するため、parent_pid は所有者ではなくシムを指します (CI で実測。macOS と Linux は直接一致し、凍結ビルドにシムはありません)。
NEKO_OWNER_RELAUNCH	未設定	1 は「所有者が自分で runtime を再起動する」という宣言です。storage 移行の再起動は自分で後継を spawn せず、クリーンに終了して再起動を待ちます。 Windows では設定を強く推奨します: 未設定だと launcher が自分で次世代を起動し、後継を巻き添えにしないため旧 Job の管理を解除する必要があり、cleanup を生き延びたプロセス (プラグイン、MCP、Chromium) が回収されません。
NEKO_PARENT_DEATH_GUARD	1	0 でガードを完全に無効化します。対象を再 parent 化する debugger / profiler 用のみ。無効化した runtime は所有者より長生きし得ます。
NEKO_LAUNCHER_RESTART_HANDOFF	未設定	前世代の launcher が後継に設定します。後継は「別インスタンスが動作中」と結論せず、単一インスタンスロックの解放を待ちます。手動設定は想定していません。
NEKO_RUNTIME_STATE_DIR	ユーザーごとの runtime ディレクトリ	launcher.lock と launcher.json の場所を上書きします。既定は Windows %LOCALAPPDATA%\N.E.K.O.runtime、macOS ~/Library/Application Support/N.E.K.O.runtime、Linux ~/.local/state/N.E.K.O/runtime。Windows と macOS では cloudsave 管理の N.E.K.O データルートと同じ階層に置き、データルートの原子的な置換が保持中の単一インスタンスロックに阻止されたり、そのロックの inode を unlink したりしないようにしています。Linux のパスは意図的に XDG_RUNTIME_DIR を無視します: この変数はデスクトップセッションには存在しますが cron・素の SSH・su・system unit・多くのコンテナには無く、これを基にロックパスを決めると同一ユーザーが別々のロックを 2 つ保持し、ランタイムが 2 つ同時に起動し得ます。上書き値はそのまま使われ、ユーザーごとの接尾辞は付かないため、必ず単一ユーザー専用のディレクトリを指す必要があります。POSIX ではディレクトリ自体は検証されます: 他の uid が所有するディレクトリ (またはそこへの symlink) は EPERM で拒否され、group/world ビットの付いたディレクトリはその場で 0700 に chmod されます。Windows ではどちらも行いません。拒否は unknown として扱われ、launcher は警告付きで起動しますが一意性の証明はありません。共有ディレクトリを指すと単一インスタンスの証明が壊れます: Windows では 2 ユーザーが同一ロックを奪い合い、POSIX では 2 人目が 1 人目のロックファイルを開けず、一意性の証明なしで起動します。

ランタイム構成

変数	デフォルト	説明
NEKO_MERGED	ソース環境: 0、凍結パッケージ: 1	1 は main、memory、agent の HTTP サービスを同一プロセスで実行しつつ各契約を維持します。0 は 3 サービスを別プロセスで実行します。既存バックエンドが不完全または混在している場合は再利用せず、merged が選択されていても分離したフォールバックポートで 3 プロセスを起動します。

開発、サービスごとの監視、agent 障害の分離が必要な場合はマルチプロセスを使用してください。 パッケージ版は NEKO_MERGED=0 ですぐにロールバックできます。 NEKO_MERGED 自体が受け付ける値は 1/true/yes と 0/false/no です。

プラグインの自動起動の並列数

変数	デフォルト	説明
NEKO_PLUGIN_AUTOSTART_CONCURRENCY	min(8, max(2, (os.cpu_count() or 4) // 2))	依存関係を宣言していないプラグインを、自動起動の各バッチで同時に開始する最大数。1–64 の整数を指定できます。1 ではプラグインごとに操作ロックを取得して順次起動します。依存関係のないプラグインが先に起動するため、従来の全体のトポロジカル順序や adapter の優先順位には戻りません。

既定値は 2–8 です。論理 CPU 数を取得できない場合は 4 個として計算し、並列数は 2 になります。 依存関係を宣言したプラグインは、独立したプラグインの起動がすべて完了してから、 従来のトポロジカル順序で逐次起動します。各並列バッチの終了後に操作ロックを解放し、 待機中のプラグイン管理リクエストを処理できるようにします。この設定はサーバーの 自動起動だけに適用されます。無効または未承認のプラグインの自動起動を有効にしたり、 手動で起動・停止したときの保存済み設定を変更したりするものではありません。

N.E.K.O を起動する前に環境変数を設定し、変更後はランタイムを再起動してください。 整数に変換できない値は既定値に戻ります。変換できても 1–64 の範囲外の場合は 設定の検証に失敗します。順次起動に戻す例:

$env:NEKO_PLUGIN_AUTOSTART_CONCURRENCY = "1"
uv run python launcher.py

NEKO_PLUGIN_AUTOSTART_CONCURRENCY=1 uv run python launcher.py

Docker entrypoint は initial /app/config/core_config.json の生成時だけ NEKO_CORE_API_KEY、NEKO_CORE_API、NEKO_ASSIST_API、一部 NEKO_ASSIST_API_KEY_*、NEKO_MCP_TOKEN を読みます。NEKO_FORCE_ENV_UPDATE は再生成要求です。旧 docker/env.template の未接続 model 変数には依存しないでください。