.env.example | Knowledge Hub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
# Yuralume self-host deployment settings.
#
# Provider keys are configured after boot from Admin → Provider Keys.
# Do not put LLM / embedding / image / video / TTS keys in this file.

APP_ENV=development
APP_BASE_URL=http://127.0.0.1:8002

# Optional browser Web Push. When all three are set, users can enable OS-level
# notifications in Player Settings. Leave unset to keep SSE/in-app notifications only.
# WEB_PUSH_VAPID_PUBLIC_KEY=
# WEB_PUSH_VAPID_PRIVATE_KEY=
# WEB_PUSH_VAPID_SUBJECT=mailto:admin@example.com
# How long (seconds) the push service retains an undeliverable message for
# store-and-forward. Default 86400 (24h); 0 = live-only, dropped when the
# device is offline/dozing.
# WEB_PUSH_TTL_SECONDS=86400

# Interface timezone for the local single user (IANA, e.g. Asia/Taipei) — civil
# dates/times, schedules, "today" boundaries. DB and server instants stay UTC.
# In single-user mode this seeds the default operator at first boot (same as
# USER_PRIMARY_LANGUAGE); the self-host installer fills it from your host.
USER_TIMEZONE=UTC

# Default interface + content language for the local single user. In single-user
# mode (AUTH_ENABLED=false) this seeds the default operator at first boot, so the
# UI and the character replies come up in this language without touching the
# in-app switcher. In multi-user mode each user picks their own at /auth/setup.
# Valid: zh-TW (default), en-US, ja-JP.
USER_PRIMARY_LANGUAGE=zh-TW

# PostgreSQL. Leave empty only for tests / ephemeral local experiments.
DATABASE_URL=postgresql+asyncpg://kokoro:kokoro_dev@127.0.0.1:5544/kokoro_link

# Single-machine mode is still the default. Set AUTH_ENABLED=true for login.
AUTH_ENABLED=false
# JWT_SECRET=change-me-to-a-long-random-string-32+chars
# JWT_TTL_SECONDS=604800
# Sliding renewal: an active player's session is extended on use. This caps how
# far one session can be carried from first sign-in; 0 (default) = no cap.
# JWT_ABSOLUTE_TTL_SECONDS=0

# Required before saving provider keys in Admin UI.
CONFIG_ENCRYPTION_KEY=change-me-to-a-long-random-string-32+chars

# Object Storage API. In self-host compose this points at storage-local.
DEPLOYMENT_MODE=container
STORAGE_PROVIDER=http
STORAGE_URL=http://127.0.0.1:9012
STORAGE_KEY=change-me
# New DB media refs are app-relative (/v1/public/...). Set this only if an
# external storage/CDN service returns URLs that the app must reverse-map.
# STORAGE_PUBLIC_URL=https://media.example.com
# STORAGE_TIMEOUT_SECONDS=30

# WhatsApp sidecar gateway. Container self-host should use the compose service
# name. Local host-mode development can override this to http://127.0.0.1:32190.
# Players do not enter this in the UI.
WHATSAPP_SIDECAR_URL=http://whatsapp-sidecar:32190
# WHATSAPP_SIDECAR_API_TOKEN=

# Optional first-run admin bootstrap. When both are set and the
# default user still has no credentials, app startup attaches them
# automatically (same effect as walking through /auth/setup once).
# Becomes a no-op after the first successful run. Safe to leave in
# place; safer to delete the password after first boot. Honoured
# whether AUTH_ENABLED is true or false — flipping the auth switch
# later picks up the seeded admin.
# BOOTSTRAP_ADMIN_EMAIL=admin@example.com
# BOOTSTRAP_ADMIN_PASSWORD=change-me-on-first-login

# Surface developer-facing admin panels in the SPA (observability,
# experiments, pending follow-ups, humanness metrics, persona drift /
# pattern timelines). Default off keeps the player-facing surface
# clean; flip to true for self-host owner debugging. Backend admin
# APIs are reachable either way — this flag only controls UI render.
# KOKORO_DEBUG_UI_ENABLED=false

# Optional generation usage price catalog. The bundled OpenAI sample covers
# Standard LLM token pricing that maps cleanly to Core usage rows.
# KOKORO_USAGE_PRICE_CATALOG_PATH=usage-prices.openai.json

# Conversational persona discovery. These flags only control whether
# the LLM curiosity planner contributes natural, low-pressure discovery
# hints to chat / proactive prompts. They do not create player forms
# and do not bypass the existing persona extraction + dream pipeline.
# PERSONA_CURIOSITY_ENABLED=true
# PERSONA_CURIOSITY_PROACTIVE_ENABLED=true

