Configuration

Two config surfaces live in Infinia: user settings (theme, language, sidebar, logging) and AI config (active backend, API keys, models). Both are read and written over REST, and AI config can be hot-swapped at runtime without restarting. Database reconfiguration is also exposed here as a reset endpoint.

All endpoints require the X-FengYu-Token header. See Backend.

User settings

GET /api/settings
  ◄── 200 { "theme": "dark", "language": "en", "sidebarCollapsed": false,
             "logLevel": "INFO", "updateApiBase": "", "computerUseEnabled": true,
             "computerUse": { "available": true, "reason": null } }

PUT /api/settings accepts a partial body — only the keys you include are persisted; the rest stay as they are.

PUT /api/settings
  Content-Type: application/json
  { "sidebarCollapsed": true }

  ◄── 200 { "theme": "dark", "language": "en", "sidebarCollapsed": true, "logLevel": "INFO" }

Key	Type	Meaning
theme	string	"light" or "dark". See Design System.
language	string	UI locale (e.g. en, zh-CN).
sidebarCollapsed	boolean	Whether the sidebar starts collapsed.
logLevel	string	TRACE, DEBUG, INFO, WARN, ERROR, or OFF. Applied immediately to the main application and every Java plugin Worker.
updateApiBase	string	The Settings upgrade channel: the absolute HTTP(S) base URL of the production Infinia Store deployment (plugins, cloud-account sign-in, app updates all route through it). Empty falls back to the bootstrap store base (FENGYU_STORE_API_BASE, production default https://www.infinia.fyi) and GitHub for updates. Intranet store addresses need -Dfengyu.store.allow-private-network=true.
computerUseEnabled	boolean	Master switch for the desktop computer_* screen-control tools (default true). false removes them from the AI catalog on the next turn; input actions always keep the per-turn approval gate.
computerUse	object	Read-only capability probe: {available, reason}. Present only in desktop mode; null in plain web mode.

Changing logLevel does not restart Workers. The host updates its Logback namespaces and sends a built-in JSON-RPC notification to each running Worker; newly launched Workers inherit the same value through FENGYU_LOG_LEVEL.

updateApiBase is the one runtime channel to the separately deployed production store: plugin installs/updates, cloud-account sign-in, and the user-center proxy resolve it per request (StoreEndpointProvider), and /api/store/status reports the effective base. It is also loaded before the desktop window opens, so the automatic startup probe and the manual About → Check for updates action use the same channel. For updates, the store's compat mirror (an APP listing's stable release) serves the Infinia-<version>-win32-x64-portable.zip artifact with a mandatory SHA-256 digest; the lite deb feed keeps the legacy FY-Proxy contract until the store ships an electron-updater feed, and NSIS, AppImage, macOS, JRE, and portable Web/JAR builds continue to use the public GitHub channel and are rejected when pointed at FY-Proxy.

AI config

GET /api/ai/config returns a masked snapshot so you can render the form without exposing raw keys:

• API keys are masked — only the first and last few characters are shown, e.g. sk-1***wXYZ.
• The snapshot also reports activeMode (the current backend) and ready (whether the active backend is usable).

GET /api/ai/config
  ◄── 200 {
        "activeMode": "openai",
        "ready": true,
        "contextWindowTokens": 32768,
        "openai":  { "apiKey": "sk-1***wXYZ", "model": "gpt-4o", "baseUrl": "..." },
        ...
      }

contextWindowTokens controls long-chat compaction. FengYu starts summarizing old rounds at 60% of this value; the default is 32768, and 0 disables automatic compaction. Set it to the selected model's actual context window rather than its output-token limit.

Dynamic tool loading

