サーバー設定リファレンス

このガイドでは、環境変数で変更できるサーバーの設定を一覧にします。環境変数とは、サーバーが.envという名前のテキストファイルから読み込む設定のことです。Marinaraは設定なしで動きます。設定が必要になるのは、たいていほかのデバイスから接続できるようにするとき、共有するサーバーを保護するとき、データフォルダーを移すとき、ログの詳しさを上げるとき、時間のかかる処理に長めの時間を与えるときだけです。

AIのアカウント、キャラクター、チャットのオプションは、アプリの中で設定します。AIのアカウントを追加する方法はAIプロバイダーへの接続を参照してください。

.envファイルを編集する

Marinaraは初回起動時に空の.envを作成します。各行はKEY=valueの形です。#で始まる行はコメントです。

インストールの種類.envの場所
通常のインストールプロジェクトのルートフォルダー
公式のDockerイメージまたはPodmanイメージ/app/data/.env(データと同じボリュームの中)
  1. 同じフォルダーにある.env.exampleを開きます。すべての設定とそのデフォルト値が並んでいます。
  2. 必要な行を.envにコピーします。
  3. =の後ろの値を変更して、ファイルを保存します。
PORT=8080
BASIC_AUTH_USER=alice
BASIC_AUTH_PASS=correct-horse-battery-staple

.envはデータであって、シェルスクリプトではありません。Marinaraは、値の中の$、$(...)、そのほかのシェル構文を実行しません。ランチャーの環境にすでに設定されている値は、.envの同じ設定より優先されます。

サーバーは、どの方法で起動しても.envを読み込みます。ランチャー(start.bat、start.sh、start-termux.sh)は、さらにほかのデバイスから接続できるようにHOST=0.0.0.0を設定し、サーバーの準備ができたらブラウザーを開きます。AUTO_OPEN_BROWSER=falseにすると、ブラウザーは開きません。pnpm startだけで起動した場合は、HOSTを設定しないかぎり、サーバーはこのコンピューターからの接続だけを待ち受けます。

再起動とホットリロード

Marinaraは実行中も.envを監視しています。ほとんどの設定は、再起動しなくてもほぼすぐに反映されます。変更のたびに、ログに[env-watcher]の行が出ます。監視を開始できない場合、サーバーは30秒ごとにファイルを確認し、そのことをログに出力します。

別のコンピューターから編集した場合や、コンテナーのバインドマウントの中を編集した場合などに、編集が反映されないときはMARINARA_ENV_WATCH=pollを設定してください。監視をオフにするには、MARINARA_ENV_WATCH=0を設定します。どちらも上級者向けの設定です。

次の設定は起動時にだけ読み込まれます。変更するには再起動が必要で、ログにも警告が出ます。

AUTO_UPDATE_ENABLEDはサーバーの起動前にランチャーが読み込むため、変更は次回の起動から反映され、ログに警告は出ません。

アクセス制御の設定と秘密の値(BASIC_AUTH_USER、BASIC_AUTH_PASS、IP_ALLOWLIST、ADMIN_SECRET、CSRF_TRUSTED_ORIGINS)には、再起動は必要ありません。

アクセス制御

アクセス制御は、実行中のサーバーに誰が接続できるかを決めます。手順と例についてはリモートアクセス: ログインとIP許可リストを参照してください。

ログインは.envを使わずに設定することもできます。すでにサインインしているブラウザーでSettings → Advanced → Access(設定 → 詳細設定 → アクセス)を使うか、サーバーのログに出る1回限りのセットアップコードを使います。サーバーがこのコードを出力するのは、ログインが未設定で、ループバックの外でも待ち受けているあいだだけです。ログインはDATA_DIR/.remote-login.jsonに保存されます。Marinaraのフォルダーでnode scripts/reset-login.mjsを実行すると、これを削除し、すべてのブラウザーをサインアウトします。.envのログインはこれより優先されます。ログインを変更または削除するには、現在のパスワードが必要です。ログイン用プロキシについてはログイン用プロキシ(forward auth)を参照してください。

この後で使う用語は次のとおりです。

ログインを設定していない場合、サーバーは信頼できる送信元からの接続だけを受け付けます。ループバック、IP_ALLOWLISTに登録したアドレス、Tailscale、同じホスト上のDockerのブリッジからの通信です。それ以外は、自宅のネットワークも含めて403 Forbiddenになります。そもそもほかのデバイスから接続できるようにするには、サーバーが外から届くアドレスで待ち受ける必要があります。HOST=0.0.0.0を設定してください。

