MyAiDesk/nomifun-tauri/docs/guides/remote-capability-api.md

Remote Capability API

NomiFun can expose its platform capabilities through a network-reachable, token-authenticated MCP and REST front door. A trusted external agent or MCP client can connect with a URL plus a companion access token and then call the same capability registry used by the desktop app.

Each token is bound to one companion. Calls made with that token run as that companion and inherit its profile model, persona, and knowledge context.

For copy-ready integrations, see Remote Capability API Examples.

Security Model

A companion access token is high privilege. It can drive agents, read and write files through exposed tools, and in desktop builds may operate browser or computer-use capabilities. Treat it like remote code execution authority:

• Give tokens only to clients and agents you trust.
• Prefer loopback, VPN, or a private network.
• Put TLS, firewall rules, and rate limits in front of any public exposure.
• Rotate or revoke tokens immediately if they leave your control.
• Sensitive tools such as secrets and factory reset are not exposed on the remote surface by default.
• Destructive tools require a confirmation retry: the first call returns a confirmation challenge; the caller must show the action to the user and retry with confirm: true.

Endpoints

The network front door is mounted by the same backend process as the Web UI.

Endpoint	Purpose
/mcp	Full Streamable-HTTP MCP server.
/mcp-agent	Curated MCP profile for external working agents.
/v1/tools	REST tool discovery. Add ?profile=agent for the curated set.
/v1/tools/{name}	REST tool call.
/v1/tools/{name}/stream	SSE streaming wrapper for tools that emit progress.
/v1/openapi.json	OpenAPI 3.1 description for the REST tool surface.

Authenticate every request with:

Authorization: Bearer <companion-access-token>

Common base URLs:

• Desktop remote access: http://<LAN-IP>:25808
• Standalone server: http://<host>:8787 unless you changed the port
• Local development or embedded desktop backend: http://127.0.0.1:<port>

Creating A Companion Token

Tokens are stored hashed. The plaintext token is shown only once.

Desktop App

Use the Open Capabilities / remote access UI, or call the trusted local API from the desktop WebView context:

curl -X POST \
  http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token

The response returns the plaintext token once:

{
  "success": true,
  "data": {
    "token": "<64-character-hex-token>",
    "companion_id": "<companion-id>"
  }
}

Status and revoke use the same path:

curl http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token

curl -X DELETE \
  http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token

These token-management endpoints require local trust. A remote browser or plain curl client cannot mint tokens.

Headless nomifun-web

Seed a token at startup with NOMIFUN_COMPANION_TOKEN. The value binds to the default companion when no token is already configured:

NOMIFUN_COMPANION_TOKEN="$(openssl rand -hex 32)" \
  nomifun-web --host 127.0.0.1 --port 8787

Use the generated hex string as the Bearer token. For non-local exposure, finish admin setup first and put the server behind TLS.

MCP Client Configuration

Example Streamable-HTTP MCP configuration:

{
  "mcpServers": {
    "nomifun": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:25808/mcp-agent",
      "headers": {
        "Authorization": "Bearer <companion-access-token>"
      }
    }
  }
}

Use /mcp-agent when an external agent mostly needs work tools (agent/browser/computer/knowledge/files). Use /mcp when you intentionally want the broader platform control surface.

REST Tool Calls

Discover tools:

curl -s "http://127.0.0.1:25808/v1/tools?profile=agent" \
  -H "Authorization: Bearer $TOKEN"

Run a delegated NomiFun agent task:

curl -s -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":"Research competitors and write notes.md","timeout_secs":600}'

Poll a long-running task:

curl -s -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_result" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":123}'

Successful REST calls return 200 {"result": ...}. Tool validation failures return 422, unknown tools return 404, invalid tokens return 401, and confirmation-required calls return 409.

Streaming

SSE streaming is available for tools that report progress:

curl -N -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_run/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":"Summarize the current repository"}'

Each event is a data: <json> line. The final event uses {"type":"__result__","data":{"result":...}}.

Companion Context

Because the caller runs as the bound companion, nomi_agent_run can use that companion's configured model when no model argument is supplied. Configure a usable provider/model for the companion before relying on model-backed tools; token creation may warn if the companion has no usable model.

Related Docs

• Remote Capability API Examples
• WebUI Remote Access
• Web Server Deployment
• Computer Use And Browser Use