Every attached tool definition is paid for on every model round, and MCP-heavy deployments can accumulate dozens of kilobytes of schemas. toolLoadingMode controls on-demand tool loading (pi's setActiveTools pattern):

• auto (default) — dynamic loading kicks in only when the visible tool count exceeds toolLoadingThreshold (default 25). At or below it, every tool is sent in full exactly as before.
• always / off — force the behaviour on or off regardless of count.

When active, each chat round attaches only a small cheap core plus the conversation's activation set; the remaining tools are listed by name in the system prompt ("Available tools (on-demand activation)") and activated through the built-in search_tools tool — additive-only, capped at 40 activations per conversation, and re-seeded on follow-up turns from the mirrored results. Calling a not-yet-active tool returns actionable guidance instead of failing the turn. The plan-and-execute agent applies the same gate: above the threshold it first selects tools from a schema-less catalog, then authors the plan against only the selected tools' schemas.

Updating AI config

PUT /api/ai/config takes a partial body. A key insight for round-trips: because GET masks the API key, sending that masked value back would clobber it. To avoid that, any API key string containing *** is treated as "unchanged" and not persisted — so the masked value can be echoed straight back without losing the real key.

PUT /api/ai/config
  Content-Type: application/json
  { "activeMode": "anthropic", "anthropic": { "apiKey": "sk-a***9zzz", "model": "..." } }

After persisting, the backend hot-swaps the active backend via BackendReactivator.reactivate() — no restart needed. The four supported modes are local (Ollama), openai, anthropic, and deepseek (OpenAI-compatible). See AI Chat for what each mode does.

Testing a connection

Before committing a new mode, probe it without saving:

POST /api/ai/config/test
  Content-Type: application/json
  { "mode": "deepseek", "endpoint": "...", "apiKey": "...", "model": "...", "baseUrl": "..." }

  ◄── 200 { "success": true, ... }

Use this to validate credentials and endpoint reachability up front.

MCP clients

FengYu can dynamically add, test, enable, disable, and remove MCP servers from Settings → MCP or through the REST API. STDIO, SSE, and Streamable HTTP connections are established immediately after saving, and discovered tools are added to the live chat and Agent catalogs without a restart.

To connect mcp-chrome:

1. Install its Chrome extension and mcp-chrome-bridge as described by the project, then click Connect in the extension.
2. Open Settings → MCP in FengYu and click Add Chrome MCP.
3. Save the prefilled Streamable HTTP configuration: http://127.0.0.1:12306 with endpoint /mcp.

The official mcp-chrome client URL is http://127.0.0.1:12306/mcp. FengYu accepts either the host URL plus /mcp endpoint or the complete URL in the address field.

For a Codex-style STDIO server file, Spring AI startup configuration remains available:

java -jar FengYu-*.jar \
  --spring.ai.mcp.client.stdio.servers-configuration=file:/absolute/path/mcp-servers.json

Tools are namespaced per server as <server>__<tool> (the detail page shows the exact prefix), so Mcp(...) permission rules can target one server and two servers may expose the same tool name. Each server can disable individual tools for the AI catalog — by bare name, wire name, or a prefix* / * wildcard — and carries its own request and initialization timeouts (5–600 s, default 30 s). Interpreter-injection environment keys (NODE_OPTIONS, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*, JVM variants) are stripped from STDIO configurations.

Plugins installed from Claude, Codex, or Grok marketplaces that declare mcpServers appear in Settings → MCP as disabled servers tagged with their plugin. Test one on demand; enabling it opens an informed confirmation showing the exact command or URL plus imported credential names. Only that explicit confirmation adopts it into the user-managed registry (an adopted server survives the plugin's uninstall). Imported HTTP declarations must use a global HTTPS target; loopback/private-network targets must be entered manually by the user.

Inspect connections with GET /api/mcp/status and GET /api/mcp/servers. Configuring an external STDIO command is explicit authorization to launch that command, so only use trusted server definitions and keep credentials in protected local configuration.

datasource.properties layout

The database connection is persisted separately from AI config, at <program-working-directory>/.fengyu/config/datasource.properties, with keys:

Key	Meaning
db.type	One of H2, SQLITE, MYSQL, POSTGRESQL.
db.url	JDBC URL.
db.driver	JDBC driver class.
db.dialect	Hibernate dialect.
db.username	DB username.
db.password	DB password, AES/GCM encrypted (see Database).
db.file.path	For embedded backends, the file location.

db.password is encrypted with a machine-bound AES/GCM key derived from the local .machineid, and stored wrapped as ENC(...). See Database — Password encryption.

Reconfigure the database

POST /api/settings/database/reset
  X-FengYu-Token: <token>

This backs up the current datasource.properties, clears it, and restarts the backend into SETUP mode so the first-launch wizard can collect new parameters. Functionally equivalent to deleting datasource.properties and restarting manually — see Database — Reconfigure.

Secret storage at rest

Local secrets (the datasource password, AI provider API keys, MCP server credentials) are encrypted with a machine-bound key before they are written to disk. By default that key is a random value stored at .fengyu/config/.machineid — this binds every encrypted value to the machine (a stolen config file is useless elsewhere) but does not protect against a reader running as the same OS user.

Deployments that keep secrets in the operating system's credential store can inject the key instead of using the file. Set FENGYU_MACHINE_KEY (system property or environment variable, 16+ characters, stable across restarts) before launching the backend — for example from the macOS Keychain:

export FENGYU_MACHINE_KEY="$(security find-generic-password -s FengYu -a machine-key -w)"
java -jar Infinia.jar --token=...

Equivalent lookups: secret-tool lookup fengyu machine-key on Linux, or a Credential Manager read in the Windows run script. Every encrypted value is bound to the injected key — switching or losing it makes the stored ciphertexts undecryptable (reset them via the settings UI). While FENGYU_MACHINE_KEY is set, the .machineid file is not used or created.

Next steps

• Database — the first-launch wizard and the four backends.
• AI Chat — using the backend you just configured.
• REST API — the full endpoint reference.