変数デフォルト説明
BASIC_AUTH_USER空ログインのユーザー名。BASIC_AUTH_PASSと合わせて設定します。
BASIC_AUTH_PASS空ログインのパスワード。どちらかを空にすると、ログインはオフになります。
BASIC_AUTH_REALMMarinara EngineBasic Authの認証要求に含まれるレルム名。
IP_ALLOWLIST空常に許可するIPアドレスまたはCIDR範囲(カンマ区切り)。ループバックからの直接の接続は常に許可されます。同じコンピューター上のリバースプロキシは許可されません。
IP_ALLOWLIST_ENABLEDtruefalseにすると、リストを残したまま適用だけを止めます。
ALLOW_UNAUTHENTICATED_PRIVATE_NETWORKfalseログインを設定していないとき、プライベートネットワークからのパスワードなしの接続を許可します。インターネットプロバイダーが顧客どうしで共有する100.64.0.0/10は含まれません。信頼できる場合にだけ、TRUSTED_PRIVATE_NETWORKSに追加してください。
ALLOW_UNAUTHENTICATED_REMOTEfalseインターネットを含む任意のアドレスから、パスワードなしで接続できるようにします。推奨しません。
TRUSTED_PRIVATE_NETWORKS組み込みの範囲デフォルトのプライベートな範囲を置き換えます。残したいデフォルトの範囲も含めてください。
BYPASS_AUTH_TAILSCALE自動空の場合: このコンピューターのTailscaleアドレスへ直接接続したデバイスだけがログインを省略します。Tailscale Serve、Funnel、そのほかのプロキシを経由する場合は、引き続きログインが必要です。true: 以前の方式で、100.64.0.0/10全体をバイパスします。false: 通常のアクセス制御を使います。
BYPASS_AUTH_DOCKER自動空の場合: 検出したコンテナーのインターフェイスとそのゲートウェイだけを、ログイン、IP_ALLOWLIST、TRUSTED_AUTH_PROXYのいずれも設定されていないあいだに限って信頼します。true: 以前の構成や独自のネットワーク向けです。false: 通常のアクセス制御を使います。
REQUIRE_AUTH_FOR_DOCKER_PROXYtrueプロキシが中継するDockerの通信にも、ログインまたは許可リストを求めます。プロキシ自体がすべての訪問者にログインを求める場合にだけfalseにしてください。
REQUIRE_AUTH_FOR_LOOPBACK_PROXYtrue同じコンピューター上のプロキシやトンネルが転送したリクエストを、nginxのデフォルトのproxy_passのようなHTTP/1.0のリクエストも含めて、リモートとして扱います。プロキシ自体がすべての訪問者にログインを求める場合にだけfalseにしてください。
TRUSTED_AUTH_PROXY空すべての訪問者にログインを求めるforward authプロキシ(tinyauth、Authelia、Authentik、oauth2-proxy)のIPアドレスまたはCIDR範囲。そのリクエストは、ログインとIP_ALLOWLISTを通らずに入れます。プロキシはすべてのパスを保護する必要があり、プロキシを迂回してMarinaraに到達できてはいけません。
TRUSTED_HOSTS空Marinaraが応答する、chat.example.comのような公開ホスト名やプロキシのホスト名を追加します。IPアドレスの直接指定、localhost、.local、.home.arpa、ラベルが1つだけのLAN名は、この設定がなくても使えます。CSRF_TRUSTED_ORIGINSやCORS_ORIGINSにある名前も受け付けます。
SSL_CERT空TLS証明書のパス。SSL_KEYと合わせて設定すると、HTTPSを直接提供します。
SSL_KEY空TLSの秘密鍵のパス。
CSRF_TRUSTED_ORIGINS空変更の保存を許可するブラウザーのオリジンを追加します。公開ドメインや通常と異なるポート向けです。リテラルのnullは、Android APKの場合も含めて無視されます。

Warning: 0.0.0.0/0のような広い公開範囲をIP_ALLOWLISTに指定すると、インターネット上のクライアントがログインなしで入れてしまうことがあります。信頼できるアドレスだけを記載してください。

ストレージ

変数デフォルト説明
DATA_DIRpackages/server/dataすべてのユーザーデータを置くルートフォルダー。Dockerイメージでは/app/dataに設定されます。
FILE_STORAGE_DIRDATA_DIRの中のstorageファイルの保存先フォルダーを上書きします。
ENCRYPTION_KEY空保存するAPIキーを暗号化する鍵。
MARINARA_MAX_RESIDENT_CHATS0(無制限)、SteamOSとTermuxでは8同時にメモリー上に保持するチャットの最大数。上限を超えると、保存のたびに、未保存の変更がないチャットのうち最後に使われてから最も時間が経ったものをメモリーから外します(ディスクから削除することはありません)。無効な文字列は、プラットフォームのデフォルトに戻ります。2未満の正の値は2になります。0にすると、メモリーからの解放をオフにします。
MARINARA_EAGER_STORAGEオフ1にすると、2.4.5より前と同じように、起動時にすべてのチャットを読み込みます。大きなプロファイルではメモリーの使用量がかなり増えます。変更には再起動が必要です。

暗号化の鍵を生成し、ENCRYPTION_KEYに貼り付けます。

openssl rand -hex 32

Marinaraはデータをそのままの形のJSONファイルとして保存するため、バックアップをコピーしたり、中身を読んだりできます。各フォルダーの中身についてはMarinaraがデータを保存する場所を参照してください。

ログレベル

LOG_LEVELは、サーバーがどこまで詳しく出力するかを決めます。選んだレベルより下の内容は表示しません。

レベル表示される内容
error重大な障害だけ。
warnエラーと警告。これがデフォルトです。
info起動時のログとリクエストごとのログを追加します。
debugプロンプトとモデルの返答の全文を含むすべて。出力は非常に多くなります。
変数デフォルト説明
LOG_LEVELwarn上のレベル。
LOG_PRESETdefaultprompt-connectionsは、debugと同じプロンプトとモデルの詳細を表示しつつ、GET /api/chatsのような定型のリクエストの行を隠します。
LOG_DISABLE_REQUEST_LOGGINGfalsetrueにすると、定型のリクエストの行を隠し、レベルはそのままにします。変更には再起動が必要です。
LOG_FORMAT自動prettyは、どこでも読みやすい行で出力します。たとえばdocker logsでDebug mode(デバッグモード)のプロンプトを読むときに使います。jsonは、1行に1つのJSONオブジェクトを出力します。変更には再起動が必要です。

