MyAiDesk/nomifun-tauri/docs/reference/configuration.md

Configuration Reference

Every flag and environment variable NomiFun reads, with defaults and the file that owns each one. Values are taken from the source — if a setting is not in this page it does not exist.

NomiFun ships one Rust backend (nomifun-app, binary nomicore) and two hosts that embed it:

• nomifun-desktop — the Tauri desktop shell. Boots the backend under AuthPolicy::TrustLocalToken on a chosen loopback port and injects a per-boot trust secret into its own WebView.
• nomifun-web — the standalone web/server host. Boots the same backend in authenticated mode by default and serves the SPA on the same port.

Both hosts share the same configuration surface for the backend; the per-host CLIs only override the bits each one owns.

nomifun-web flags and environment variables

Source: apps/web/src/main.rs.

Flag	Env var	Default	Purpose
--host	NOMIFUN_WEB_HOST	127.0.0.1	IP to bind on. 0.0.0.0 accepts LAN/VPN/public traffic; pre-seed or complete first-run setup before broad exposure. Hostnames are not parsed; bad input fails fast at startup.
--port	NOMIFUN_WEB_PORT	8787	TCP port. Serves the API, the WebSocket at /ws, and the SPA from one socket.
--data-dir	NOMIFUN_DATA_DIR	per-user app-data dir	Backend data directory (SQLite database, agent state, logs, Bun cache). Defaults to the per-user location shared by every host — %LOCALAPPDATA%\NomiFun\Nomi on Windows, ~/Library/Application Support/NomiFun/Nomi on macOS, $XDG_DATA_HOME/NomiFun/Nomi on Linux. Override with the flag or NOMIFUN_DATA_DIR (taken literally, no suffix); use an absolute path in production.
--dist	NOMIFUN_WEB_DIST	../../ui/dist	Directory containing the built SPA. Set this explicitly when deploying outside the repo.
--admin-user	NOMIFUN_ADMIN_USERNAME	admin	Username used when pre-seeding the first admin. Ignored once an admin exists.
--admin-password	NOMIFUN_ADMIN_PASSWORD	—	Pre-seeds the first admin password at boot, skipping interactive setup. Ignored once an admin exists.
--insecure-no-auth	NOMIFUN_WEB_INSECURE_NO_AUTH	false	DANGER. Disables authentication entirely (desktop-style local mode). Only use on loopback or a fully trusted private network.

Boolean envs accept 1, true, yes, on (case-insensitive).

nomicore (backend) flags

Source: crates/backend/nomifun-app/src/cli.rs.

These are the flags exposed by the standalone nomicore binary. The two hosts construct a defaulted Cli and override only what they own — so the same flags apply when the backend is run on its own.

Flag	Default	Purpose
--host	127.0.0.1 (DEFAULT_HOST)	Host address to listen on.
--port	25808 (DEFAULT_PORT)	Port to listen on.
--data-dir	per-user app-data dir	Database + file storage root. Bound to the NOMIFUN_DATA_DIR env (literal value) via clap; with neither set it resolves default_data_dir() — the same per-user location all hosts share.
--work-dir	(none)	Working directory for conversation workspaces. Falls back to NOMIFUN_WORK_DIR env, then to the data dir itself.
--app-version	crate version	Host application version reported to the extension engine for compatibility checks.
--local	false	No-auth local mode for standalone nomicore. nomifun-web --insecure-no-auth maps to the same policy. The desktop shell does not use this flag; it uses TrustLocalToken instead.
--log-dir	<data-dir>/logs	Directory for rolling daily log files.
--log-level	info	Log level filter. Supports per-target overrides — e.g. info,nomifun_mcp=trace.

Subcommands (used internally by the agent CLI bridge and for diagnostics):

