In MiniMax Code, Mini Apps and sessions relate as follows:
One backend per Mini App: Each Mini App starts only one Node process. Whichever session you call it from, you reach the same backend and read and write the same data.
Pages are isolated per session: Each session has its own Mini App tab, but within one session a Mini App opens in only one tab.
Sessions a Mini App starts are private to it: Sessions a Mini App starts through the Agent API don’t appear in the chat list on the left; only that Mini App maintains and continues them.
One service per plugin, one page per session; Agent sessions a Mini App starts belong to that Mini App.
There are three ways: pick it from the right panel’s ”+” menu, @-mention an installed Mini App in the input, or let the Agent call open. The page always opens in the session that started the action.
Situation
What happens
A Mini App reference appears in an existing session’s input
The backend starts or is reused right away, and the sidebar expands only after the page opens; a failed startup never shows an empty panel. Selecting with @, clicking “Use” in the marketplace, and restoring a draft with a reference all count
A new conversation on the home screen
Only the backend starts. After the first send creates the session, pages open for Mini Apps that are still in the message and started successfully
Opening or @-mentioning it again in the same session
The existing tab is reused, keeping the current route and state instead of jumping back to the start page; it navigates only when path is given explicitly
Plain-text @xxx and message history
Never start the service or open a page
Cloud, SSH, and Remote Control sessions
Never start or open Mini Apps on your machine
Once opening has started, removing the reference, cancelling the message, or switching sessions doesn’t withdraw it. The page stays in the session that requested it until you close it.
The session list on the left marks sessions that have a Mini App open, so you can get back to the right workspace.
When sessions A and B open the same Mini App, both pages talk to the same Node service and read and write the same dataDir.
A change made in session A shows up on session B’s page only after a refresh or a pushed update. Authors should route every write through the Node business service and push SSE or WebSocket events after committing; see State and persistence.
Removing an @ reference from the input doesn’t stop the shared service.
Closing a running Mini App’s tab and confirming stops its shared service and closes that plugin’s pages in every session.
At most 3 different Mini App services run at once, and referencing a Mini App that is already running doesn’t take a new slot. If you @ a Mini App that needs a new slot and none is free, it doesn’t start or open; you see a service-limit notice and the reference stays. Select it again once a slot frees up.
After a service restart, refresh or reopen an open tab to recover.
Managed MCP tools: while the Mini App service runs, the Agent can call the tools it exposes. Tools follow the service, not any session’s page.
Ready before sending: when a message references a Mini App, the host starts its service, connects MCP, and confirms the tools are available before calling the model. If a required managed MCP is unavailable, the request fails instead of letting the model continue without its tools.
No implicit starts: the host never starts a Mini App because of message history, quoted messages, or model output.
Looking at the page: the Agent can inspect the Mini App page open in the current session with the built-in browser. That is how screenshot acceptance works when building with /miniapp-creator.
message.append always targets the session the page belongs to. It never writes to another session or the home draft, and never creates a session.
It only appends to local, writable sessions. If the session is deleted, becomes read-only, or switches to cloud or Remote Control, the call rejects with target_unavailable instead of writing somewhere else.
It can append to the session’s draft even when that session isn’t in the foreground.
Every append needs your confirmation, and you press Send yourself.
A Mini App that declares agentAccess can start Agent sessions through the Agent API. These are separate from your chat sessions:
Page-initiated
Node-initiated
Linked chat
The session the page is open in
None
Agent
That session’s agent
The primary agent, or one chosen at creation
Working directory
That session’s project directory; without one, this Mini App’s own Agent directory
This Mini App’s own Agent directory
Model
That session’s model and thinking level at creation
The runtime default model
These sessions don’t appear in your session list. Each Mini App can continue only sessions it created.
The agent is fixed at creation; create a new session to use a different agent.
The model is captured at creation and then decoupled from the chat: switching models in your main chat doesn’t affect the Mini App’s session. run and answer can switch models explicitly.
A session the page creates with create can be handed to Node by passing its sessionId, and Node continues it with run({ sessionId }).
When the page calls open(sessionId), the Agent session appears in the current chat’s side panel, where you can follow it, approve tool calls, and answer questionnaires.
The page can open any session this Mini App owns, including ones Node created.
One session can show in the side panels of several chats at once; it counts as unanswerable only after all of them close.
Tool approvals wait only while someone can answer: the call passed onEvent, or the session is showing in a chat side panel. The chat a session was originally created from doesn’t count. Approvals nobody can answer are denied, and the model is told to continue without that tool.
Reloading or closing the host window counts as closing the panel. After the chat is deleted or the runtime restarts, the page needs to call open again.
A popped-out window still belongs to the original session’s tab. Closing it, or pressing Cmd/Ctrl+W, returns the page to its file panel.
The window’s visibility doesn’t follow the main window: hiding, minimizing, or closing the main window to the tray leaves popped-out windows as they are.
When the Mini App stops, the page closes, or the app quits, the window closes with it.
When the same sign-in refreshes its credentials, running Mini Apps, managed MCP, and tools stay as they are.
After you sign out, Host Connector tool lists and authorized references are revoked. Sign back in with the same account and the Mini App lists its tools again to keep working, with no republish.
When you switch to a different account, official Mini Apps running under the old account are retired before the new account can activate them. Local Mini Apps keep running, but their Connector access from the old account is revoked for good; restart the service to use Connectors under the new account.