ターミナルでは、サーバーは読みやすい行で出力します。Dockerのログなどそれ以外の場所では、本番用のサーバーはJSONの行を出力します。Termuxのランチャーは読みやすい行を指定します。ブラウザー側のログは別の仕組みで、LOG_LEVELでは制御しません。

タイムアウト

タイムアウトとは、時間のかかる処理をサーバーが待つ上限時間のことです。Settings → Advanced → Request timeouts(設定 → 詳細設定 → リクエストのタイムアウト)を開くと、テキスト、エージェント、Gameの画像プロンプト、画像、動画、ComfyUI、埋め込みの上限時間を秒単位で変更できます。上限を長くすると、低速なローカルバックエンドで役立ちます。サービス側が設けている上限は変更できません。保存にはサーバーの管理権限が必要です。

これらの設定はすべてのプロファイルに適用され、有効な.envと同じ場所に.env.timeouts.json(または<custom-env-path>.timeouts.json)として保存されます。.envを書き換えずに、対応する環境変数より優先されます。テキスト、エージェント、Gameの画像プロンプト、埋め込みの変更は、新しいリクエストから適用されます。メディアの変更と、インストール済みのエージェントパッケージへの反映には再起動が必要です。環境変数に戻すには、そのファイルを削除して再起動します。

名前に別の単位が示されていないかぎり、値の単位はミリ秒です。値を検証するチャット、エージェント、Gameの画像プロンプトのタイムアウトに、不正な値、0、負の値、範囲外の値を指定すると、警告をログに出してデフォルト値を使います。動画の処理についてはシーン動画を参照してください。

変数デフォルト説明
CHAT_GENERATION_TIMEOUT_MS300000(5分)Conversation、Roleplay、Gameの返信で、最初のトークンまでの時間とチャンク間の間隔の上限。独自のタイムアウトを持たないバックグラウンド処理(Professor Mari、Noodleの更新、Slurpの返信)の上限時間にもなります。範囲は10000-3600000です。エージェント、メディア、埋め込み、ツールのタイムアウトは変わりません。
AGENT_CALL_TIMEOUT_MS300000(5分)ダウンロードしたエージェントも含め、エージェントのモデル呼び出し1回で、開始前または実行中に何も届かない状態が続いてよい最長時間。データを受信するとリセットされます。範囲は10000-3600000です。Illustratorには、少なくとも組み込みの30分の無通信時間が確保されます。
GAME_DYNAMIC_IMAGE_PROMPT_TIMEOUT_MS45000(45秒)Gameのシーンを画像プロンプトに変換するモデル呼び出しの、合計時間の上限。範囲は10000-3600000です。
EMBEDDING_TIMEOUT_MS300000(5分)埋め込みのリクエスト1件に許される時間。
IMAGE_GEN_TIMEOUT_MS1800000(30分)画像生成のリクエスト1件に許される時間。
IMAGE_GEN_MAX_RESPONSE_BYTES31457280(30 MiB)受け入れる画像レスポンスの最大サイズ。ローカルのComfyUIが大きなメタデータを埋め込む場合は、値を大きくしてください。
VIDEO_GEN_TIMEOUT_MS1800000(30分)ComfyUIの動画ワークフローを含む、シーン動画のリクエスト1件に許される時間。
VIDEO_GEN_MAX_RESPONSE_BYTES167772160(160 MiB)受け入れるシーン動画のダウンロードの最大サイズ。
COMFYUI_GEN_TIMEOUT2400(40分、単位は秒)キューに入った後のComfyUIの画像ワークフロー1件に許される時間。
SPRITE_GENERATION_TIMEOUT_MSIMAGE_GEN_TIMEOUT_MSAIによるスプライト生成の処理1件に許される時間。
CUSTOM_TOOL_TIMEOUT_MS60000(1分)カスタムツールの呼び出し1回に許される時間。
MAX_TOOL_ROUNDS100モデルが回答しなければならなくなるまでの、ツール呼び出しの最大ラウンド数。Gameの1ターンは最大4回、エージェントは16回、ロアブックのバックフィルは64回までで、この値のほうが小さい場合はこの値が上限になります。

特権API(ADMIN_SECRET)

バックアップ、データの消去、アップデートの適用、テーマのインストールなど、破壊的な操作や危険な操作には、通常のアクセス確認に加えて追加の秘密の値が必要です。サーバーが動いているコンピューター上のSettings → Advanced → Admin Access(設定 → 詳細設定 → 管理者アクセス)で作成するか(Admin Accessを参照)、サーバー側に長いランダムな値を設定します。

ADMIN_SECRET=replace-this-with-a-long-random-secret

サーバーが動いているコンピューター上では、これらの操作はたいてい秘密の値なしで実行できます。そのコンピューター上のプロキシやトンネルが転送したリクエストは、REQUIRE_AUTH_FOR_LOOPBACK_PROXY=falseでないかぎりリモートとして扱われます。ほかのデバイスからの直接のリクエストには、秘密の値が必要です。同じ値をSettings → Advanced → Admin Accessに貼り付けると、アプリが代わりに送信します。.envのADMIN_SECRETは、アプリで作成した秘密の値より優先されます。管理者用の秘密の値がない場合、特権操作はサーバーのコンピューター以外のすべてのデバイスから失敗し、エラーで設定するよう案内されます。インストール済みのエージェントは、ログインでサインインしたどのデバイスからでも使えますが、インストール、アップデート、削除には秘密の値が必要です。