# Web fetch tool limits (always-on tool; tune for resource-constrained deploys).
# WEB_FETCH_TIMEOUT=15
# WEB_FETCH_MAX_HTML_BYTES=2000000
# WEB_FETCH_MAX_TEXT_CHARS=6000

# NOTE: web search (Tavily/SearXNG/DuckDuckGo/OpenAI Web Search), real-world facts
# (Weather/Calendar/GeoIP), NSFW mode TTL, and world-event RSS feeds now
# live in the Admin UI (Admin → Provider Keys / 站點設定 / World events).
# The env vars below are still read once on first boot to seed the DB, then
# the Admin UI is the source of truth — see the Deprecated section at the
# end of this file.

# Prompt pack overlay directory. Matching .txt files override bundled
# src/kokoro_link/data/prompts/; PROMPTS_DIR and KOKORO_PROMPTS_DIR are
# still accepted as legacy fallback names.
# YURALUME_PROMPT_PACK_DIR=/etc/yuralume/prompts-override

# Player-visible reply quality gates. Default-on; low-risk chat turns
# keep incremental streaming, high-risk turns buffer for quality review.
# KOKORO_PROMPT_MATERIAL_DIGEST_ENABLED=true
# KOKORO_REGISTER_PROFILE_ENABLED=true
# KOKORO_NOVELTY_GATE_ENABLED=true
# KOKORO_NOVELTY_GATE_MAX_RETRIES=1
# KOKORO_REPLY_QUALITY_GATE_RISK_THRESHOLD=0.65
# KOKORO_REPLY_QUALITY_SIMILARITY_THRESHOLD=0.88

# Character-card marketplace pack directory override. Points at an
# external folder of .lumecard packs; defaults to the bundled
# src/kokoro_link/data/character_cards/.
# CHARACTER_CARD_PACK_DIR=/etc/yuralume/character-cards

# Frontend Vite dev server.
VITE_BACKEND_HOST=127.0.0.1
VITE_BACKEND_PORT=8002
VITE_FRONTEND_HOST=0.0.0.0
VITE_FRONTEND_PORT=5174
# VITE_ALLOWED_HOSTS=

# Deprecated compatibility:
# Existing KOKORO_* variables are still read as fallback during migration,
# but new deployments should use the names above and configure provider
# keys from Admin → Provider Keys.
#
# Deprecated (已改由 Admin 後台管理，下個 release 移除 — CORE_ENV_TO_ADMIN_CONFIG):
# These are read ONLY on first boot (when the corresponding DB rows are
# empty) to seed the Admin DB, after which the Admin UI is authoritative.
# Setting them logs a deprecation warning at startup.
#
#   Provider config → Admin → Provider Keys:
#     KOKORO_COMFYUI_SERVER / _CHECKPOINT / _WORKFLOW_FILE / _TIMEOUT / _LORA_DIR
#     KOKORO_IMAGE_API_* / KOKORO_VIDEO_API_* / KOKORO_OPENAI_IMAGE_*
#     KOKORO_EMBEDDING_* / KOKORO_LMSTUDIO_* (→ local_openai_compatible)
#     KOKORO_TTS_API_KEY / _BASE_URL / _MODEL (TTS auth)
#     TAVILY_API_KEY / TAVILY_MAX_RESULTS / TAVILY_TIMEOUT / TAVILY_SEARCH_DEPTH
#
#   Deployment facts / policy → Admin → 站點設定:
#     CALENDAR_REGION / CALENDAR_ENABLED
#     WEATHER_LATITUDE / WEATHER_LONGITUDE / WEATHER_LOCATION_LABEL / WEATHER_*
#     GEOIP_ENABLED / GEOIP_PROVIDER / GEOIP_ENDPOINT / GEOIP_*
#     NSFW_MODE_TTL_SECONDS
#
#   World-event RSS feeds → Admin → World events:
#     KOKORO_WORLD_EVENT_FEED_N_SOURCE_ID / _URL / _TAGS
#     KOKORO_WORLD_EVENT_RETENTION_DAYS / KOKORO_WORLD_EVENT_SCHEDULER_INTERVAL
#
#   Per-character voice (voice_id / translate target) → set per character in
#     the character voice profile; the global KOKORO_TTS_VOICE_ID /
#     KOKORO_TTS_TRANSLATE_TARGET_LANG remain the resolve fallback.