環境変数
このページでは、現在の Libre WebUI のバックエンド、フロントエンド、メンテナンススクリプトが 読み取る、運用担当者向けの対応環境変数を一覧にします。テスト専用の内部 canary は意図的に 省略しています。
バックエンドサーバー
| 変数 | デフォルト | 用途 |
|---|---|---|
NODE_ENV | development | ランタイムモード |
PORT | 開発時は 3001、本番では 8080 | バックエンドの HTTP ポート |
TRUST_PROXY | 未設定（Helm では 0） | クライアントアドレスの導出に使用する、信頼済みリバースプロキシの正確なホップ数 |
CORS_ORIGIN | ローカル開発のオリジン | 許可するブラウザーオリジンのカンマ区切り一覧 |
SERVE_FRONTEND | 未設定 | true の場合、ビルド済みフロントエンドをバックエンドから提供 |
DOCKER_ENV | 未設定 | true の場合、Docker 向け動作を有効化 |
DATA_DIR | backend/data、パッケージ版 CLI では ~/.libre-webui | 永続データディレクトリ |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight、パッケージ版 CLI ではユーザーキャッシュ | 起動時の非公開 DB/WAL 検査コピー用スクラッチ領域。データベースと WAL の合計サイズを確保 |
PLUGIN_UPLOAD_TEMP_DIR | OS の一時ディレクトリ配下の libre-webui-plugin-uploads | 処理中のプラグインアップロード用スクラッチ領域 |
PLUGINS_DIR | $DATA_DIR/plugins | インストール済み／カスタマイズ済みプラグイン用の書き込み可能なディレクトリ |
BASE_URL | http://localhost:3001 | OAuth コールバックのデフォルトに使用するベース URL |
LOG_LEVEL | info（テストでは warn） | バックエンドのログレベル |
LOG_FORMAT | text | json でタイムスタンプ、相関 ID、秘匿化を含む構造化 1 行ログへ切り替え |
OTEL_EXPORTER_OTLP_ENDPOINT | 未設定 | オプトインの OTLP/HTTP JSON テレメトリー出力。未設定ならプロセス外へテレメトリーを送信しない |
OTEL_EXPORTER_OTLP_HEADERS | 未設定 | OTLP コレクターへ送る key=value ヘッダーのカンマ区切り一覧（認証など） |
OTEL_SERVICE_NAME | libre-webui | 出力テレメトリーの service.name リソース属性 |
WEBUI_HOST | ループバック。Docker では 0.0.0.0 | HTTP 待ち受けアドレス |
OPEN_BROWSER | フロントエンド提供時は true | false にするとブラウザーの自動起動を抑止 |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | チャット単位の全文書コンテキストモードのトークン上限（1000-2000000） |
GALLERY_RETENTION_DAYS | 未設定（永久保持） | スケジューラーのスイープで指定日数より古いギャラリーメディアを削除 |
RECOVERY_DRILL_INTERVAL_HOURS | 未設定（ドリル無効） | N 時間ごとに検証済みリカバリードリルを自動実行（solo プロファイル） |
RECOVERY_DRILL_HISTORY | 60 | 保持するリカバリードリル履歴の件数 |
ソースから起動する場合、相対 DATA_DIR、PLUGINS_DIR、
PLATFORM_PREFLIGHT_TMP_DIR の値は、シェルの作業ディレクトリに関係なくバックエンド
ディレクトリを基準にします。そのため DATA_DIR が未設定の場合、または新しいソース用の例で
DATA_DIR=./data としている場合、ルートとバックエンドのワークスペースコマンドはいずれも
backend/data を使用します。互換性のため、DATA_DIR=./backend/data を含む既存の
ソース設定では引き続き backend/backend/data が選ばれます。停止した状態で意図的に
バックアップと移行を行う場合だけ変更してください。未設定のソースプロファイルでも、
backend/backend/data が唯一の既存永続ストアであれば、それを使い続けます。両方の
場所に状態があり、パスが選ばれていない場合は、推測、コピー、マージを行わず、起動を
フェイルクローズします。
一方、npx、グローバル npm、対話型 Homebrew ランチャーは、データを
~/.libre-webui 配下に保持します。そのランチャーへ明示的な相対 DATA_DIR を渡すと、
呼び出し元の作業ディレクトリを基準に解決され、バックエンドの起動前に絶対パスへ変換されます。
明示的に設定した相対 PLUGINS_DIR にも同じ規則が適用されます。未設定の場合、書き込み可能な
プラグインは $DATA_DIR/plugins 配下に残ります。検査用スクラッチのデフォルトは、データ
ディレクトリ外のユーザーが書き込めるキャッシュです。macOS では
~/Library/Caches/libre-webui、Windows では %LOCALAPPDATA%\libre-webui、
その他のシステムでは ${XDG_CACHE_HOME:-~/.cache}/libre-webui を使用します。
Homebrew サービスは同じホームデータディレクトリに固定され、スクラッチには Homebrew の
var/libre-webui/preflight を使用します。そのキャッシュにデータベースと WAL が収まらない場合は、
PLATFORM_PREFLIGHT_TMP_DIR を明示的に設定してください。同梱の Docker および Helm
デプロイでは、別々のマウントに支えられた絶対パス /app/backend/data と
/app/backend/temp/preflight を使用します。
プラットフォーム基盤
デフォルトの solo プロファイルでは SQLite、ローカルの暗号化 blob、暗号化した組み込み
ベクトル、ローカル連携、組み込みの永続ワーカーを使用します。team プロファイルでは
PostgreSQL、非公開の S3 互換 blob、PGVector、Redis、外部ワーカーを使用します。
team 設定はフェイルクローズです。共有依存関係はすべて一緒に選択する必要があります。
| 変数 | デフォルト | 用途 |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | 整合した solo または team プロファイルを選択 |
DATABASE_BACKEND | sqlite | sqlite または postgres を選択 |
DATABASE_URL | 未設定 | PostgreSQL 接続 URL。postgres では必須 |
DATABASE_SSL_MODE | verify-full | PostgreSQL TLS ポリシー：disable、require、またはホスト名を検証する verify-full |
POSTGRES_MIGRATION_MODE | apply | リーダーロック下で互換移行を実行。読み取り専用のスキーマ確認には validate を使用 |
POSTGRES_POOL_MAX | 10 | アプリケーションまたはワーカープロセスごとの PostgreSQL 最大接続数（1-100） |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | PostgreSQL 接続タイムアウト（1-60000 ms） |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | PostgreSQL アイドル接続タイムアウト（1-600000 ms） |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | PostgreSQL ステートメントタイムアウト（1-600000 ms） |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | 移行リーダーロックを待機する時間（1-600000 ms） |
BLOB_STORE_BACKEND | local | 暗号化 local ストレージまたは非公開 s3 を選択 |
VECTOR_STORE_BACKEND | SQLite では embedded | 暗号化 embedded ベクトルまたは pgvector を選択 |
COORDINATION_BACKEND | solo では local、team では redis | プロセスローカルまたは Redis の連携を選択 |
REDIS_URL | 未設定 | redis: または rediss: URL。Redis 連携では必須 |
REDIS_KEY_PREFIX | libre | Libre 連携キー用の 1-64 文字の名前空間 |
REDIS_CONNECT_TIMEOUT_MS | 5000 | 初回 Redis 接続タイムアウト。上限 60 秒 |
JOB_WORKER_MODE | solo では embedded、team では external | ハンドラーをアプリ内または独立した共有ワーカーで実行 |
RESOURCE_LEASE_TTL_MS | 30000 | 永続ジョブのリソース所有権に使う連携リース TTL（5000-300000。範囲外では起動失敗） |
JOB_WORKER_CONCURRENCY | 4 | 1 ワーカーが同時に実行できる永続ジョブ数（1-32） |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | 毎時のスイープで削除されるまでチャットストリームのチャンクイベントを保持する時間 |
PLATFORM_EVENT_RETENTION_DAYS | 30 | 毎時のスイープで削除されるまで永続イベントを保持する日数 |
PLATFORM_JOB_RETENTION_DAYS | 30 | 毎時のスイープで削除されるまで、完了した非ライフサイクルジョブを保持する日数 |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | 未設定 | 1 で次回起動時の従来暗号文の詳細スキャンを省略（退避手段。通常はスキーマ世代ごとにキャッシュ） |
STORAGE_ENCRYPTION_KEYS | 未設定 | シークレット JSON キーマップ。現在は ENCRYPTION_KEY と一致する legacy を含める必要あり |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | 未設定 | 新しいローカル blob および組み込みベクトルの書き込みに使うキー ID |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | 所有者ごとの永続的な平文 blob 最大バイト数（正の安全な整数） |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | 放棄されたストリーミング割り当て予約の有効期間（60000 ms 以上） |
S3_BUCKET | 未設定 | 非公開の S3 互換バケット。s3 では必須 |
S3_REGION | 未設定 | S3 リージョン。s3 では必須 |
S3_ENDPOINT | プロバイダーのデフォルト | MinIO または別の互換サービス用の任意の絶対 HTTP(S) エンドポイント |
S3_ACCESS_KEY_ID | SDK 資格情報チェーン | 任意の明示的 S3 アクセスキー |
S3_SECRET_ACCESS_KEY | SDK 資格情報チェーン | 明示的なアクセスキーを設定した場合は必須 |
S3_SESSION_TOKEN | 未設定 | 明示的な S3 資格情報に付随する任意のトークン |
S3_FORCE_PATH_STYLE | false | パス形式のアドレス指定が必要なサービスでは true に設定 |
S3_BLOB_PREFIX | libre/blobs | Libre が所有する不透明なバケットキープレフィックス |
バージョン付きストレージキーマップがない場合、ストレージアダプターは既存の ENCRYPTION_KEY を
キー ID legacy として使用します。それもない場合は、既存の ${DATA_DIR}/.encryption_key を
生成または変更せずに読み取ります。明示的な設定と永続ファイルは一致している必要があります。従来の
キーが存在する状態でバージョン付きマップを導入する場合、すべてのオブジェクトとベクトルを
書き直すか再ラップし、検証が完了するまで、そのキーを正確な ID legacy で維持してください。
競合、安全でないファイル権限、シンボリックリンク、設定済みキーの欠落はフェイルクローズします。
Redis は連携用であり、正規の永続ストレージではありません。Redis だけを選択しても、SQLite、
ローカルファイル、その他のプロセス所有状態がレプリカ間で安全になるわけではありません。team モードでは、
HTTP レート制限、Chat/WebSocket 接続、STT/TTS/音声プロバイダー処理、アーカイブのインポート、
Work ターミナルセッションが Redis ベースの共有受付を使用します。容量はプロセスごとではなく、
すべてのレプリカにまたがって適用されます。受付または更新可能な許可の失敗は 503 を返すか、
処理中の操作を中止します。Libre が独立したローカルカウンターへフォールバックすることはありません。
プラットフォーム基盤を参照してください。
同梱の team Compose プロファイルと Helm チャートは、上記の team プラットフォームセレクターと
調整値をすべてアプリケーションと外部ワーカーの両方へ転送します。Helm チャートでは、シークレットでない
セレクターを env に置き、接続情報またはキーマテリアルには secrets.redisUrl、
secrets.databaseUrl、secrets.storageEncryptionKeys を設定します。PostgreSQL プール上限は
プロセス単位です。データベースには少なくとも
(replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX 接続に加え、運用と移行用の
余裕を確保してください。管理対象またはリモートの PostgreSQL では
DATABASE_SSL_MODE=verify-full を維持します。同梱の team Compose プロファイルだけは、
データベースリスナーが非公開プロジェクトネットワークに隔離されているため disable を選びます。
team Helm では 1 つの安定した secrets.jwtSecret も必要で、同じ Secret キーをすべての
アプリケーション Pod とワーカー Pod にマウントします。JWT シークレットを省略すると、プロセスごとに
署名マテリアルが生成されてしまいます。S3 は不透明なキーと暗号文を受け取ります。バケット URL と
プロバイダー URL はアプリケーションメタデータに保存されません。
統合された solo および team アーカイブでは、PostgreSQL プールとタイムアウト設定、Redis 接続 タイムアウト、両方の blob 割り当て設定、プラットフォームセレクター、S3 アドレス設定を、署名および 暗号化された保護設定内に保持します。そのためクリーンリストアでは、対応するデプロイの再作成に必要な 運用値を、平文のアーカイブメタデータへ置かずに公開できます。
同梱の team Compose および Helm のアプリケーション／外部ワーカーの組は、解決済みの同じ
OLLAMA_BASE_URL、OLLAMA_TIMEOUT、OLLAMA_LONG_OPERATION_TIMEOUT、
OLLAMA_MAX_CONTEXT を受け取ります。文書埋め込み、永続 Chat、Work 実行のプロバイダー呼び出しは
ワーカーで行われるため、これらの値をプロセス間で変えてはいけません。どちらのサーバーエントリーポイントも、
ローカル状態の作成または共有状態への接続前に、3 つの数値を完全な 10 進正整数として解析します。
300000ms のような部分値、指数／16 進表記、範囲外の値、標準タイムアウト未満の長時間操作
タイムアウトでは起動に失敗します。
Helm は TRUST_PROXY を 0 から 16 までの正確な整数ホップ数に制限し、HTTP
アプリケーション Pod だけへ転送します。直接通信ではデフォルトの 0 を維持します。Ingress／
ロードバランサーチェーンには、正確で固定された数を設定してください。ランタイムの無制限な true 形式は
決して使用しないでください。数が誤っていると、共有レート制限でクライアントがプロキシアドレスにまとめられるか、
クライアントが指定できるアドレスを信頼することになります。
PostgreSQL のスキーマ互換性は完全なバージョン一致です。Helm のアプリとワーカーは Recreate を
使用します。team のアップグレード前に古い Pod をすべてドレインして終了し、その後 1 つの新しい
プロセスにアドバイザリーリーダーロック下で移行させてください。異なるバイナリバージョンを混在させたり、
スキーマをゼロダウンタイムで展開できるとみなしたりしないでください。ロールバックでは、対応する古い
バイナリを起動する前に、検証済みのアップグレード前 team アーカイブをクリーンな PostgreSQL/S3
ターゲットへ復元します。
有効な team アプリケーションには worker.replicaCount >= 1 が必要です。Helm は readiness の
失敗を待たず、永続ワーカーのない稼働アプリを拒否します。完全に停止するには、アプリケーションとワーカーの
数を両方ゼロにします。アプリがゼロでワーカー数が正の場合は、意図的なワーカー専用のドレインまたは
リカバリーモードとなり、ウェブ通信を提供せずにキュー済みジョブを処理し続けます。
プライベートバックアップヘルパー
次の変数は deploy/private/libre-webui-backup を設定し、アプリケーションプロセスではなく
メンテナンススクリプトによって読み取られます。
| 変数 | デフォルト | 用途 |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | 非公開 Compose ファイルを含むディレクトリ |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | バックアップセットとロックファイル用の保護ディレクトリ |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | 完了済みバックアップセットを削除するまでの日数 |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | 検査するデプロイ済みアプリケーションコンテナ |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | 非公開のアーカイブ暗号化／署名キーディレクトリ |
LIBRE_WEBUI_RESTORE_IMAGE | リストア時に必須 | 確認済みで不変の Libre イメージ ID またはダイジェスト |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | /etc/libre-webui/restored 配下のボリューム別パス | 復元した設定用の新しいディレクトリ |
systemd ユニットは、任意の root 所有ファイル /etc/libre-webui/backup.env から
バックアップの上書きを読み込みます。モードを 0600 に設定してください。スタックディレクトリ、
保持期間、コンテナ名、バックアップキーディレクトリは、このファイルで直接設定できます。ユニットの
ファイルシステムサンドボックスが書き込みを許可するのは、デフォルトのバックアップディレクトリ配下だけです。
カスタム LIBRE_WEBUI_BACKUP_DIR を使う場合は、事前に作成したその正確なディレクトリを、
ReadWritePaths= サービスドロップインにも追加する必要があります。
プライベートなリモートデプロイを参照してください。
認証とセキュリティ
| 変数 | デフォルト | 用途 |
|---|---|---|
ENABLE_SIGNUP | false | 最初のローカル管理者作成後の登録を許可 |
JWT_SECRET | 開発環境では生成／フォールバック | JWT 署名シークレット。本番環境では明示的に設定 |
JWT_EXPIRES_IN | 7d | セッショントークンの有効期間 |
ENCRYPTION_KEY | 自動生成 | 暗号化された値に使用する 64 文字の 16 進キー |
DEBUG_ENCRYPTION | 未設定 | 設定時に暗号化のデバッグ出力をログへ記録 |
TURNSTILE_SITE_KEY | 未設定 | ログインとサインアップ用の Cloudflare Turnstile サイトキー |
TURNSTILE_SECRET_KEY | 未設定 | バックエンド検証用の Cloudflare Turnstile シークレットキー |
TURNSTILE_EXPECTED_HOSTNAME | BASE_URL のホスト名 | Cloudflare の検証応答で必須とするホスト名 |
MFA_REQUIRED_MODE | 未設定（管理者切り替え、optional） | 2 要素認証ポリシーを optional または required に固定 |
WEBAUTHN_RP_ID | リクエストのホスト名 | 複数ホスト名の背後でパスキーに使う固定 relying-party ID |
VAPID_PUBLIC_KEY | 生成して暗号化保存 | Web Push VAPID 公開キーを固定（base64url P-256 point） |
VAPID_PRIVATE_KEY | 生成して暗号化保存 | Web Push VAPID 秘密キーを固定（base64url scalar） |
VAPID_SUBJECT | mailto:admin@localhost | 署名済み Web Push 認可内の連絡先 claim |
Turnstile は、両方の Turnstile キーが存在する場合だけ有効になります。
ENABLE_SIGNUP=false でも、空のデータベースでは最初のローカル管理者の作成が許可され、その後は
追加のローカルアカウントと OAuth アカウントがブロックされます。リモートから到達できる bootstrap
ルートは、初回起動前に外部の ID 境界で保護してください。
発行されるすべての JWT はサーバー側セッション（sid claim）に結び付けられるため、サインアウト、
または設定 → セッションでのセッション無効化は、すべてのレプリカでトークンを直ちに無効にし、
有効な WebSocket 接続を閉じます。セキュリティ監査の保持期間は設定できます。
| 変数 | デフォルト | 用途 |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | セキュリティ監査イベントログの行を保持する日数 |
汎用 OIDC シングルサインオン
discovery document を提供する OpenID Connect プロバイダーは、ログインに使用できます。
このフローでは PKCE（S256）、CSRF state、署名を確認した ID token 内で検証される nonce を
使用します。ID は安定した sub claim でリンクされます。
| 変数 | デフォルト | 用途 |
|---|---|---|
OIDC_ISSUER_URL | 未設定 | issuer ベース URL。discovery は <issuer>/.well-known/openid-configuration から取得 |
OIDC_CLIENT_ID | 未設定 | プロバイダーに登録した OAuth client ID |
OIDC_CLIENT_SECRET | 未設定 | OAuth client secret |
OIDC_DISPLAY_NAME | Single Sign-On | ログインボタンに表示するラベル |
OIDC_SCOPES | openid profile email | 要求する scope |
OIDC_CALLBACK_URL | BASE_URL + OIDC コールバックルート | プロバイダーに登録するリダイレクト URI |
OIDC_ALLOWED_EMAIL_DOMAINS | 未設定 | カンマ区切り一覧。設定すると、そのいずれかのドメインの検証済みメールアドレスが必要 |
OIDC_GROUP_CLAIM | groups | グループ名を含む ID token claim |
OIDC_ADMIN_GROUPS | 未設定 | カンマ区切り一覧。設定すると、ログインごとに claim の所属状況に従って管理者ロールを設定 |
OIDC_SYNC_GROUPS | false | true でログインごとに Libre のグループ所属をグループ claim と同期 |
OIDC が有効になるのは、issuer URL、client ID、client secret がすべて存在する場合だけです。
リンクされていないローカルアカウントで既に使用中のメールアドレスは、暗黙に統合されず拒否されます。
アカウント作成には引き続き ENABLE_SIGNUP が適用されます。
認証を弱めることなく、Chat WebSocket の受付を調整できます。
| 変数 | デフォルト | 用途 |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | 受け入れる WebSocket メッセージの最大サイズ |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | 接続ごとの WebSocket メッセージ上限 |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | アカウントごとに許可するプロバイダー生成数 |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | アカウントごとの同時認証済みソケット数 |
WEBSOCKET_TICKET_TTL_MS | 30000 | 1 回限りの Chat/Work チケット有効期間。上限 60 秒 |
ブラウザーは通常の Authorization ヘッダーを不透明なチケットへ交換し、その短時間有効な値だけを
WebSocket アップグレード URL に置きます。チケットは 1 回限りで、プロトコル、セッションに
拘束され、ハッシュとしてのみ保存されます。これにより永続セッショントークンがリバースプロキシの
リクエストターゲットログへ残ることを防ぎます。CORS_ORIGIN または BASE_URL が設定されている
場合、Origin ヘッダーを持つブラウザーアップグレードは、設定済みオリジンのいずれかと一致する
必要があります。リモートから到達可能なデプロイでは、少なくとも一方を設定してください。どちらも
設定されていない場合、ローカル開発との互換性のため Origin フィルターは寛容です。
ブラウザーの Origin 制御を利用できない Electron およびブラウザー以外のクライアント向けに、Origin の
ないアップグレードは意図的にサポートされています。その場合も、有効な 1 回限りのチケットが必要で、
同じ現在のアカウント、Work アクセス、タスクの確認を受けます。チケットを認証境界として扱い、
ブラウザー以外からのアクセスはデプロイで通常使用する TLS、ファイアウォール、リバースプロキシの
制御で制限してください。
OAuth
| 変数 | 用途 |
|---|---|
GITHUB_CLIENT_ID | GitHub OAuth client ID |
GITHUB_CLIENT_SECRET | GitHub OAuth client secret |
GITHUB_CALLBACK_URL | GitHub コールバック URL の上書き |
HUGGINGFACE_CLIENT_ID | Hugging Face OAuth client ID |
HUGGINGFACE_CLIENT_SECRET | Hugging Face OAuth client secret |
HUGGINGFACE_CALLBACK_URL | Hugging Face コールバック URL の上書き |
コールバック URL が設定されていない場合、Libre WebUI は BASE_URL からデフォルトを構築します。
Ollama
| 変数 | デフォルト | 用途 |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | Ollama API ベース URL |
OLLAMA_TIMEOUT | 300000 | 標準 Ollama リクエストタイムアウト（1,000-3,600,000 ms） |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | 長時間操作のタイムアウト（1,000-3,600,000 ms、OLLAMA_TIMEOUT 未満は不可） |
OLLAMA_MAX_CONTEXT | 32768 | 自動採用するモデルコンテキストの最大値（128-2,097,152 tokens） |
ウェブ検索
| 変数 | デフォルト | 用途 |
|---|---|---|
SEARXNG_URL | 未設定 | ウェブ検索設定用のデフォルト SearXNG エンドポイント。管理者が設定 > 検索で有効化する必要あり |
Libre Claw
| 変数 | デフォルト | 用途 |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | 任意の Libre Claw デーモン URL |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Libre Claw HTTP リクエストタイムアウト |
Work ランタイム
次の変数は、Libre WebUI バックエンドを実行するマシンまたは Kubernetes クラスター上の Work
実行を設定します。デフォルトのランタイムは Docker です。Helm チャートでは
work.enabled=true の場合に Kubernetes が選択されます。
| 変数 | デフォルト | 用途 |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Work サンドボックスで使用する固定イメージ |
WORK_DOCKER_COMMAND | docker | プロセスから利用できる Docker バックエンドの CLI 実行ファイル |
WORK_COMMAND_TIMEOUT_MS | 120000 | デフォルトタイムアウト。ツールは最大 600000 ms を要求可能 |
WORK_MAX_OUTPUT_CHARS | 50000 | 取得する stdout/stderr の上限。各ストリームに適用 |
WORK_MAX_AGENT_ROUNDS | 48 | 1 回の実行に対する、プロバイダーに依存しないモデル／ツールのラウンド上限 |
WORK_STATUS_BLURB_MODEL | 1 | 0 で、実行後にエージェントのサイドバー状態行を書く 1 回のモデルリクエストを省略 |
WORK_MEMORY_LIMIT | 2g | 各 Work コンテナに渡すメモリ上限 |
WORK_CPU_LIMIT | 2 | 各 Work コンテナに渡す CPU 上限 |
WORK_PIDS_LIMIT | 256 | 各 Work コンテナに渡すプロセス上限 |
WORK_PREVIEW_PORT | 4173 | プレビューサーバーがタスクコンテナ内で使用する必要があるポート |
WORK_PREVIEW_BIND | 127.0.0.1 | タスクのプレビューポートを公開するホストインターフェース。ネイティブ Docker Engine の Compose 構成では、到達可能な非公開のブリッジインターフェースを指定する必要があります |
WORK_DOCKER_PUBLISHED_HOST | アプリ既定値：WORK_PREVIEW_BIND と同じ。Compose 既定値：host.docker.internal | Docker が公開するプレビュー、画面、音声ポート用のバックエンド側ホスト／IP |
WORK_COMPUTER_SCREEN_PORT | 6080 | GUI 対応サンドボックス内の Work Computer 画面ブリッジ（websockify）のコンテナポート |
WORK_COMPUTER_AUDIO_PORT | 6081 | GUI 対応サンドボックス内の Work Computer 音声ブリッジ（websockify → PulseAudio monitor）のコンテナポート |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | インスタンス全体で同時に実行できるランタイム使用タスク数 |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | 1 ユーザーが同時に実行できるランタイム使用タスク数 |
WORK_MAX_TASKS_GLOBAL | 500 | インスタンス全体で永続化できる Work タスクの最大数 |
WORK_MAX_TASKS_PER_USER | 100 | 1 管理者が永続化できる Work タスクの最大数 |
WORK_NETWORK_NAME | libre-webui-work | ネットワークを使用するタスク向けの管理対象サンドボックスブリッジネットワーク |
WORK_RUN_LEASE_WAIT_MS | 60000 | レプリカ競合を報告する前に、実行がタスクの共有ランタイムリースを待つ時間（team モード） |
WORK_RUNTIME_DNS | 未設定 | ネットワークを使用するタスクへ強制する resolver IP のカンマ区切り一覧 |
WORK_DOCKER_SOCKET | DOCKER_HOST が unix:// または tcp:// ならその値、それ以外は /var/run/docker.sock | ターミナルと診断に使う Docker Engine エンドポイント |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | 1 タスクに接続できるブラウザーターミナルの同時セッション数 |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | ターミナルセッションを閉じるまでのアイドルタイムアウト |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0（無効） | この時間操作がないサンドボックスを停止（プレビューも対象） |
WORK_HOST_WORKSPACES_ENABLED | false | ボリュームの代わりにホストフォルダーをタスクで使えるようにする |
WORK_HOST_WORKSPACE_ROOTS | サーバーユーザーのホームディレクトリ | ホストワークスペースを配置できるルートの : 区切り一覧 |
WORK_RUNTIME_BACKEND | docker | サンドボックスのバックエンド：docker または kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Kubernetes サンドボックスの Pod と PVC を格納する namespace |
WORK_K8S_STORAGE_CLASS | クラスターのデフォルト | ワークスペース PVC の StorageClass |
WORK_K8S_WORKSPACE_SIZE | 5Gi | タスクごとのワークスペース PVC サイズ（実際のディスク割り当て） |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | サンドボックス Pod が Running になるまで待つ時間（pull を含む） |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | 削除したサンドボックス Pod が消えるまで待つ時間 |
AGENT_CLI_MODELS_ENABLED | 未設定（管理者切り替え、無効） | Agents 機能のオン／オフを固定。未設定ならユーザー管理の管理者切り替えに従う（デフォルト無効） |
TOOLS_ACCESS_MODE | 未設定（管理者切り替え、管理者のみ） | Chat ツールを admins または all-users に固定し、ユーザー管理の管理者切り替えをロック |
STT_ACCESS_MODE | 未設定（管理者切り替え、全ユーザー） | 音声認識を admins または all-users に固定し、ユーザー管理の管理者切り替えをロック |
TTS_ACCESS_MODE | 未設定（管理者切り替え、全ユーザー） | テキスト読み上げを admins または all-users に固定し、ユーザー管理の管理者切り替えをロック |
VOICE_MODE_ACCESS_MODE | 未設定（管理者切り替え、全ユーザー） | ハンズフリー音声モードを admins または all-users に固定し、ユーザー管理の管理者切り替えをロック |
VOICE_CLONING_ACCESS_MODE | 未設定（管理者切り替え、全ユーザー） | ボイスクローンを admins または all-users に固定し、ユーザー管理の管理者切り替えをロック |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | 未設定 | ツールサーバーと webhook ターゲットがプライベートアドレスへ解決できる正確なホスト名（カンマ区切り）。固定 |
AGENT_CLI_TIMEOUT_MS | 600000 | エージェント CLI を終了させるまでの実行時間 |
CODEX_OAUTH_MODELS_ENABLED | true | Codex（ChatGPT）プロバイダーを管理者に提供 |
CODEX_HOME | ~/.codex | Codex CLI のサインイン情報（auth.json）を読み取る場所 |
エージェント CLI バイナリと Codex OAuth 資格情報はノードローカルです。検索と実行で同じファイルシステムと
環境を参照できる solo プロセスでのみ対応しています。team モードでは永続 Chat ジョブを外部ワーカーで
実行するため、AGENT_CLI_MODELS_ENABLED=false と CODEX_OAUTH_MODELS_ENABLED=false の
両方が必要です。それ以外の値は、アプリケーションレプリカの 1 つにしか存在しない可能性があるプロバイダーを
表示せず、起動時に拒否されます。資格情報とルーティングが共有 PostgreSQL に保存されているか、すべての
アプリケーションとワーカーへ同一に転送される Ollama またはプロバイダープラグインを使用してください。
Docker バックエンドでは、ホストワークスペースによって実ディレクトリが /workspace に bind mount
されるため、タスクは独自の Docker ボリューム内で作業する代わりに、そのファイルを直接読み書きできます。
Kubernetes はホストフォルダーのワークスペースを拒否します。これは Docker サンドボックスを意図的に
弱めます。必要な場合を除き WORK_HOST_WORKSPACES_ENABLED は無効にし、
WORK_HOST_WORKSPACE_ROOTS は可能な限り狭くしてください。要求されたパスは、ルートとの照合前に
シンボリックリンクをたどって解決され、.ssh、.gnupg、.aws、.config などのフォルダーは
無条件に拒否されます。
エージェント CLI モデルでは、サーバーにインストール済みのコーディングエージェント（claude、
codex）を選択可能なチャットモデルとして公開するため、サブスクリプションのエージェントは API キーなしで
応答できます。これらは管理者にのみ表示され、CLI は Libre WebUI サーバーユーザーとして実行され、その
ユーザーのエージェント資格情報を継承します。これらのエージェントへ shell access を付与することと
同等に扱ってください。
Docker では、ネットワークを使用する Work タスクは、管理対象の WORK_NETWORK_NAME ブリッジへ
接続します。ブリッジではコンテナ間通信が無効になっているため、あるサンドボックスから別のサンドボックスや
デプロイ自身のコンテナへ到達できません。WORK_RUNTIME_DNS は、対応している Docker の egress
ポリシーフックです。名前に基づく許可／拒否リストを適用するには、フィルタリング resolver を指定します。
IPv4/IPv6 アドレスでない項目は拒否され、ログに記録されます。DNS フィルタリングは IP 直接指定の
egress を制限しません。デプロイで必要な場合は、ホストのファイアウォールルールを追加してください。
Kubernetes バックエンドでは、代わりにチャートの default-deny NetworkPolicies と
work.networkPolicy.blockedEgressCidrs の値を使用します。
Docker では、対話型ターミナルとシステム診断が Docker Engine API と直接通信します。
WORK_DOCKER_SOCKET が設定されていればそれを使用し、それ以外は DOCKER_HOST が
unix:// ソケット、またはソケットプロキシ（docker-compose.socket-proxy.yml を参照）のような
平文 HTTP tcp:// エンドポイントであればその値を使用し、それ以外は /var/run/docker.sock を
使用します。このクライアントが扱えない DOCKER_HOST（ssh://、または
DOCKER_TLS_VERIFY を設定した tcp://）では、ターミナルと Docker 診断が利用不可と報告されます。
Work の残りの部分は、それらのエンドポイントを独自に扱える Docker CLI 経由で引き続き動作します。
Kubernetes では、ターミナルが Pod exec subresource を使用し、Docker エンドポイントは使いません。
Work はバックエンド起動時にこれらの値を読み取ります。プレビューポートはタスクコンテナ内部用です。 Libre WebUI はこの値をすべてのホストインターフェースで直接公開せず、動的に割り当てた ループバックポートへ公開します。
ランタイムイメージは、確認済みのバージョンまたはダイジェストに固定してください。同時実行数や
リソース上限を増やすと、1 つ以上の自律実行が消費できるランタイム容量も増えます。
WORK_MAX_AGENT_ROUNDS は Ollama とプラグインを使用する実行へ同じように適用され、プラグイン
専用の低い上限はありません。ツール呼び出しの安全上限は
max(128, WORK_MAX_AGENT_ROUNDS × 8) です。実行がラウンド上限に達すると、Work はモデルへ
ツールなしの最終引き継ぎを要求し、生のラウンド上限エラーを返したり成功したと主張したりせず、終端の
needs_input 状態で終了します。フォローアップ実行は同じ永続ワークスペースで続行されます。
永続化するツール出力には、約 20,000 ソース文字と切り詰めマーカーという別の上限があります。
次の変数は、既に到達可能な Work ランタイムを調整します。リポジトリの単一インスタンス向け Compose デプロイではデフォルトで有効です。イメージには Docker CLI が含まれ、それらの Compose ファイルは ホストの Docker ソケットをマウントします。この接続は Compose レベルの 2 つの変数で制御します。
| 変数 | デフォルト | 用途 |
|---|---|---|
DOCKER_GID | 0 | コンテナユーザーに追加するホスト Docker ソケットのグループ ID |
DOCKER_SOCKET | /var/run/docker.sock | マウントするホスト Docker ソケットのパス |
DOCKER_GID には、コンテナ内から見えるソケットのグループを指定する必要があります。macOS ホストが
報告する値は異なります。team Compose ベースはソケットをマウントせず、
docker-compose.team.work.yml を追加するまで Docker ベースの Work を利用不可のままにします。
この本番用オーバーレイは、ソケットマウントやソケットグループではなく、同じ内部フィルタリング済み
プロキシエンドポイントをアプリケーションとワーカーの両方へ提供します。プロキシが許可するのは
ランタイムが使う Docker API セクションだけですが、コンテナ作成は引き続き Docker ホストを制御できる
資格情報です。境界を強化するには、Work 専用または rootless のデーモンを使用してください。
Helm チャートはノードのランタイムソケットを一切マウントしません。ネイティブの Pod/PVC Work
バックエンドは work.enabled=true で有効にします。
solo プロファイルは SQLite、ローカルファイル、プロセスローカル連携を使用するため、
アプリケーションレプリカ数を 0 または 1 に維持する必要があります。Helm チャートは意図的な停止用に
ゼロを受け入れますが、solo のレプリカ数を増やす設定や autoscaling は拒否します。完全な team
プロファイルでは、PostgreSQL、S3、PGVector、Redis が共有状態を所有するため、複数のアプリケーション
レプリカと外部ワーカーを使用できます。Work のサンドボックス Pod はどちらのプロファイルでも独立して
スケールします。team モードでは、外部ワーカーはアプリケーション Pod と同じ Kubernetes ランタイム
イメージ、StorageClass、work.env 上限を受け取ります。
リポジトリの Compose ファイルでは、WEBUI_BIND_ADDRESS（デフォルトは 127.0.0.1）と
WEBUI_PORT（デフォルトは 8080）も使用できます。信頼できる LAN またはホストの
リバースプロキシからポートへ到達させる必要がない限り、ループバックのデフォルトを維持してください。
プロバイダーのモデル検索
プロバイダーのモデルカタログが存在しないか古くなると、自動的に再検索されます。そのため再読み込み時には、 プロバイダーが現在提供しているモデルが反映されます。次の変数でこのサイクルを調整します。
| 変数 | デフォルト | 用途 |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000（6 h） | 保存済みカタログが次のプラグイン一覧読み取り時に更新される経過時間 |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000（10 min） | 失敗するプロバイダーを頻繁に調査しないための、試行間の最小時間 |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | 応答を返す前にプラグイン一覧リクエストが更新を待つ時間 |
期限を超えた更新も完了し、次のリクエストで提供されます。明示的なモデルを更新は常にプロバイダーへ 接続し、間隔を無視します。
プロバイダープラグインのキー
プロバイダープラグインでは、環境変数のキーをデプロイ全体のデフォルトとして使用できます。
| 変数 | プロバイダー |
|---|---|
OPENAI_API_KEY | OpenAI および OpenAI TTS |
ANTHROPIC_API_KEY | Anthropic |
GROQ_API_KEY | Groq |
GEMINI_API_KEY | Google Gemini |
MISTRAL_API_KEY | Mistral |
OPENROUTER_API_KEY | OpenRouter |
KIMI_API_KEY | Moonshot AI の Kimi Code |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | 設定されている場合の Hugging Face API |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | API キーが必要な ComfyUI デプロイ |
ユーザー単位のキーを推奨する場合は、ユーザーが UI にプロバイダー資格情報を保存することもできます。 環境変数のキーが使われるのは、シャドウされていない組み込み定義のルーティングおよび認証プロジェクションを 使用する場合だけです。インポートした定義、組み込み ID を再利用する書き込み可能な定義、管理者が保存した カスタムルートには、そのアカウントで保存した資格情報が必要です。Libre WebUI は環境変数のキーを それらのルートへ付加せず、検索および可用性チェックを通じて公開しません。信頼は、出荷する各マニフェストの コンパイル済みハッシュに基づきます。そのため、従来と組み込みのプラグインディレクトリが同じパスを共有する コンテナレイアウトも、変更済みマニフェストを組み込みとして扱わずに対応できます。
ユーザーが保存したキーは、有効なプロバイダー定義、ソース、認証コントラクト、ルーティング値に 結び付けられます。管理者が宛先を変更した後、ユーザーはキーを再保存する必要があります。アップグレード前の バインドされていないキーが受け入れられ、初回使用時にバインドされるのは、組み込みルートを使用する正確な 出荷時定義の場合だけです。
ソースから起動すると、相対 PLUGINS_DIR 値はバックエンドディレクトリを基準に解決されます。
一方、パッケージ版ランチャーは、明示的に設定された相対値を、バックエンド起動前に呼び出し元基準の
絶対パスへ変換します。互換性のため、Libre は決定的な backend/plugins ディレクトリと、以前の設定で
選択されていた従来の場所も読み取ります。それらの定義を $DATA_DIR/plugins へ移動してください。
カスタム定義が従来の場所に残っている間、リカバリーは従来のパスを外部状態として報告し、ボリュームだけの
スナップショットをブロックします。プラグインディレクトリと JSON 定義は実体のある通常エントリーでなければ
なりません。Libre はプラグインのシンボリックリンクをたどりません。
フロントエンド
| 変数 | デフォルト | 用途 |
|---|---|---|
VITE_API_BASE_URL | 同一オリジンの開発プロキシまたは本番 API | フロントエンド API のベース URL |
VITE_WS_BASE_URL | API URL から推測 | Chat と Work ソケット用の絶対 ws:/wss: ベース |
VITE_APP_VERSION | Vite 設定が注入するパッケージバージョン | 表示するアプリのバージョン |
VITE_DEMO_MODE | false | true の場合、デモモードの mock を有効化 |
VITE_API_TIMEOUT | 300000 | フロントエンド API のタイムアウト（ミリ秒） |
VITE_BACKEND_URL | http://localhost:3001 | 一部の認証ヘルパーコンポーネントで使用 |
VITE_DEBUG_VERBOSE | 未設定 | 開発環境で詳細なフロントエンドデバッグログを有効化 |
VITE_LOG_LEVEL | 未設定 | フロントエンドのログレベルを上書き |
ELECTRON_BUILD | 未設定 | true の場合、Electron 固有の Vite 動作を有効化 |
VITE_WS_BASE_URL は、Chat と Work ターミナルの両方ですべての WebSocket フォールバックを
上書きします。リバースプロキシのパスプレフィックスを含められますが、資格情報、クエリ、フラグメントのない
絶対 ws: または wss: URL でなければなりません。未設定の場合、Electron の file:
クライアントは ws://localhost:3001 を使用します。ブラウザークライアントは、
VITE_API_BASE_URL、次にブラウザーのオリジンからベースを導出します。Vite は
開発オリジンをポート 3001 のバックエンドにプロキシします。
メンテナンススクリプト
| 変数 | 用途 |
|---|---|
CHANGELOG_AI | 0 で AI 支援の changelog 下書きを無効化 |
CHANGELOG_AI_MODEL | release/changelog 生成用の Ollama モデル |
CHANGELOG_AI_TIMEOUT_MS | AI changelog 生成のタイムアウト（ミリ秒） |
例：
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
本番環境の例
NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768
TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example