変数デフォルト説明
ADMIN_SECRET空リモートのデバイスから特権操作を行うための秘密の値。
MARINARA_REQUIRE_ADMIN_SECRET_ON_LOOPBACKfalsetrueにすると、サーバーのコンピューター上でも秘密の値を求めます。
UPDATES_APPLY_ENABLEDfalse同じチャンネル内のアップデートを、ブラウザーのApply Update(アップデートの適用)で適用できるようにします。サーバーのコンピューター上のブラウザーからリリースチャンネルを切り替える操作は、この設定がなくても行えます。Gitからのインストールのみ対象です。
UPDATES_APPLY_DISABLED未設定チャンネルの切り替えも含め、サーバー側でのアップデートの適用をすべて拒否します。UPDATES_APPLY_ENABLEDより優先されます。開発用とe2e用のランチャーはこれを設定します。
UPDATES_ALLOW_REMOTE_APPLYfalse有効な秘密の値があれば、リモートのデバイスからアップデートを適用できるようにします。
HAPTICS_ALLOW_REMOTEfalse有効な秘密の値があれば、リモートのデバイスから触覚デバイスの操作を実行できるようにします。
CUSTOM_TOOL_SCRIPT_ENABLEDfalseカスタムのスクリプトツールをオンにします。信頼できないツールやインポートしたツールを使う場合は、オフのままにしてください。
MARI_DB_ALLOW_UNSAFE_TRANSFORMSfalseProfessor Mariのデータベース変換スクリプトを、OSのサンドボックス(macOSのSeatbelt、LinuxのBubblewrap。ある場合は使います)がないホストでも実行できるようにします。スクリプトを自分で確認した場合以外は、オフのままにしてください。
ENABLE_CUSTOM_AGENT_REPOSfalseAgent Organizerで、GitHubのエージェントリポジトリーを手動でプレビューし、同期できるようにします。カスタムエージェントのリポジトリーを参照してください。
MARINARA_OVERWORLD_GAMESfalseプレイヤーがOverworldゲーム(舞台設定キットと生成された世界)を作成し、以前の形式のゲームをOverworldゲームに変換できるようにします。オフの場合、ウィザードではClassicゲームだけを作成できます。
ENABLE_EXTERNAL_EXTENSIONSfalseサードパーティー製の拡張機能をインポートするための2つの許可のうち、1つ目です。外部拡張機能(External Extensions)を参照してください。
IMPORT_ALLOWED_ROOTS空ピッカーのトークンなしで一括インポートが読み取れるフォルダー。
PROFILE_EXPORT_JSON_LIMIT_BYTES268435456(256 MiB)サーバーが作成するJSONのプロファイルエクスポート1件の最大サイズ。

ローカルアドレスへの接続の許可

デフォルトでは、AIサービス、画像サービス、Webhookへの外向きのリクエストは、プライベートアドレスやローカルアドレスへの接続を拒否します。これにより、リクエストをだまして内部のアドレスへ向かわせるSSRF(サーバーサイドリクエストフォージェリ)を防ぎます。ループバック上のモデルサーバーはそのまま使えます。プライベートネットワーク上の別のコンピューターでセルフホストしているサービスに必要なスイッチだけをオンにしてください。

変数デフォルト説明
PROVIDER_LOCAL_URLS_ENABLEDfalseAIサービスのURLが、プライベートアドレスやLANのアドレスに接続できるようにします。Androidではデフォルトでオンです。
IMAGE_LOCAL_URLS_ENABLEDfalse画像サービスのURLが、プライベートアドレスやLANのアドレスに接続できるようにします。プライベートアドレスの結果URLは、引き続きサービスのオリジンと完全に一致する必要があります。
TTS_LOCAL_URLS_ENABLEDfalse音声合成のURLが、プライベートアドレスやLANのアドレスに接続できるようにします。
STT_LOCAL_URLS_ENABLEDfalse音声認識(Speech to text)サーバーのURLが、プライベートアドレスやLANのアドレスに接続できるようにします。同じコンピューター上のサーバーは、この設定がなくても使えます。
DEEPLX_LOCAL_URLS_ENABLEDfalseDeepLXの翻訳URLが、プライベートアドレスやLANのアドレスに接続できるようにします。
WEBHOOK_LOCAL_URLS_ENABLEDfalseカスタムツールのWebhookが、プライベートアドレスやLANのアドレスに接続できるようにします。

ローカルモデルやセルフホストモデルに接続する方法はローカルモデルやセルフホストモデルへの接続を参照してください。

機能スイッチ

失敗したプロバイダー呼び出しの再試行や、ロアブックのグループの選択を固定する動作など、サーバーのオプションの動作はSettings → Advanced → Features(設定 → 詳細設定 → 機能)にあります。すべてデフォルトでオフです。いくつかには、設定するとスイッチより優先される環境変数があります。機能スイッチを参照してください。

Marinaraのお知らせ

お知らせは、メンテナーからの短い警告です。たとえば、セキュリティ上の問題や、お使いのバージョンに必要な手動の手順を伝えます。お知らせはバナーで表示されます。

お知らせをオフにするには、MARINARA_NOTICES_ENABLED=falseを設定します。

Warning: お知らせをオフにすると、Marinaraはセキュリティ修正や必要な手順を伝えられません。GitHubのリリースを自分で確認してください。

フォークは、MARINARA_NOTICES_URLを自分のファイルに向けられます。

オプションのマルチプレイヤー