Subcommand	Purpose
mcp-requirement-stdio	MCP stdio server for AutoWork requirement declaration tools.
mcp-knowledge-stdio	MCP stdio server for per-session knowledge search.
mcp-gateway-stdio	MCP stdio server for Desktop Gateway tools.
mcp-open-stdio	MCP stdio server exposing a reliable OS open tool.
mcp-computer-stdio	MCP stdio server exposing desktop computer-use tools.
mcp-browser-stdio	MCP stdio server exposing browser-use tools.
terminal-hook --event <kind>	One-shot terminal lifecycle hook relay.
doctor	Self-check: hydrate the agent registry, probe every CLI on $PATH, print a per-agent availability table.
tools	List public Remote capability names and descriptions as JSON.
call <name> [json-args]	Invoke a public Remote capability on a running instance via /v1.
agent "<goal>"	Convenience wrapper over the nomi_agent_run capability.

Shared environment variables

These are read by the backend regardless of which host embeds it.

Env var	Read by	Effect
NOMIFUN_DATA_DIR	all hosts	Source of truth for the backend data directory when the host wants to honour it. The desktop shell appends /Nomi: with the env set the dir is $NOMIFUN_DATA_DIR/Nomi; with it unset the dir is the per-user app-data default (see below). The standalone web host and the nomicore binary use it literally as the default for --data-dir (no extra suffix).
NOMIFUN_WORK_DIR	nomicore	Fallback for --work-dir (per-conversation workspace root).
JWT_SECRET	nomifun-app	Secret used to sign session JWTs. See Auth secret resolution for the resolution order.
NOMIFUN_HTTPS	nomifun-auth::CookieConfig	When truthy, session and CSRF cookies get the Secure flag and SameSite=Strict. Set it whenever the app is reached over HTTPS (TLS reverse proxy, etc.). Default is false → no Secure flag, SameSite=Lax.
SHELL	agent engine (Linux/macOS)	Shell used when the agent engine spawns child processes. On Linux servers under systemd, set this explicitly (the system account often has no $SHELL).
NOMIFUN_URL	nomicore call, nomicore agent	Base URL for a running instance when invoking Remote capabilities.
NOMIFUN_COMPANION_TOKEN	nomicore call, nomicore agent	Companion access token used against /v1 Remote capability routes.

There is no SENTRY_DSN integration: the codebase does not read that environment variable.

Backend constants

Source: crates/backend/nomifun-common/src/constants.rs. These are compile-time values, not environment variables — they are listed here so operators know the limits.

Constant	Value	Used for
DEFAULT_HOST	127.0.0.1	Default --host for nomicore.
DEFAULT_PORT	25808	Default --port for nomicore. (The web host overrides this to 8787.)
BODY_LIMIT	10 MiB	Default request body limit applied to every route. Routes that need more (e.g. /api/fs/upload) install their own larger limit.
UPLOAD_MAX_SIZE	30 MiB	Cap for the file upload route (/api/fs/upload).
REMOTE_IMAGE_MAX_SIZE	5 MiB	Cap for downloading a remote image referenced in chat.
COOKIE_NAME	nomifun-session	Session cookie.
CSRF_COOKIE_NAME	nomifun-csrf-token	CSRF cookie (NOT HttpOnly — JavaScript reads it).
CSRF_HEADER_NAME	x-csrf-token	Header that mirrors the CSRF cookie value (Double Submit Cookie).
COOKIE_MAX_AGE_DAYS	30	Cookie Max-Age.
SESSION_EXPIRY	24h	JWT validity window before refresh is required.
HEARTBEAT_INTERVAL_MS / HEARTBEAT_TIMEOUT_MS	30000 / 60000	WebSocket heartbeat ping/pong.

Data directory and work directory semantics

