Skip to main content

​
Mini App runtime

A Mini App’s Node code runs on your machine as your user, just like local plugins and MCP servers. It can read and write any file you can access, start programs, and make network requests. Install Mini Apps only from sources you trust, and read the README before installing to see what data it accesses.The host doesn’t use operating-system sandboxes such as seccomp or seatbelt, mainly because of their cost to cross-platform support, debugging, and third-party dependencies. Instead, it strictly limits the capabilities it exposes to a Mini App, to guard against poisoned third-party Mini Apps and harmful code from Agent hallucinations.

​
Host security boundaries

​
Ports and credentials

A Mini App listens only on a local address, but other processes and browser pages on your machine can still reach its port, including malicious pages that use DNS rebinding. The host therefore checks the caller’s identity at the port:
Credential flow

The credential passes only between the host, the request guard, and the Agent's MCP client; the page, plugin code, and outside callers can't obtain it.

  • One credential per run. Each time the host starts the process, it generates a random 32-byte credential and gives it to the request guard in the child process, the host main process, and the Agent’s MCP client. The page never holds it.
  • The guard loads before plugin code. The child process receives an initialization message over IPC, and a missing or extra field fails startup. It then installs the guard at the request dispatch entry of Node’s built-in HTTP server, and only then loads plugin code. Every node:http server the plugin creates therefore receives requests only after the guard has checked them.
  • Host and credential checks. Host must equal 127.0.0.1:port exactly, which blocks DNS rebinding, and the credential is compared in constant time. WebSocket upgrades and CONNECT requests are checked the same way. Once a request passes, the credential is removed from its headers before plugin code sees it.
  • The host adds the credential to page requests. When the page sends a request, the host main process checks its real origin and then adds the header, overwriting any header with the same name the page set itself. When the Agent reaches the MCP endpoint, its MCP client carries the credential in request headers, never in visible configuration.
The request guard runs in the same process as plugin code, so it can only stop outside callers from posing as the host; it can’t isolate a malicious plugin.

​
Limits of the Agent API

  • A Mini App can create background sessions, assign tasks, handle tool approvals and questionnaires, and list available models and agents, but no API reads your chat history or inserts messages into your chats.
  • Each Mini App can continue only sessions it created; the host records ownership.
  • These limits apply only to the host APIs; the Node process itself has no operating-system-level isolation.

​
User confirmation

  • message.append needs your confirmation every time, and you send the message yourself. The host checks the caller against the real page that Electron reports.
  • Agent approvals offer only “allow once” and “deny”. A Mini App can’t change your global permission rules, and approvals nobody can answer are denied. See Who can answer an approval.
  • A Mini App can’t read chat history or change sent messages.

​
Known limitations

  • Port authentication only defends against other local processes and browser tabs, not against a malicious plugin itself.
  • The host manages only the entry Node process. The plugin must clean up any child processes it starts in dispose.
  • After a service restart, open tabs get 401 until they are refreshed or reopened.