マルチプレイヤーはデフォルトでオフです。オンにすると、Conversation、Roleplay、Gameの非公開ルームを、参加人数の固定上限なしで共有できます。各ゲストは、自分の信頼できるMarinaraを使います。ゲストにAIのアカウントは不要です。ホストがAIのアカウントを用意し、共有された内容を読んで保存できます。2つの有効化条件のどちらかがオフのあいだ、Marinaraはセッション、証明書、接続相手のバックグラウンドでの確認を行いません。

  1. 参加する各Marinaraの.envにMULTIPLAYER_ENABLED=trueを設定し、再起動します。有効になるのは正確にtrueの値だけで、ホットリロードでは反映されません。
  2. Settings → Advanced → Multiplayer(設定 → 詳細設定 → マルチプレイヤー)を開き、警告を読んで設定をオンにします。これだけでは待ち受けを開始せず、ルームにも参加しません。
  3. ホストするには、モードの選択やセットアップの流れの中でCreate shared session(共有セッションを作成)またはPlay together(一緒にプレイ)を使います。セットアップ、表示名、共有するペルソナの文章を確認してください。既存のチャットから共有されるのはセットアップの選択だけで、履歴、メモ、記憶は共有されません。
  4. ホストでは、ルームのホスト名に対して有効で、ゲストが信頼する証明書をSSL_CERTとSSL_KEYに設定します。https://room.example.org:7861のように、別のHTTPSルームアドレスとポートを選びます。ホストの操作でそのポートが開きます。ファイアウォールやルーターでは、ルームのポートだけを通してください。通常のMarinara APIは公開しないでください。ポート転送、リレー、証明書確認の回避は自動では設定されません。
  5. 管理者の認証情報とは異なる、12文字以上のルームパスワードを設定します。有効期限付きの招待とパスワードを、信頼する相手に別々に送ります。ゲストはホスト名のフィンガープリント、ルーム名、ペルソナの文章を確認してから、参加を申請します。ホストがPlayers(プレイヤー)で各申請を承認するまで、履歴は一切送られません。

制限と動作は次のとおりです。

Warning: 信頼できる相手にだけ接続し、自分のMarinaraクライアントを使ってください。ホストが提供するクライアント、拡張機能、ファイルは絶対にインストールしないでください。ホストは共有した内容を読むことができ、共有した内容はホストのAIサービスに送られることがあります。直接接続ではネットワークアドレスが相手に伝わります。パスワード、APIキー、個人情報は共有しないでください。少しでもおかしいと感じたら、すぐに退出してください。

制限の詳細とテスト済みのプラットフォームについては互換性と検証の記録を、問題が起きたときはトラブルシューティングを参照してください。

エージェントと拡張機能

任意で追加できる公式のエージェントは、アプリのAgents → Agent Organizer(エージェント → エージェント管理)からインストールします。Marinaraは、自分のメジャーバージョンに合ったPasta-Devs/Marinara-Agentsのカタログを選びます。

カスタムエージェントのインポート

外部のエージェントのファイル、フォルダー、リポジトリーはロックされています。許可するには、Settings → Advanced → Danger Zone(設定 → 詳細設定 → 危険な操作)でAllow custom Agent imports(カスタムエージェントのインポートを許可)をオンにします。環境変数は必要ありません。オンにするまで、インポートの操作はグレー表示のままです。

インポートするたびに、まずそのエージェントが要求する機能を表示します。権限は明示的に承認する必要があります。同梱された関数やツールの選択はインポートされず、生成されたCSSは無害化され、結果の動作は承認済みの機能と照らし合わせて検査されます。この設定をオフにすると、インポートしたエージェントは止まります。Marinaraの中で作ったエージェントと公式パッケージには影響しません。

カスタムエージェントのリポジトリー

リポジトリーのプロンプトやツールは検証されていないため、リポジトリーはデフォルトでオフです。ENABLE_CUSTOM_AGENT_REPOS=trueを設定し、Allow custom Agent imports(カスタムエージェントのインポートを許可)をオンにしてから、Agents → Agent Organizer → Custom Sources(エージェント → エージェント管理 → カスタムソース)を開いて、公開されているGitHubリポジトリーをプレビューします。ソースの追加にも、その後の変更の適用にも、確認が必要です。同期は手動で、Marinaraがバックグラウンドでリポジトリーをクローンしたり、確認しに行ったりすることはありません。受け付けるのは、リポジトリーのルートを指すGitHubのURLだけです。

リポジトリーでは、エージェント、Game Modeのルールセット、またはその両方を公開します。ルートには次のものを置きます。

  [
    {
      "id": "continuity-helper",
      "name": "Continuity Helper",
      "description": "Checks recent turns for contradictions.",
      "phase": "post_processing",
      "enabledByDefault": false,
      "category": "writer",
      "defaultPromptTemplate": "Check {{messages}} for continuity errors."
    }
  ]

インポートしたルールセットには、alice/my-5eのようにリポジトリーの所有者の名前が付くため、公式の名前と重なることはありません。すべてのバージョンが保持され、ゲームは開始したときとまったく同じバージョンでプレイされます。同じバージョンが異なる内容で届いた場合、Marinaraはインストール済みのものを残し、作者にバージョン番号を上げてもらうよう案内します。Marinaraが読み取れないファイルは、理由とともに一覧に表示され、スキップされます。

同期すると、プレビューに表示された、リポジトリーが管理するプロンプト、設定、ツールの値が、リモートの値に置き換わります。アカウントとアートワークの選択はローカルのまま残ります。上流からエージェントが消えた場合、そのエージェントは通常のローカルのエージェントとして残り、リポジトリーとの関連付けだけが外れます。ソースを削除したときも同じで、そのルールセットはインストールされたまま残ります。

