Skip to main content

​
Definitions and runtimes are separate

  • An enabled, validated package enters the Mini App catalog and can be discovered, but that doesn’t start it.
  • Only explicit activation (@ selection, open, publish, restart) starts the service, and it affects only that Mini App.
  • Apps, Skills, and ordinary MCP in the same package publish automatically under ordinary plugin rules, without waiting for the Mini App to start.

​
Starting

1

Copy a runtime copy

The host copies the installed package into a runtime directory it manages and re-checks identity, content digests, and entry location before running it. The process never reads the workspace or the installation directory, so files the Agent is editing don’t affect the running instance until the next publish.
2

Assign a port

Ports come from 49152–65535. The host picks a starting point from a hash of the plugin ID, moves on if the port is taken, and remembers the chosen port to try it first next time.
3

Install the request guard

The child process first runs host startup code, receives an initialization message over IPC and validates every field, installs a request guard on the HTTP servers in the process, and only then loads plugin code; see Ports and credentials.
4

Wait for readiness

After the plugin’s start(context) returns, the host probes twice: a request without the credential must be rejected (401) and one with it must succeed (204). If this doesn’t pass within the startup limit (currently 10 seconds), startup fails.

​
Readiness

A runtime is ready only when the entry’s start(context) has completed, the child process has reported a started message that matches the current run, and the host’s authenticated probe of the assigned port passes (401 without the credential, 204 with it).This catches problems such as bypassing the guard or another process holding the port, but it doesn’t prove the plugin itself is safe. On a port collision, startup retries on another port within a bounded range; other startup errors fail immediately and clean up the process, port, and runtime directory.

​
Updating a running Mini App

Simply stopping the old process and starting a new one could easily interrupt work in progress: the Agent may be waiting on an MCP tool, or the Mini App may be calling a Connector. Since a Mini App can only have one process at a time, the host treats stopping the old process as the dividing line:
Updating a running Mini App

Stopping the old process is the line: before it you can back out, after it there is no going back.

  • Before the stop, the host can back out at any time. It validates the new package, stops the old process from taking new Connector calls, and waits, within a limit, for calls already sent. If any step fails, the update is abandoned, the old process keeps serving, and the action fails (for example with BUSY); retry later.
  • After the stop, there is no going back. The host stops the old process and confirms it exited, copies the new runtime, starts the new process, and lets it take over only after a full readiness check; managed MCP reconnects and the new capability snapshot is committed.
  • If the new process fails to start, the Mini App enters a failed state and the host doesn’t revive the old process. Apps, Skills, and ordinary MCP in the package stay available until the next open, publish, or restart.
Publish, restart, and stop all go through the plugin system’s single operation queue. The capability snapshot switches only when no conversation turn is in progress; a running turn keeps the snapshot it started with.

​
Which changes replace the process

When publishing, the host computes three content digests: the whole package, the page payload, and the Node payload. Changing only a Skill or an ordinary MCP declaration doesn’t replace the running process; only changes to the page or Node payload go through the update flow above. Grants such as agentAccess take effect with the process, so changing them restarts it too.

​
Stopping and exit

  • On stop, the host first disconnects the Host Connector, then asks the plugin to dispose.
  • Exit has to be confirmed: the host waits a 2-second grace period, sends SIGTERM, forces the process to end if it is still running, and waits for the actual exit.
  • If exit still can’t be confirmed, the host marks the plugin unavailable, stops routing requests to its port, and keeps its service slot.

​
Capacity and sharing

  • A Mini App has one Node process at any time. On replacement, the old process must be confirmed exited before the new one starts.
  • At most 3 different Mini App services run at once. Services that are still starting take a slot too, and a slot is released only after exit is confirmed.
  • Cold starts of different Mini Apps run independently and don’t wait on each other.
  • If a Mini App selected with @ needs a slot and none is free, it doesn’t start or open; the user sees a service-limit notice, and the reference stays.

​
Stop, shutdown, and account switching

  • stop ends the process and keeps the installed package, its enabled state, and the package’s Apps, Skills, and ordinary MCP. Later ordinary publishes don’t start it implicitly.
  • When the user signs out or switches accounts, official Mini Apps running under the previous account are retired before the new account can activate them. Refreshing credentials within the same sign-in doesn’t affect running Mini Apps.