• data-dir holds the SQLite database (nomifun-backend.db*), per-agent state, the Bun cache, log files, and any embedded extension data. Treat it like any other database — back it up and restrict permissions. Sharing it between two running backends is prevented mechanically (see the server lock below).
• All three hosts (nomifun-desktop, nomifun-web, the standalone nomicore binary) resolve the same default data dir via nomifun_app::cli::default_data_dir(): %LOCALAPPDATA%\NomiFun\Nomi on Windows, ~/Library/Application Support/NomiFun/Nomi on macOS, $XDG_DATA_HOME/NomiFun/Nomi on Linux (usually ~/.local/share/NomiFun/Nomi), resolved via the dirs crate, with <system temp>/nomifun-data/Nomi as the extreme fallback when the OS reports no user directory. One default for every host is deliberate: the dev loops (bun run serve:web, dev:web, dev) and the installed desktop app read and write the same state — a provider or companion configured once is testable everywhere, and troubleshooting only ever has one directory to look at. For an isolated sandbox, point NOMIFUN_DATA_DIR or --data-dir somewhere else.
• At startup (before the database is opened) the backend takes an OS-level exclusive lock on {data_dir}/server.lock. A second backend process on the same data dir fails fast with an error naming the holder (pid + executable) and the two ways out: close the other instance, or give this one its own directory via NOMIFUN_DATA_DIR / --data-dir. The lock is advisory (flock / LockFileEx via fs2) and is released by the OS when the process exits or crashes — a leftover server.lock file is harmless. nomicore doctor and the mcp-* stdio subcommands do not take the lock (doctor is designed to run alongside a live server).
• work-dir holds per-conversation workspaces. When unset, it resolves in this order: --work-dir → non-empty NOMIFUN_WORK_DIR env → the data dir itself. Conversations create subdirectories under <work-dir>/conversations/; deleting a conversation deletes its workspace.
• The desktop shell uses the shared default above. With NOMIFUN_DATA_DIR set, the dir becomes $NOMIFUN_DATA_DIR/Nomi — the override semantics are unchanged. Older builds defaulted to <system temp>/nomifun-data/Nomi; on first launch with the new default, an existing temp-rooted install is relocated automatically (one-shot, the legacy dir is kept as a backup and absolute paths stored in the database are rewritten).
• The web host applies the value literally — --data-dir (or NOMIFUN_DATA_DIR) is used as given, with no /Nomi suffix — so Docker (/data) and systemd (/var/lib/nomifun) deployments are unaffected. With neither set it falls back to the shared per-user default; the old relative data default is gone.

Auth secret resolution

JwtService is constructed from a single secret; AppServices::from_config resolves it in this order:

1. JWT_SECRET environment variable, if set.
2. Otherwise, the value persisted in the system user row (system_default_user.jwt_secret).
3. Otherwise, a fresh cryptographically random secret is generated and persisted to the database for future boots.

The change-password flow rotates the JWT secret as a side effect, invalidating every existing session.

The same secret is also used to derive an encryption key (derive_encryption_key) for at-rest encryption of secrets stored in the database (provider keys, MCP OAuth tokens, etc.).

TLS / HTTPS cookie handling

NomiFun does not terminate TLS itself — put a TLS-terminating reverse proxy (Caddy, nginx, …) in front. When you do:

• Set NOMIFUN_HTTPS=true so cookies are flagged Secure and SameSite=Strict. Without this, browsers reject Secure cookies on HTTPS responses, and login appears to silently fail.
• The WebSocket upgrade at /ws passes through any standards-compliant proxy without extra headers; Caddy handles it out of the box.

See guides/web-server-deployment.md for a worked Caddy + Docker setup.

Logging

• All logs go to both stdout (so journalctl/docker logs capture them) and a daily-rolling file at <log-dir>/nomicore.log.

• --log-level accepts a full tracing EnvFilter directive: a global level, or a comma-separated list of per-target overrides.

  Examples:

  • info — global info.
  • debug — global debug. Verbose; useful for short reproductions.
  • info,nomifun_mcp=trace — info everywhere, trace for the MCP module.
  • warn,nomifun_conversation=info,nomifun_terminal=debug — quieter overall, normal for the conversation engine, debug for terminals.

There is no separate RUST_LOG plumbing — --log-level (or its env-driven equivalent in the running host) is the single switch.

See also

• Web Server Deployment — running nomifun-web with Docker, systemd, Caddy.
• Running NomiFun as a Desktop App — desktop-specific configuration.
• API Overview — what the backend exposes once it is configured and running.
• Troubleshooting — symptoms and fixes when configuration ends up wrong at runtime.