カスタムエージェントは、Context Sources(コンテキストソース)でPrevious output(前回の出力)をオンにすると、自身の直近の成功した出力を読み取ることもできます。JSON context output(JSON形式のコンテキスト出力)では、{"text":"main prompt content","agent-context":"private continuation context"}を返します。メインプロンプトに入るのはtextだけです。Hide output as spoilers(出力をスポイラーとして隠す)を使うと、保存済みの出力は折りたたまれたままになります。再生成では置き換えられるターンが除外され、削除済みのメッセージや非アクティブなスワイプはコンテキストに使われません。

外部拡張機能(External Extensions)

サードパーティー製の拡張機能をインポートするには、2つの許可が必要です。環境変数は、サーバーを運用する側の許可です。Danger Zoneのスイッチは、利用者本人の同意です。

  1. .envにENABLE_EXTERNAL_EXTENSIONS=trueを設定します。
  2. Settings → Advanced → Danger Zone(設定 → 詳細設定 → 危険な操作)を開き、データ削除の操作より下までスクロールして、警告を読んでからAllow third-party extension imports(サードパーティー製拡張機能のインポートを許可)をオンにします。

すると、Settings → Addons(設定 → アドオン)の下にExternal Extensions(外部拡張機能)セクションが表示されます。どちらかの許可を閉じると、外部のレコードは無効になり、そのコードも停止します。手動で保存したもの、以前の形式のもの、プロファイルからインポートしたもの、出所が不明なものは外部として扱われます。そのため、フォルダーにファイルを置くだけでは、この2つの許可を回避できません。Professor Mariの下書きには、どちらの許可も必要ありません。下書きは無効の状態で作られ、実行するにはそのコードのハッシュそのものを承認する必要があります。

デフォルトは、サンドボックス化されたブラウザー拡張機能です。古いパッケージの一部は、Marinaraのページを必要とするためFull page access(ページ全体へのアクセス)と表示されます。このモードでは、承認したコードがMarinaraのページ内で動き、ページの内容、ブラウザーのストレージ、ネットワークAPI、セッションにアクセスできます。このモードを使えるのは、2つの許可が両方とも開いているExternal Extensionsだけで、別途警告への同意も必要です。無効にした後は、ページを再読み込みしてください。

環境変数の完全なリファレンス

アクセス制御、ストレージ、ログ、タイムアウト、特権操作、ローカルアドレスへの接続の許可は、上の表で説明しました。残りの設定はここにまとめます。

サーバーと起動

変数デフォルト説明
PORT7860サーバーが待ち受けるポート。Android、Docker、Termuxでは同じ値にそろえてください。
HOST127.0.0.1(ランチャーとDockerイメージでは0.0.0.0)待ち受けるネットワークインターフェイス。LANから接続するには0.0.0.0にします。デフォルトのComposeファイルは、Dockerのポートを127.0.0.1だけに公開します。
MARINARA_ANDROID_SECRET空APKが管理するTermuxインストール向けの内部シークレット。Androidアプリが生成し、Termuxランチャーが環境変数として渡します。利用者に設定を求めないでください。ちょうど64文字の16進数でなければなりません。空でない無効な値を受け取ると、端末内からのリクエストはHTTP 503で失敗します。
MARINARA_ANDROID_SECRET_FILE~/.marinara-engine/android-secretTermuxランチャーとローカルのmariコマンドが使うシークレットファイル。APKとランチャーが管理します。
AUTO_OPEN_BROWSERtrueランチャーがアプリのURLを開くかどうか。falseにすると開きません。APKが管理するセットアップでは、これをオフにします。
AUTO_UPDATE_ENABLEDtrueGitを使うランチャーが、起動前にアップデートを取得して適用するかどうか。falseにすると、次回の起動から無効になります。この場合もランチャーは、新しいリリースがないかを読み取りだけで確認し、リマインダーを表示します。--skip-updateを使うと、1回の起動だけ両方の確認を省略します。
MARINARA_NOTICES_ENABLEDtrueサーバーがメンテナーのお知らせを取得するかどうか。Marinaraのお知らせを参照してください。
MARINARA_NOTICES_URLnoticesブランチのnotices.jsonフォークやミラー向けに、お知らせファイルを上書きします。同じ方法で検証され、https://github.com/Pasta-Devs/以外を指すリンクは削除されます。
MARINARA_ENV_FILEプロジェクトルートの.env.envファイルのパスを変更します。起動前に設定してください。
MARINARA_MEDIA_GENERATION_CONCURRENCY4サーバー全体で同時に実行する画像・動画リクエストの最大数。ローカルのComfyUIやSwarmUIでVRAMが足りなくなる場合は、1-2に下げてください。0にすると上限をなくします。無効な値は警告を出して無視されます。一括処理が最後の枠を使うことはありません。この上限は、Queue media generation requests(メディア生成リクエストを順番待ちにする)に加えて適用されます。この設定はSettings → Generations → Overall Generations(設定 → 生成 → 生成全般)にあってデフォルトでオンになっており、画像と動画のジョブをアカウントごとに順番待ちにします。
MARINARA_MEDIA_GENERATION_WAIT_TIMEOUT_MS600000(10分)リクエストが空き枠を待つ時間。これを過ぎると失敗します。0にすると無期限に待ちます。
MARINARA_SHARED_GPU_HOSTS空ローカルモデルとローカルの画像・動画バックエンドが1台のGPUを共有する場合(llama-swapなど)の、カンマ区切りのhost:port一覧。一覧内のホストへのテキストとメディアのリクエストは交互に処理されるため、画像がチャットの返信の後ろでいつまでも待たされることはありません。画像やクリップが待つ時間は、最長でMARINARA_MEDIA_GENERATION_WAIT_TIMEOUT_MSです。埋め込みは待機させません。再起動しなくても新しいリクエストに適用されます。
MARINARA_ENV_WATCH1.envの監視方法。デフォルト: 変更の通知を使い(約250 msの待ち合わせ)、予備として30秒ごとに確認します。poll: 常に30秒ごとの確認を使います。0: オフ。再起動とホットリロードを参照してください。
TZシステムのデフォルトサーバーの処理に使う、ホストの予備のタイムゾーン(例: Europe/Warsaw)。ホストのタイムゾーンを使うには、未設定のままにするか空にしてください。スケジュールでは、保存したConversationのSchedule timezone(スケジュールのタイムゾーン)が優先されます。
CORS_ORIGINShttp://localhost:5173,http://127.0.0.1:5173クロスオリジンのリクエストを許可するブラウザーのオリジン。
AUTO_CREATE_DEFAULT_CONNECTIONtrue古い形式のフラグ。現在のビルドには最初から使えるキーが同梱されていないため、何も作成しません。アプリで自分のアカウントを追加してください。

