.env.example

# Optional Huabu configuration overrides.
#
# Local use initializes automatically. For remote access, run `pnpm run setup`.
# Before setup or a connection-token reset, stop this instance's Huabu and Vite
# dev servers; start them again afterward. Setup does not detect running services.
# Copy this file to .env only when you need overrides; uncomment the values you use.
# Deployment overrides take precedence over setup, which never edits .env.
# Setup displays environment-managed fields and skips their inputs.
# Passwords are never displayed; both Basic Auth values must be configured together.
# Shell environment variables take precedence over .env values.
# Restart the server after deployment changes.
# Detailed guidance: docs/architecture/deployment-security.md

# ══════════════════════════════════════════════════════════════════
# OPTIONAL ADVANCED DEPLOYMENT OVERRIDES
# ══════════════════════════════════════════════════════════════════

# ── Standalone credential encryption ──
# Optional externally managed master key. Without it, standalone servers
# create a private master-key file outside the data directory.
# Existing encrypted stores still require their original key; never replace it.
# Keep externally managed keys outside the data directory; `.env` is git-ignored.
# Generate a key with Node.js:
# node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
# HUABU_SECRET_KEY=
# Optional private deployment-config/master-key directory. Defaults to
# ~/.huabu/servers/<hash-of-absolute-data-directory>/, independent of startup cwd.
# Back up this directory with the matching data directory; persist both in Docker.
# Use an absolute path. POSIX directory/file permissions must be 0700/0600.
# HUABU_CONFIG_DIR=

# ── Ports ──
# SERVER_PORT is fixed for `pnpm start:web`; startup fails if it is unavailable.
# Development launchers may advance from this preferred port for parallel use.
# SERVER_PORT=3001
# WEB_PORT is only for the Vite development server, not `pnpm start:web`.
# WEB_PORT=5173

# ── Network (outbound proxy) ──
# HTTPS_PROXY=http://127.0.0.1:1086

# ── Debug ──
# Writes assembled per-turn prompts to each Space's huabu.prompt.log extension
# storage. These logs may contain sensitive conversation content.
# Default: enabled outside production, disabled in production.
# Set true to enable or off to disable; existing logs are not removed.
# HUABU_DEBUG_PROMPT=true

# ── Agentlet connection token ──
# Generated and securely persisted automatically; reused across server restarts.
# Only set this override when managing the token outside Huabu.
# Connection guidance: Settings > Agent > Add device.
# HUABU_CONNECTION_TOKEN=

# ── Network exposure ──
# By default the server binds to 127.0.0.1 only, so a fresh install is
# never silently exposed to the LAN. Prefer `pnpm run setup` to enable remote access.
# Advanced override: set HUABU_BIND_HOST=0.0.0.0 (or a
# specific NIC IP) to listen on every interface. A non-loopback bind requires
# HUABU_PUBLIC_ORIGIN and both HUABU_BASIC_AUTH_* values or Bubble identity, unless
# login is explicitly disabled with HUABU_AUTH_MODE=none; startup fails closed otherwise.
# The public origin hostname is automatically
# trusted by the Host/CORS/Origin guards. Put HTTPS in front for anything beyond
# a trusted private network.
# HUABU_BIND_HOST=0.0.0.0
# Canonical root origin reachable by remote Agentlets. Required for a
# non-loopback bind. Use HTTP only on a trusted private network; otherwise
# terminate HTTPS in front of Huabu. Paths, credentials, queries, and fragments
# are rejected. RFS and Agentlet endpoints are derived from this one value.
# HUABU_PUBLIC_ORIGIN=https://huabu.team-a.example
# Optional additional browser aliases beyond HUABU_PUBLIC_ORIGIN.
# HUABU_ALLOWED_HOSTS=192.168.1.50,huabu-alt.team-a.example

# ── Single-owner remote login ──
# Setup accepts a custom login name; Enter reuses the saved name or `owner`.
# The password is stored encrypted.
# These optional overrides must be provided together. The owner can use every
# feature, including Settings, OAuth, and External Agents. Basic Auth is
# plaintext over HTTP, so use a trusted private network or external HTTPS.
# HUABU_BASIC_AUTH_USER=
# HUABU_BASIC_AUTH_PASS=
# Optional: basic (default) or none. Setup also offers a no-login choice.
# With none, anyone who can reach Huabu has full owner access. Use only on a
# trusted network or behind an authenticated proxy; remove Basic Auth overrides.
# HUABU_AUTH_MODE=none

# Identity provider: local (default) or bubble. Local needs no identity server
# and keeps the Basic Auth configuration above for network deployments.
# HUABU_IDENTITY_PROVIDER=local
#
# bubble: run Bubble inside this Server and serve its API at /bubble. Requires
# HUABU_POSTGRES_URL; Bubble's records live in its "bubble" schema, whichever
# backend holds Huabu's own records. Do not configure Basic Auth alongside it.
# A Bubble "member" grant on the system target admits a principal to Huabu,
# and an "owner" grant also allows settings, credentials and agents. A member
# reaches only the Spaces they created or own, plus every Space in a Workspace
# they own, and cannot run agents.
# The browser signs in through an auth0 or entra entry below; register
# <origin>/auth/callback as its single-page-app redirect URI.
# HUABU_BUBBLE_AUTH is Bubble's ordered authenticator list as JSON (drivers:
# local-token, master-key, auth0, entra, default). Default: local tokens only.
# master-key goes last; "default" verifies nothing and is refused on a network
# bind. Keep the master key in a HUABU_ variable named by masterKeyEnvVar:
# agents inherit every other variable, and startup refuses BUBBLE_MASTER_KEY.
# HUABU_BUBBLE_AUTH=[{"driver":"local-token"},{"driver":"master-key","masterKeyEnvVar":"HUABU_BUBBLE_MASTER_KEY","defaultPrincipalId":"admin"}]
# HUABU_BUBBLE_MASTER_KEY=
# Principal provisioned as Bubble system owner at startup.
# HUABU_BUBBLE_OWNER=admin

