MyAiDesk/nomifun-tauri/docs/skills/drive-nomifun/SKILL.md

name, description

name

description

drive-nomifun

Use to connect to and drive a NomiFun instance from an external agent (Claude Code / Cursor / any MCP client). Delegate goals to NomiFun's autonomous agent, drive its browser / computer / knowledge base / files, and manage the platform — over MCP or REST, with a per-companion access token (you run AS the bound companion). Use this whenever the user asks to control, automate, or hand work off to "NomiFun", "their NomiFun", "the desktop companion", or a running NomiFun server.

Drive NomiFun (external companion)

NomiFun exposes its full platform capability set — an autonomous agent, browser automation, computer control, knowledge bases, files, terminals, and platform management — to external callers through one MCP endpoint and an equivalent REST API, authenticated by a per-companion access token. Each token is bound to one specific companion: calling with it runs you as that companion, inheriting its profile model / persona / knowledge bases. Connecting makes you an "external companion": you drive the platform exactly as its built-in desktop companion does.

1. Connect (MCP, recommended)

Configure NomiFun as a Streamable-HTTP MCP server:

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

• <host> is the machine running NomiFun (127.0.0.1 locally, or its LAN/public address with WebUI remote access enabled).
• /mcp-agent advertises a tight, curated tool set for getting work done (agent delegation, browser, computer, knowledge, files). Use /mcp instead for the full platform-control surface (~140 tools incl. channels, companions, cron, providers, …).
• <token> is a per-companion access token — it binds you to one companion. Get it from the NomiFun operator: in the desktop WebUI/remote panel, or by minting one (see "Minting a token" below). The companion you bind to must have a configured model for nomi_agent_run (and other model-backed caps) to work — otherwise minting returns a warning and those calls fail until a model is set in Model Management.

REST equivalent (for scripts): POST http://<host>:25808/v1/tools/<name> with the same Bearer token; GET /v1/tools?profile=agent lists tools; GET /v1/openapi.json?profile=agent is a machine-readable contract.

Minting a token (operator, local-trust only)

The mint/query/revoke endpoints are local-trust gated (reachable only from the desktop client / loopback, not from a remote browser). {id} is the companion id you want the token bound to:

# Mint — returns the plaintext token ONCE, bound to that companion.
curl -X POST http://127.0.0.1:<port>/api/webui/companions/<id>/access-token
# => { "token": "<64-hex token>", "companion_id": "<id>" }
#    If that companion has no usable model yet, the body also carries
#    "warning": "…" (the token is still minted, but nomi_agent_run etc. will fail
#    until you configure a model).

# Query whether one is configured (does NOT return the token):
curl http://127.0.0.1:<port>/api/webui/companions/<id>/access-token
# => { "configured": true }

# Revoke:
curl -X DELETE http://127.0.0.1:<port>/api/webui/companions/<id>/access-token

For a headless server, seed a token at startup via the NOMIFUN_COMPANION_TOKEN env var — it binds to the default companion (only if no token is configured yet; it won't overwrite an existing one):

NOMIFUN_COMPANION_TOKEN="$(openssl rand -hex 32)" nomicore   # or nomifun-web

2. Delegate a goal (the headline move)

To hand a whole task to NomiFun's own autonomous agent, call nomi_agent_run:

{ "goal": "Research X and write a summary to notes.md", "timeout_secs": 600 }

It spins up a fresh autonomous NomiFun agent (full tools, using the bound companion's profile model — which must be configured), runs the goal to completion, and returns { "status": "completed", "text": "<final answer>", "conversation_id": <id> }. For long tasks it returns { "status": "running", "conversation_id": <id> } — poll nomi_agent_result with that conversation_id until completed.

3. Or drive capabilities directly

Use individual tools when you want fine control: nomi_browser_* (navigate / observe / act), the computer tools, nomi_knowledge_* (search / read / write knowledge bases), nomi_fs_* (read / write / browse files), nomi_create_terminal, and the conversation tools. GET /v1/tools (or MCP tools/list) is the live, authoritative catalog with JSON Schemas.

4. Confirmations & limits

• Destructive actions (deletes, etc.) return { "needs_confirmation": true, "restate": "..." }. Restate the exact action to the user, get agreement, then re-call the same tool with "confirm": true.
• Sensitive actions (secrets, factory reset) are denied on this surface.
• Trust model: holding a per-companion access token grants full, RCE-equivalent control of that NomiFun instance (as the bound companion). Treat the token as a high-value secret; only connect to instances you are authorized to drive. Revoking a token affects only its companion; other companions' tokens are unaffected.

5. Failure handling

• 401 → missing / invalid / revoked access token.
• REST 409 (or needs_confirmation in the body) → re-call with confirm: true.
• REST 422 / a { "error": ... } body → the tool rejected the arguments; check the schema from /v1/tools and retry.
• Connection refused → NomiFun isn't running or the URL/port is wrong.