Schedule timezoneのデフォルトは、デバイスのタイムゾーンです。Conversationのセットアップ中、ConversationのChat Settings、キャラクターのスケジュール編集画面で変更できます。これはすべてのConversationのチャットで共有される1つのグローバルな設定で、同じサーバーのほかのクライアントにも同期されます。

メディアとスプライトのツール

変数デフォルト説明
FFMPEG_PATH空アニメーション表情のGIFに使うffmpegのパス。指定しない場合は、PATH上のffmpegを使います。
SPRITE_ANIMATED_FFMPEG_TIMEOUT_MS180000(3分)アニメーション表情のクリップ1本の変換に許される時間。
SPRITE_BACKGROUND_REMOVAL_ENGINEautoautoは組み込みの背景処理を先に試し、次に任意のAIツールを使います。builtinは組み込みの背景処理だけを使います。backgroundremoverはAIツールを必ず使います。
BACKGROUNDREMOVER_AUTO_INSTALLfalsetrueにすると、起動時に任意のAI背景除去ツールをインストールします。
BACKGROUNDREMOVER_COMMAND空システムにインストールしたbackgroundremoverプログラムのパス。
BACKGROUNDREMOVER_PYTHON空backgroundremoverをインストールしたPythonのパス。
BACKGROUNDREMOVER_TIMEOUT_MS600000(10分)AIによる背景除去の呼び出し1回に許される時間。

シーン動画のプロバイダー

動画のアカウントはアプリの中で設定します。ここの設定は、処理を調整するだけのものです。値の単位はミリ秒です。

変数デフォルト説明
GOOGLE_VEO_VIDEO_POLL_INTERVAL_MS10000サーバーがGoogle Veoの処理を確認する間隔。
XAI_VIDEO_POLL_INTERVAL_MS5000xAI Imagineの処理を確認する間隔。
OPENROUTER_VIDEO_POLL_INTERVAL_MS10000OpenRouterの動画処理を確認する間隔。
SEEDANCE_VIDEO_POLL_INTERVAL_MS10000Seedanceの処理を確認する間隔。
VIDEO_REFERENCE_PUBLIC_BASE_URL空このサーバーの公開HTTPSアドレス。参照画像をURLから取得する必要があるサービスに使います。

ロアブック

どちらもデフォルトでオフで、.envを変更した後の次の生成から適用されます。LOREBOOK_STABLE_GROUP_WINNERSを設定すると、Settings → Advanced → Features(設定 → 詳細設定 → 機能)のStable lorebook picks(ロアブックの選択を固定)スイッチより優先されます。設定しない場合は、スイッチで決まります。機能スイッチを参照してください。

変数デフォルト説明
LOREBOOK_STABLE_GROUP_WINNERSfalse候補が変わらないあいだ、包含グループで選ばれるエントリーをチャットごとに同じに保ち、生成のたびに選び直しません。プロバイダーのプロンプトキャッシュのために、プロンプトの先頭を安定させます。
LOREBOOK_COMPACT_STORED_SCANSfalse有効化されたエントリーの全文を、最新のアシスタントまたはナレーターのメッセージにだけ保存します。古いメッセージには、エントリーのID、キー、スコアが残ります。大きなロアブックを使うチャットがかなり小さくなります。新しいメッセージを削除した場合、再び最新になったメッセージのActive Contextとエージェントの再試行では、そのエントリーの現在の本文を表示します。

scripts/compact-lorebook-scans.mjsは、以前のチャットにも同じ規則を適用します。先にサーバーを停止してください。--applyを渡さないかぎり試行(ドライラン)だけを行い、書き込む前に両方のメッセージテーブルをバックアップします。

堅牢性

どれもデフォルトでオフで、従来の動作のままになります。STORAGE_CACHE_WINDOWS_BOOT_ID、SHUTDOWN_WINDOWS_CONSOLE_SIGNALS、SHUTDOWN_FORCE_EXIT_ON_REPEATの変更には再起動が必要です。それ以外は、.envを変更すると適用されます。PROVIDER_RETRY_TRANSIENT_ERRORSを設定すると、Settings → Advanced → Features(設定 → 詳細設定 → 機能)のRetry failed provider calls(失敗したプロバイダー呼び出しを再試行)スイッチより優先されます。設定しない場合は、スイッチで決まります。