# ── Storage (restart required) ──
# Structured records: disk (default), sqlite or postgres. The two axes are
# independent, so every pairing of an implemented record backend with an
# implemented blob backend is a valid deployment.
# For sqlite or postgres, leave HUABU_WORKSPACE unset in both the shell and
# .env files — neither keeps Workspaces as folders. First launch creates a
# named Workspace; later launches reopen the most recently used one. The UI
# has no Workspace picker for them; named Workspace creation/switching is
# available via API. Changing backends does not migrate existing data.
# HUABU_STRUCTURED_BACKEND=disk
#
# Attachments and other Space bytes are always files — in a local directory
# (disk) or an object store (azure), never rows in the record backend.
# HUABU_BLOB_BACKEND=disk
#
# Postgres connection string. Required with HUABU_STRUCTURED_BACKEND=postgres
# or HUABU_IDENTITY_PROVIDER=bubble; startup fails without it. One database or schema holds Workspaces, Spaces,
# nodes, logs, Tasks and agent conversations. Single Server per database: the
# locking is not distributed admission.
# HUABU_POSTGRES_URL=postgresql://user:password@host:5432/huabu
#
# Azure Blob credentials. Both are required with HUABU_BLOB_BACKEND=azure.
# The container must already exist and stay private — the operator owns it,
# and deleting a Space only sweeps that Space's own keys.
# HUABU_AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
# HUABU_AZURE_BLOB_CONTAINER=huabu
#
# Key prefix inside that container, one path segment. Default: huabu. Give
# each deployment sharing a container its own.
# HUABU_AZURE_BLOB_PREFIX=huabu
#
# SQLite database file. Default: <HUABU_DATA_DIR>/storage/sqlite/huabu.sqlite.
# Only used with HUABU_STRUCTURED_BACKEND=sqlite; does not move blob files.
# HUABU_SQLITE_PATH=/var/lib/huabu/storage/sqlite/huabu.sqlite
#
# Blob base directory when records are rows and bytes are local files. Each
# Space uses a subdirectory <workspaceId>/<canvasId>/. Default:
# <HUABU_DATA_DIR>/storage/disk/blobs. Ignored with disk records, where bytes
# stay inside each Space folder, and with HUABU_BLOB_BACKEND=azure.
# HUABU_BLOB_ROOT=/var/lib/huabu/storage/disk/blobs
#
# Default data directory: apps/server/data for source server launches and
# dev:desktop; <Electron userData>/data for start:desktop and installed apps.
# For desktop, pass storage settings in the app process environment; there
# is no in-app storage selector. Installed apps do not load this repo .env.
# Restart the server or fully quit and relaunch desktop after changes.

# ── Managed workspace mode (disk records only) ──
# Locks workspace to this absolute path; disables folder picker.
# Remote setup confirms and saves a Home directory without requiring this override.
# Unset with no saved remote Home = free mode (disk clients choose a directory;
# sqlite and postgres open their own Workspace). Setting this with a backend with no
# Workspace folder fails startup; managed mode is disk-only.
# HUABU_WORKSPACE=/var/lib/huabu/team-a

# ══════════════════════════════════════════════════════════════════
# OPTIONAL MODEL AND SERVICE FALLBACKS
# Prefer Settings for these values. Saved credentials take precedence over
# environment credentials; deployment overrides above follow different rules.
# ══════════════════════════════════════════════════════════════════

# ── Built-In Pi models (Settings > Agent > Built-In Pi) ──
# Not required for external agents, which manage their own model credentials.
# Without saved model configuration, an available provider key selects an
# initial provider/model. It does not replace an existing model selection.
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=
# GEMINI_API_KEY=
# OPENROUTER_API_KEY=
# GROQ_API_KEY=
# XAI_API_KEY=
# MISTRAL_API_KEY=
# Azure requires the following key, endpoint, and deployment name together.
# AZURE_OPENAI_API_KEY=
# AZURE_OPENAI_API_ENDPOINT=
# AZURE_OPENAI_API_DEPLOYMENT_NAME=
# Optional Azure API version override; otherwise the provider default applies.
# AZURE_OPENAI_API_VERSION=

# ── Web search — Tavily (Settings > Services) ──
# TAVILY_API_KEY=

# ── YouTube transcripts — RapidAPI (Settings > Services) ──
# RAPIDAPI_KEY=

# ── Handwriting recognition — Azure AI Vision (Settings > Services) ──
# VISION_ENDPOINT=https://<resource-name>.cognitiveservices.azure.com/
# VISION_KEY=

# ══════════════════════════════════════════════════════════════════
# DEVELOPMENT AND FRONTEND BUILD OVERRIDES
# ══════════════════════════════════════════════════════════════════

# ── Public user handbook ──
# Absolute URL opened by Handbook actions. `pnpm dev` and `pnpm dev:desktop`
# read this override and otherwise use the public Huabu handbook.
# For production builds, export it in the build environment or set it in
# apps/web/.env.local; the tracked apps/web/.env.production supplies the default.
# Direct Vite development falls back to /docs/ on the current origin.
# Production requires HTTPS; HTTP localhost is allowed only in development.
# Changing this for a production app requires rebuilding the frontend.
# VITE_HANDBOOK_URL=

# Personal Canary redeployment options: docs/architecture/canary-deployment.md