MyAiDesk/nomifun-tauri/docs/architecture/communication.md

Communication

NomiFun has several transport surfaces. They deliberately serve different callers and security models.

Channels

Channel	Direction	Carries	Source
HTTP REST	UI/browser/client -> backend	CRUD, commands, setup, file operations, terminal input	nomifun-app route tree
WebSocket /ws	backend <-> UI	Agent stream events, terminal output, broadcast events, heartbeats	nomifun-realtime
Tauri IPC	SPA -> desktop shell	Desktop-only OS features	apps/desktop/src/main.rs + Tauri plugins
ACP/agent stdio	backend <-> child CLI	External CLI-agent conversation traffic	nomifun-ai-agent
MCP stdio/HTTP	agent/backend/client <-> MCP server	Tools/resources/prompts	nomi-mcp, nomifun-mcp, nomifun-public, bridge subcommands
Public Remote fronts	external agents/scripts -> backend	MCP tools or REST capability calls	/mcp, /mcp-agent, /v1

Auth Modes

The backend resolves trust through nomifun-auth and the AppServices configuration:

• Required: normal web mode. Login cookie is required for /api/*; CSRF protects state-changing cookie-authenticated requests.
• NoAuth: explicit insecure mode, used only through flags such as --insecure-no-auth for trusted loopback/private use.
• TrustLocalToken: desktop shell mode. The webview gets a per-boot secret and sends it as x-nomi-local-trust; middleware resolves that request to the trusted local user. This is not the same as the old blanket --local story.

WebSocket auth accepts the normal authenticated browser path and the local-trust path used by the desktop shell.

HTTP And WebSocket

The SPA bridge in ui/src/common/adapter/httpBridge.ts selects:

• same-origin URLs for nomifun-web,
• http://127.0.0.1:<window.__backendPort> for the desktop webview.

/ws is a singleton connection per page lifetime. The backend event bus fans conversation, terminal, cron/requirement, channel, companion, and other events into the WebSocket manager.

Tauri IPC

Rust commands currently registered by the desktop shell include:

• check_for_updates
• sync_companion_windows
• webui_get_status
• webui_start
• webui_stop
• set_keep_awake
• set_tray_labels

The renderer also uses Tauri JS APIs/plugins for window, dialog, notification, process, autostart, deep-link, updater, and path operations where appropriate.

MCP And Agent Bridges

The current nomicore CLI subcommands include:

• mcp-requirement-stdio
• mcp-knowledge-stdio
• mcp-gateway-stdio
• mcp-open-stdio
• mcp-computer-stdio
• mcp-browser-stdio
• terminal-hook
• doctor
• tools
• call
• agent

Older docs that mention mcp-bridge, mcp-guide-stdio, or mcp-team-stdio are historical and predate the current bridge set.

MCP injection differs by runtime:

• user MCP rows and OAuth-backed HTTP servers come from nomifun-mcp,
• requirement and knowledge servers are scoped internal MCP servers,
• Desktop Gateway tools are exposed through nomifun-gateway,
• browser/computer bridges are feature-gated,
• public /mcp and /mcp-agent are companion-token authenticated fronts from nomifun-public.

Public Capability Fronts

The full app router mounts three companion-token authenticated surfaces outside the normal /api browser-auth tree:

• /mcp: general MCP profile for a companion identity,
• /mcp-agent: curated agent profile,
• /v1: REST capability adapter, with optional agent profile selection.

Tokens are per companion. A caller acts as that companion and inherits the associated profile, model/persona choices, and scoped capabilities.

Quick Lookup

Operation	Transport
Login/setup	HTTP /api/auth/*
Conversation send	HTTP /api/conversations/* plus streamed /ws events
Terminal input	HTTP terminal route; output over /ws
Desktop keep-awake	Tauri command
Remote MCP tool call	/mcp or /mcp-agent
Remote REST capability call	/v1
Agent CLI conversation	child process stdio managed by nomifun-ai-agent
Internal knowledge search for ACP session	mcp-knowledge-stdio bridge