変数デフォルト説明
PROVIDER_RETRY_TRANSIENT_ERRORSfalse接続が拒否されたか到達できなかった場合、または502か503の場合に、最大5秒の待機を挟んで最大2回再試行します。対象は、テキストが届き始める前だけです。504や途中で切れた接続は再試行しません。アカウントにフォールバックがある場合は使われず、すぐにフォールバックを試します。失敗の確定が遅いホストでは、エラーの表示が約20秒遅れることがあります。
STORAGE_SKIP_UNCHANGED_WRITESfalseチャットファイルまたはmanifest.jsonの内容が、このサーバーが最後に書き込んだものと同じで、ディスク上のファイルも変わっていない場合、保存時に書き直しを省略します。.bakから復元した直後のファイルは必ず書き直します。
STORAGE_YIELDING_SERIALIZEfalse大きなチャットファイルの保存準備を短い区間に分けて行い、非常に長いチャットの保存でほかのリクエストが止まらないようにします。書き込まれるバイト列は同じです。
STORAGE_CACHE_WINDOWS_BOOT_IDfalseWindowsのみ。ストレージロックが起動のたびに行う起動時刻の確認(約1.5~2秒のPowerShell処理)の結果を、次の再起動までDATA_DIR内の.writer-boot-id.jsonに記憶します。
SHUTDOWN_WINDOWS_CONSOLE_SIGNALSfalseWindowsのみ。<kbd>Ctrl</kbd>+<kbd>Break</kbd>やコンソールを閉じる操作でも、サーバーを正常に停止し、保留中の保存を書き込みます。コンソールを閉じる場合は、Windowsが許す約5秒に収まるよう、短い期限を使います。
SHUTDOWN_FORCE_EXIT_ON_REPEATfalse最初の<kbd>Ctrl</kbd>+<kbd>C</kbd>または<kbd>Ctrl</kbd>+<kbd>Break</kbd>から1.5秒より後にもう一度押すと、サーバーをすぐに終了します。書き込まれていない保存が失われる場合があります。この設定がない場合、繰り返しは無視され、8秒の終了期限が適用されます。
SHUTDOWN_EARLY_FLUSHfalse停止シグナルを受け取ると、接続を閉じている途中でも保留中の保存を書き始めます。Advanced Settingsの再起動では使いません。
SHUTDOWN_RUNTIME_STOP_BUDGET_MS0停止シグナルを受け取ったとき、ストレージを閉じる前にバックグラウンドのランタイム(パッケージ、拡張機能、内蔵モデル)を待つ時間。0にするとすべてを待ちます。最大は2500で、8秒の期限内にストレージを閉じます。Advanced Settingsの再起動は、引き続きすべてを待ちます。

連携とその他

変数デフォルト説明
CLAUDE_SUBSCRIPTION_USE_INSTALLED_CLItrueClaude (Subscription)のアカウントで、このコンピューターのClaude Codeが同梱版と同じかそれより新しい場合に、そちらを使うかどうか。Androidには同梱版がないため、オンにしておく必要があります。falseにすると、常に同梱版を使います。5分以内に反映されます。
DOCS_I18N_BASE_URL公式のdocs-i18nブランチドキュメントとUIの言語パックのダウンロード元。UIパックは、そのui/配下を使います。公開されたhttps://ホストでなければなりません。
GIPHY_API_KEY空ConversationモードのGIF検索に使うGiphyのキー。設定して再起動するまで、検索はオフのままです。
INTIFACE_URLws://127.0.0.1:12345Intifaceの触覚アプリのデフォルトのアドレス。
SPOTIFY_REDIRECT_URIリクエストから自動で決まるSpotifyのログインのコールバック用URLを上書きします。TLSを上流で終端している場合に設定します。
MARI_WIKI_CONTENT_MAX_BYTES50000Professor Mariが切り詰める前に読み込むwikiページの内容の最大サイズ。
MARI_WIKI_REQUEST_TIMEOUT_MS30000Professor Mariによるwikiのリクエスト1件に許される時間。
MARI_WIKI_CACHE_TTL_MS300000Professor Mariがwikiの読み込み結果をキャッシュする時間。
SIDECAR_RUNTIME_INSTALL_ENABLEDfalse(Windowsのランチャーはtrueに設定します)ループバックからの場合に、管理者用のヘッダーなしでBuilt-in model(内蔵モデル)のランタイムをインストールできるようにします。

Built-in modelについては内蔵モデルのセットアップを参照してください。

外向きのHTTPプロキシ

ネットワークによっては、HTTPプロキシを経由しないとインターネットに出られないことがあります。たとえば、TUNモードを使わないv2rayNがそうです。Marinaraは、AIサービス、画像サービス、埋め込みサーバー、エージェントのカタログへのリクエストを、そのプロキシ経由で送れます。Marinaraを起動する環境か.envに次の設定を書き、再起動してください。

変数デフォルト説明
NODE_USE_ENV_PROXY未設定1にすると、プロキシを使います。これがない場合、MarinaraはNode.jsと同じくプロキシの設定を無視します。
HTTP_PROXY空http://127.0.0.1:10809のようなプロキシのアドレス。HTTPS_PROXYを設定していない場合は、すべてのリクエストに使います。
HTTPS_PROXY空HTTP_PROXYと異なる場合に、https://のアドレスに使うプロキシ。
NO_PROXY空プロキシを通さないホストのカンマ区切りの一覧。ネットワーク上のモデルサーバーを追加してください。localhost、127.0.0.1、::1は常にプロキシを通りません。

関連ガイド