Security Posture
This page records MindRoom's security model, the file_access setting, and the behaviors that are intentional.
Use it to explain what an agent's tools can reach and to check a suspected vulnerability before reporting or fixing it.
If a finding contradicts an intentional behavior below, do not change the code; raise the posture with the maintainers and explain which scenario it fails to protect.
Trust model
A worker container, reached through the sandbox proxy, is the only security boundary between an agent and the MindRoom runtime.
Tools that run arbitrary programs cannot be confined inside their own process, because a program started by a shell or Python tool ignores any in-process path or command check.
MindRoom therefore never filters the paths, commands, or imports of code-execution tools as a security measure; it isolates them only by routing them to a worker with worker_tools.
An agent whose code-execution tools run in the primary process is trusted with everything that process can reach, so restricting its other tools protects nothing.
The shell tool refuses commands in the primary process unless defaults.allow_shell_without_worker records that trust; python and the other code-execution tools have no such setting.
An agent whose code-execution tools run in a worker must not reach more through its primary-process tools than its worker can.
Tools such as browser, attachments, matrix_message, gmail, and google_drive run in the primary process by default even then, so they follow the agent's file_access setting, which by default keeps them inside the agent workspace.
Which Matrix user may drive an agent, act in a room, or approve a change is a separate question governed by access policy and requester authorization.
An agent or team mentioned in another entity's reply acts for the human or configured bot account that requested that reply, so neither can reach an entity whose access excludes them by asking a different entity to mention it.
Work no person started, such as a shared agent's automation run and the delegations, todos, mentions, and schedules that mention another agent it makes, acts as that agent's own account, which every other agent and team admits only through its own access.
When an agent-created schedule that mentions no agent reaches one of several responders through a router hand-off, the hand-off drops the managed requester, so the target checks the router's account, which the default access admits because the router joins every managed room.
Protecting the primary from worker code
Hardening that protects the primary runtime and other tenants from untrusted worker code is always in scope. Examples are symlinks or files planted in shared workspaces that the primary later follows, worker-writable metadata the primary trusts, Git config the primary executes, and secrets mounted or passed into workers.
Config and state kept out of workers
Runners and dedicated workers never receive the primary's config file, its directory, its .env, a ConfigMap holding it, or the credential encryption key.
Neither Docker nor Kubernetes backend settings reach a dedicated worker's startup manifest; Kubernetes passes only its storage-subpath prefix, which the runner needs.
Credentials the primary's environment declares (provider keys, GITHUB_TOKEN, credential seeds) are read only by the primary, under the credentials saved in its store, and never stored; every runner establishes runner mode at startup and never reads them, and a worker receives one only as a granted mirror copy or in a per-call credential lease.
OAuth app client configurations (*_oauth_client) live in the primary's own store for every worker scope, so a worker's store never supplies one.
A secret tool setting the primary reads from its .env configures only the toolkit the primary builds; a worker-routed call rebuilds the toolkit from its leased saved settings and the worker's own environment.
A Docker dedicated worker's environment includes the non-secret startup names it receives from the primary's environment and .env, so the tool settings among them, AWS_REGION, AWS_DEFAULT_REGION, AWS_PROFILE, GOOGLE_CLOUD_PROJECT, and GOOGLE_CLOUD_LOCATION, also configure the toolkit it rebuilds.
The config sent to runners with each request, and the config file projected into each Docker worker, hold only the fields runners resolve; models, MCP servers, plugin settings, and every other section stay in the primary, and a worker-routed call carries only the called tool's own inline overrides.
Of the agents' data, dedicated Docker and Kubernetes workers mount only workspaces and shared directories, never the agent state roots around them, so sessions, memory, Mem0 data, and private-instance identity records stay out of every worker.
The Kubernetes static_runner sidecar still mounts agents, private_instances, and shared_directories read-write, so records the primary treats as authority live below the primary-only tracking/ directory instead: the invited-room and pending-invite ledgers, personal-room records, conversation modes, auto-approve windows, the shared-directory membership ledger, the contacts store, and the primary's copy of each private-instance owner record, together with their locks.
Agent and private-instance conversation databases stay in those directories, so opening a conversation store refuses a sessions directory or database file that is a link; the store's later operations do not check again (see Known gaps).
The runtime images link SQLite 3.53.3 or later instead of Debian's 3.46, which plays back a journal file planted beside a database and deletes whatever file the journal names as its super-journal; the newer library deletes only real super-journals, so a journal written beside a database the primary opens through Python's sqlite3 cannot make the primary delete other files.
Team memory lives in team_memory/, which no worker mounts; the one-time merge of the per-member team copies earlier releases kept below agents/ reads file copies without following links, and opens only the Mem0 stores the runtime itself opens, and only when they hold nothing but directories and regular files.
It merges a team's copies only from its members, the stores each member read, so what any member's copy held, including anything that member's dedicated worker wrote there while releases mounted its state root, becomes the team's memory, which each member reads through its own backend.
Every team's Mem0 records share one store, so the merge moves only records of the embedding size the team store's own records or the configured embedder give, never a size read from a worker-writable member store, and a planted record of another size cannot make that store refuse other teams' records.
The one-time conversions of a database from an earlier release read its rows as untrusted input and write its .pre-storage-v2 or .pre-storage-v4 backup without following links, so worker code that tampers with a database can break only that agent's or team's history.
The thread exporter writes into a private instance only for the requester that the primary's owner record names, so an owner record planted in private_instances gets no export.
Automations likewise run for a private instance only as the requester that record names, and post only in that requester's personal room, so their replies quoting private files never reach another room.
The knowledge graph database lives in the primary-only knowledge_graph/ storage directory, and its embedded server opens no TCP port and listens on a Unix socket in a private temporary directory of the primary, so no worker can reach it.
Knowledge indexes, including private agents' indexes and their publication and refresh-status files, live in the primary-only knowledge_db/ storage directory, like knowledge Git directories, so no worker can write the index files the primary opens.
The Slack app's credentials (slack_app: bot token, signing secret, and app-level token) and each person's Slack user token (slack_oauth) stay in the primary runtime: slack always runs there, and slack_app can never be granted to a worker through worker_grantable_credentials.
Egress broker secrets (credential services named egress_*) are stored in primary-only credential stores and never reach worker-writable locations, matching the placement of primary-built tool settings.
When the broker is enabled, the shell calls and worker-routed python calls of agents with the egress_credentials tool receive a signed proxy token in their environment, and the broker injects the configured secret when such a request matches a service rule; other agents' calls get no token and no secret.
Worker code can read its own proxy token, but the token only authorizes that worker's scope and expires after MINDROOM_EGRESS_BROKER_TOKEN_TTL_SECONDS (default 7 days), so a leaked token exercises only that scope's configured services until it expires.
Broker refusals never carry a secret, token, query string, or connect link, but they name a shared agent's credential managers, so worker code can read those Matrix IDs.
Agents without a worker scope all share the global store, so a token from any of them reaches the same global keys.
A service can also take its secret from an OAuth account that a user connected (GitHub, Google, Atlassian) when no API key is stored for the scope, and an explicit key always wins over the account.
The broker uses such an account for a service only after someone allowed Agent Keys to use it, an opt-in kept primary-only beside the connection, so connecting an account for its tools, whose writes may ask for approval, never by itself lets an agent's commands act as it.
A user's own service on a personal agent can instead have an account of its own (oauth_separate_account), stored and allowed the same way beside the tools' connection, which the provider's tools never use.
An opt-in allowed read only, for a service that declares read_only, gets the token only for GET, HEAD, and POST to the service's listed read paths, and never for a WebSocket upgrade or a request with a method-override header; that limit holds only as far as the upstream API keeps its writes off those methods and paths.
A group sign-in on the Connections portal (Connect all) stores one token per member service, and each token carries every scope of that sign-in, so an Agent Keys allowance for one member acts with the whole grant on the hosts that service allows.
The primary fetches and refreshes those access tokens through the OAuth credential lifecycle and the broker injects them as the matched rule's auth type; workers never receive an OAuth access token or a refresh token, only the proxy token and placeholder values, and the broker's logs and audit records never contain them.
Account scope follows each provider's own policy: GitHub and Atlassian are requester-scoped, so a worker's requests use the requester named in its verified proxy token, while the Google providers, and Atlassian connections registered with requester_scoped=False, follow the agent's worker scope.
The broker uses a requester-scoped account only on user and user_agent workers that run on a dedicated (Docker or Kubernetes) worker backend by default.
A shared or unscoped worker, and every worker on the static runner, runs every requester's commands in one sandbox, where a later command from another user can read an earlier caller's proxy token (for example from the environment of a process left running) and act with that caller's account until the token expires, so there the broker injects no requester-scoped GitHub or Atlassian account, adds no placeholder for it, and offers no connect link.
A service's oauth_on_shared_workers: true removes that gate: every user of such a shared sandbox can then act with any other user's connected account until that user's proxy token expires.
The connect_url that a 403 response carries goes only to the worker whose proxy token has that scope; it is the same short-lived single-use connect link that conversation OAuth uses, and it starts a connection for that one scope after the recheck of the requester's permission.
The link also requires the browser to be signed in to MindRoom as that requester.
A shared-scope link would skip that sign-in, and any process in a shared worker could read it, so the broker never puts one in a response; users of a shared agent connect its account from the egress pages instead.
A shared Google service account (GOOGLE_SERVICE_ACCOUNT_FILE) is never injected, so the broker cannot be used to spend it.
On the shared static runner, including the hosted static_runner sidecar, a scoped call's broker token, valid for the token TTL, lives in a process shared with other users' calls, consistent with the static runner not being an isolation boundary; use dedicated user or user_agent workers on private agents when requesters must not be able to use each other's brokered credentials (see Shared workspaces on non-private agents), because a dedicated shared or unscoped worker also runs every requester's commands in one sandbox.
Only administrators and an agent's credential managers can change the keys, services, account connection, and account opt-in of a shared or unscoped agent.
Besides the Agent Keys pages, a MindRoom Chat client session can set a key through an agent's secret request card, under the same rule and only for the scope and service the card names.
The credential managers of one key scope, and of all unscoped agents, can change each other's keys and services (see Egress Broker Design Decisions).
Users can define egress services of their own, which apply only to their own scope, route only that scope's keys and accounts, never widen the administrator's policy, and cannot take a config service's name or set oauth_on_shared_workers, admin_key, agents, or github_app.
A github_app service's tokens are minted in the primary from the App private key named by a stored credential, which the primary reads and workers never see; the tokens cover only the listed repositories, and GitHub enforces that scope.
Every scope a github_app service serves shares its tokens, so code in any of those sandboxes can revoke the current token or use up the installation's rate limit for all of them until the next mint (accepted; see GitHub App).
An administrator key (admin_key) is one key in the global store for every scope of a service, which only administrators set from the dashboard; a service's agents list limits which agents get its key or account, but not which code can use them where agents share a sandbox, such as the static runner or a requester's user agents (see Limiting a service to some agents).
A user service can use a connected account only in a personal scope, and its placeholder variables are limited to credential-like names and plain values, because a shared agent's services set variables in every requester's sandbox.
restrict_to_rules is not a network boundary: under passthrough a worker can reach the same server by IP address through a tunnel the broker does not intercept, which carries no credential, so the real boundary stays the token's own permissions on the upstream side.
The risks the broker cannot prevent (code in the primary process, write access to the config, agents with the egress_credentials tool acting with their scope's full keys and allowed accounts, hosts that echo requests, wildcard rules on shared hosting domains, keys that can create other keys, and shared workspaces on user and user_agent agents that are not private) are listed in What the broker cannot protect against.
The egress broker listener (when MINDROOM_EGRESS_BROKER_PORT is set) is a worker-reachable primary runtime surface: workers must reach it to make brokered requests, so it must be accessible from the worker network (Docker docker0 interface or the Kubernetes broker Service).
The hosted static_runner sidecar shares the primary pod's network instead, so there the broker binds only loopback (127.0.0.1) and is reachable from no other pod.
The broker port must not be published beyond the worker network, because a leaked token could otherwise be used from arbitrary network locations until it expires; expired tokens get 407.
Firewall rules and network policies confine the broker port to worker-originated connections only.
Testing and review of the egress broker
The broker's transport around ssl, h11, and cryptography, and its path checks, are hand-written and covered by tests, including a request-smuggling corpus and fuzzing, but have had no independent adversarial review.
A human penetration test of the proxy core is recommended before the broker is exposed widely.
Workspace mounts by worker scope
Worker scopes lists the workspaces each dedicated worker mounts.
A user worker mounts several agents' workspaces, so code working in one of them can read and write the others.
A shared directory lives at shared_directories/<owner>/<name>/ and mounts read-write into its owner's dedicated workers and read-only into each member's.
No dedicated worker mounts shared_directories/ or an owner directory below it, so worker code cannot replace a directory another worker mounts; the primary creates and empties these directories through no-follow descriptors, reads and writes files there only through the path tools' no-follow confinement and atomic writes, and indexes a knowledge base configured inside one without following links.
Primary-process file and coding reach shared directories only when no worker is configured, because worker code writes them and these tools list and search by path after checking it.
For the same reason the primary never runs Git for a knowledge base inside a shared directory.
A workspace or shared directory is mounted only when it is a real directory reached from the storage root without links.
Because Docker resolves mount targets again on every container start, a worker whose mount target inside its writable root was replaced with a link by worker code is refused when it is created or restarted.
Assigned knowledge outside the workspace reaches a worker only when its configured path is a real directory or file, reached without links, outside every directory other workers write, or inside a shared directory that worker already mounts.
Kubernetes mounts such knowledge read-only, because kubelet follows links inside the volume when it mounts, and Docker copies it into the worker's read-only config snapshot through no-follow descriptors.
Workspace files the primary reads and writes
The primary treats everything inside a mounted workspace as worker-controlled.
Files it reads or writes there, such as skills, subagent profiles, context files, workspace template copies, delegation records, knowledge sources, call transcripts, callback scripts, script-run snapshots, todo templates, scheduled-run receipts, workspace knowledge links, thread exports, the files prompt_curation measures, the memory files, staging copies, reports, verdicts, and thread-export index.json files dreaming reads, and the files chat clients list, read, and save through the workspace file routes, are reached from the workspace root without following links, never written through a file that has another hard link, opened non-blocking so a FIFO cannot stall the primary, and published by atomic replacement or exclusive creation.
The primary never takes a file lock inside a workspace, because worker code could hold it forever.
dreaming writes each run's agenda, staging copy of memory/, and patch under .mindroom/dreaming/runs/, and deletes finished staging and old runs without following links.
It writes an approved proposal into memory/ from bytes worker code staged, which gives the agent nothing it could not write itself; it writes only Markdown under memory/ other than today's daily note and context files, and keeps its progress below tracking/, outside the workspace.
Delegation records keep their working state below tracking/, and the run.json, events.jsonl, and transcript.md in the child's workspace are exports the primary never reads.
Worker code that makes one of those exports or the caller's receipt unwritable only leaves the record's exports or the receipt stale; the delegation still records its events and settles.
In the primary, mindroom_output_path, attachment saves, Google Drive, Microsoft Files, Outlook mail attachment, Slack, and E2B downloads, file_generation saves, visualization charts, workspace knowledge links, workspace todo templates, and file and coding reads, writes, and deletes refuse a workspace replaced by a link after runtime resolution.
That check covers only the workspace's final path component, so a replaced parent such as agents/<name> is not refused.
With the default workspace names that is not exploitable in the hosted layout, because no primary-only directory there contains an entry named workspace; an authored private.root that matches a primary directory name, such as credentials, could be reached through a replaced parent.
A background job's saved result keeps the bytes a tool returned with a media file instead of reopening its path, and reads a media file the tool returned only by path as a regular file, opened non-blocking without following a final link.
Git commands the primary runs in a workspace, for knowledge checkouts and the coding tool's ignore check, use the hardened Git command and environment, so programs named in workspace Git config never run.
Read limits on workspace files
Reads of worker-controlled files are capped per surface.
| Surface | Cap | Above the cap |
|---|---|---|
| Context files | 1 MiB | Truncated with a warning |
prompt_curation snapshots of MEMORY.md and context files |
1 MiB per file | Refused, so the check is skipped with a warning or verify reports the file as unreadable |
dreaming memory files, staging copies, reports, and verdicts |
1 MiB per file | A memory file is left out of the run, a staged file stops the run, and a report or verdict counts as missing, so the run stops or the proposal is rejected |
dreaming thread-export index.json |
8 MiB per room | Ignored, so that room's conversations are aged by file modification time |
Workspace SKILL.md, skill references and scripts |
1 MiB per file; names 64 characters; descriptions and the reason a skill did not load 1024 characters; 256 listed scripts and 256 references; per workspace 256 skills and 8 MiB of SKILL.md files and listings, including files that fail to load; 1,024 examined entries per skills/, scripts/, references/, or skills/.history/<skill>/ directory, for skill loading and skill learning alike |
An oversized file or a skill with a longer name is refused, a longer description, listing, or reason is truncated, and skills beyond the budget or count are skipped, each with a warning; the agent's system prompt names each skill refused for its frontmatter or name with the reason, which can quote that frontmatter; entries past the first 1,024 in directory order are not examined |
Workspace subagent profiles (subagents/*.md) |
64 KiB per file; names 64 characters; descriptions 1024 characters; the listing reads at most 256 profiles and 1 MiB; 1,024 examined entries in subagents/ |
An oversized or unreadable file is listed as invalid and cannot run, and profiles past the listing limits are left out of it but still load by name |
| Call transcripts sent to Mem0 | 64 MiB | Truncated |
| Knowledge sources, including operator-managed ones | 64 MiB | Left out of the listing with a warning |
| Vectors one search loads from a base whose path lies in, or holds, storage that workers write: private knowledge, semantic file memory, and shared bases inside a workspace or shared directory | 256 MiB per base | The search fails before loading them, so memory search falls back to keyword matching and search_knowledge_base leaves that base out of its results, or reports the error when no other base answers |
Scheduled-run receipts, file and coding reads, airflow DAG reads |
64 MiB | Refused with a logged error |
e2b uploads, sandbox files that e2b downloads or reads, and e2b command and code output |
64 MiB | Refused with a tool error; stream_command() returns its first 64 MiB |
microsoft_files uploads |
250 MB, Microsoft Graph's single-request limit | Refused with a tool error before any request |
outlook_mail attachments |
3 MB per file, Microsoft Graph's inline attachment limit | Refused with a tool error before any request |
slack uploads |
50 MB, the same as Slack downloads | Refused with a tool error before any request |
Files a file content search reads |
500 KiB each, Agno's search limit | Skipped |
browser upload snapshots, kept in the browser's temp directory until their tab closes |
256 MiB in total per browser | Refused with a tool error |
| Media files a background job's result reads by path | 48 MiB in total per result, within its 64 MiB encoded limit | The job fails with a size-limit error |
moviepy_video_tools staged inputs |
1 GiB per video; 1 MiB per caption file | The call fails before staging more than the cap |
| Files a chat client reads or saves over through the workspace file routes | 5 MiB per file; 5,000 examined entries per folder listing, hidden ones included | A read or save answers 413; a listing is cut and says so |
| What the workspace change stream scans | 10,000 folders, 100,000 examined entries, and 16 MiB of kept paths as UTF-8, breadth first, 32 folders deep; 100,000 paths or 16 MiB of paths waiting unsent per stream | Changes in the deepest folders and entries past the cap are not reported; a stream with more waiting closes for the client to connect again |
Thread-export files are read and built under the per-file, per-thread, and per-room limits documented in Thread Exports.
The exporter's drift check reads at most 8 MiB of a room's index.json and rebuilds a larger one from the thread files.
Workspace todo templates have the size, render, and listing limits documented in todo, and they render in a short-lived, memory-limited child process instead of the primary, because sandboxed Jinja alone does not bound their cost.
Workspace SKILL.md and subagent profile frontmatter, todo templates, and thread-export files are refused before parsing when their YAML uses aliases, %TAG directives, deep nesting, or other structures that would let a small file cost the primary unbounded memory, stack depth, or parse time; Skills lists the exact limits.
Request sizing reads the page count of a PDF a request carries, an attachment or a tool's result, with pypdf in the primary, so a crafted PDF costs the parse time pypdf allows; the dependency floor follows pypdf's denial-of-service fixes.
Listening agents
A listening agent runs model turns that no requester started, driven by room text. Everyone who may reach the agent in a listened room can put text in front of the model, and a silent turn has no requester whose budget or access it could be checked against. Heard text can therefore carry prompt injection that drives the turn's tools.
What listen.tools names is the operator's choice, and the rest only narrows what a turn reaches:
- A silent turn calls only
listen.tools, each of which must also be one of the agent's owntools, so it gains no tool,worker_scopecheck bypass, or tool limit bypass. A listed tool keeps its usual effects, though, and some act with the agent's full authority later or elsewhere. What listed tools can do names them, and the few tools and arguments MindRoom refuses; list them only if you trust everyone whose messages the agent hears. - Approval-gated tools and interactive questions are hidden, and the turn's text is dropped.
- The prompt marks heard text as data rather than instructions, which lowers but does not remove the risk.
- It hears only senders allowed to reach the agent in that room, judged on the person a relay speaks for.
max_runs_per_hourandmax_messagesbound the turns and what each reads.
Keep listen.tools narrow: injected text can use any listed tool.
Heard text also crosses rooms and users through memory and the knowledge graph.
A silent turn with memory, or with knowledge_graph when knowledge_graph_edits is on, can store what anyone it may answer said in a listened room, including people who never addressed the agent, and both are shared, so that text can resurface in the agent's replies in other rooms and to other users (Privacy and cost).
This is intended: an operator who lists either chooses to let the agent learn from the room.
Hosted tenant isolation
Hosted tenants share the mindroom-instances namespace, and a tenant can run code in its own primary and sandbox-runner sidecar by design.
The boundary between tenants is the cluster configuration around those pods.
Multi-Tenant Architecture lists those controls. The instance chart refuses dedicated Kubernetes workers because RBAC cannot confine a worker manager to one tenant's Deployments, Services, PVCs, and Secrets in a shared namespace.
File access
defaults.file_access sets the default and agents.<name>.file_access overrides it for one agent.
| Value | Path tools may use |
|---|---|
workspace (default) |
Files inside the agent workspace and attachments available in the conversation; for file and coding, also the agent's shared directories, read-only where it only joined; in a headless run with a workdir, file, coding, and attachments' view_file use that directory instead of the workspace, file and coding may also read the agent's saved tool outputs, and the other path tools keep the workspace; a browser in the primary process also uploads and opens files by absolute path from its own artifact directory, browser/ in the agent's state root unless output_dir names another |
unrestricted |
Any file the tool's process can reach; on a worker that is the worker container |
Every tool, including plugin tools, must declare one of these file access classes when it registers, so no tool silently defaults to taking no paths.
| Tool class | Tools | Behavior |
|---|---|---|
| Path tools | attachments (including view_file), matrix_message, chat_ui canvas pages (show_canvas with path), gmail, google_drive, microsoft_files, outlook_mail attachments, slack uploads, browser uploads, e2b uploads, openai and groq audio files, airflow, moviepy_video_tools |
Follow the agent's file_access and refuse replaced workspace roots and swapped files; airflow and moviepy_video_tools writes do not follow links below the workspace, and MoviePy and FFmpeg work only on private staged copies, refusing video inputs that FFmpeg would open as playlists or manifests |
| Worker path tools | file, coding |
Follow the agent's file_access; reads, writes, edits, deletes, and every file a file content search reads refuse replaced workspace roots and swapped files, while listing and the other searches walk by path, as the known gap below describes |
| Unconfined tools | Code-execution tools (shell, python, docker, claude_agent) and tools whose queries, paths, or URLs reach local files without confinement (duckdb, csv, pandas, sql, composio, postgres, redshift, browserbase) |
Class unconfined: not confined by file_access, whatever the agent's setting; authored tool config may only state file_access: unconfined |
| Other tools | Everything else, including web_browser_tools, which opens only http and https URLs |
Take no local file paths |
browser_mcp runs only in a worker and confines its upload, drop, screenshot, and PDF paths to the worker workspace whatever the agent's file_access.
MCP servers on the local stdio transport are unconfined too, because they are operator-launched programs; remote sse and streamable-http servers take no local file paths.
Whether a tool executes code is a separate metadata flag from its file access class; only the code-execution tools above, script, and terminal carry it.
A worker isolates the unconfined tools that support worker routing (shell, python, docker, csv, postgres, redshift).
The rest require the primary runtime and cannot run in a worker (claude_agent, duckdb, pandas, sql, composio, browserbase, and stdio MCP servers), so enable them only for agents trusted with everything the primary runtime can reach.
script also runs in the primary process, but there it only reads the one source file it launches, from the agent workspace through no-follow descriptors whatever the agent's file_access, so it declares no file access; its scripts run on the worker backend.
terminal also runs in the primary process, but it only types into and reads the terminals of the agent's shell in its worker, so it declares no file access, and it offers nothing to an agent whose shell runs in the primary.
It types only for an agent whose run_shell_command calls never ask for approval, because approval rules judge a command's text and what text typed into a persistent shell runs depends on what ran there before; any other agent is offered only reading and listing, on every path (Persistent Terminals).
MindRoom logs a warning when an agent routes code-execution tools to a worker while primary-process tools stay unconfined, meaning unconfined tools, path tools under file_access: unrestricted, or script under a local MINDROOM_SANDBOX_EXECUTION_MODE, which runs scripts in the primary process, because those tools can then read runtime secrets the worker was meant to keep away.
The model sees the effective file access and the unconfined tools in its tool execution environment description.
Connections portal sign-in
This section holds the mechanics behind opening Connections from MindRoom Chat.
The portal asks the window that opened it for a Matrix OpenID token over postMessage, waiting up to five seconds; without an answer it signs in through Chat's page below rather than trusting the browser's existing session, which may belong to another account, and while it shows its message instead, an answer that arrives later still signs in.
That page, also where a signed-out direct visit goes, is the sign_in_url that GET /api/connections/session names, /connections on the first web origin in MINDROOM_CONNECTIONS_ALLOWED_ORIGINS, which comes only from configuration; the portal never sends the same tab there twice in a row, and links to it the second time instead.
It then posts the token and the origin of Chat's message to POST /api/connections/session.
Chat's /connections page instead submits the token as a form to POST /api/connections/session/handoff, a top-level cross-origin post whose Origin header the browser sets, and MindRoom checks that header the same way before redirecting to /connections/; the token travels in the form body, never in a URL.
When a published report that requires sign-in sent the browser to Chat, the hand-off redirects to the page of that report the browser asked for, /reports/public/<slug> plus the requested path and query, instead, read from the ten-minute __Host-mindroom_report_return cookie (mindroom_report_return over plain HTTP), which holds only that slug, path, and query, percent-encoded; it is SameSite=None over HTTPS because the hand-off is a cross-site post, and a value whose slug is malformed or whose path has a . or .. segment or a backslash, before or after one more percent-decoding, lands on the portal.
MindRoom checks that origin against MINDROOM_CONNECTIONS_ALLOWED_ORIGINS, which defaults to MindRoom's hosted Chat plus, for a portal on a local address, any Chat on a local address; under that default, MindRoom also reads /_matrix/client/versions and refuses sign-in unless the homeserver binds tokens.
It verifies the token at the configured homeserver through /_matrix/federation/v1/openid/userinfo and accepts only users of that homeserver.
MindRoom also sends the normalized origin of MINDROOM_PUBLIC_URL, or http://localhost:<MINDROOM_PORT> when it is unset, as the audience, so a homeserver that binds tokens accepts only a token that Chat requested for that origin; other homeservers ignore it.
MindRoom then sets the __Host-mindroom_connections_session cookie.
The cookie is Secure, HttpOnly, SameSite=Lax, and Path=/.
Browsers refuse Secure cookies over plain HTTP, so a portal on a local address served over HTTP names it mindroom_connections_session without Secure; an HTTPS portal ignores that name, so a sibling host cannot plant a session for it.
The cookie is browser-wide, so a second sign-in in another tab replaces it.
To keep a stale tab from acting as the new account, the Connections pages send the Matrix ID they show in the X-MindRoom-Connections-User header on every /api/connections request.
MindRoom answers 401 when that header names a different account than the request authenticates as, whether by a session or by trusted upstream.
Requests without the header, such as OAuth popup navigations, still work.
At sign-in, MindRoom also records in the signed cookie whether the session may open the dashboard.
It may only when the user is in administrators and the homeserver's /_matrix/client/versions lists io.mindroom.openid_audience as true, which MindRoom's Tuwunel fork does while it binds tokens.
Under binding, a token that verified with this deployment's audience was requested for this deployment, so another deployment's operator cannot replay it here; without binding they could, and the dashboard is full control.
The exception is deployments that all leave MINDROOM_PUBLIC_URL unset and so share the default http://localhost:<MINDROOM_PORT> audience: a backend a user opens at that origin can replay the token to any such deployment it reaches.
MindRoom verifies the token a second time after reading /versions, because /versions shows only the setting after the first verification: if binding came on in between, the second verification refuses the unbound token, and if it went off, the first one already proved the token bound to this deployment.
The record is fixed at sign-in, because a session started before binding was never proven bound, while administrators is read again on every dashboard request.
Such a session authenticates dashboard routes as the administrator's Matrix ID, except in hosted platform mode and on OAuth callbacks, which keep finishing each flow as the identity that started it.
MindRoom Chat's iOS app opens agents' connect and reset links in the system browser, where it cannot post from a page, so it starts that browser's session through /api/connections/session/native/ instead and then continues to the link.
The app posts its token to start, which checks it like a Chat sign-in, except that it always requires a homeserver that binds tokens, whatever MINDROOM_CONNECTIONS_ALLOWED_ORIGINS lists, because no browser Origin vouches for the call.
That list stays the operator's off switch: start and confirm refuse with 403 while it is [] or invalid, before they issue or consume any state, but its web origins never apply to the app.
The browser that opens the returned redeem URL gets a pending cookie, __Host-mindroom_connections_session_native or, on a plain HTTP local portal, mindroom_connections_session_native, and the app gets a nonce through mindroom://connections/confirm, whose origin parameter names the origin of the deployment that issued it.
The app confirms the nonce with its own token, which must name the user who started, and the browser that opens the returned continue URL gets the session only if it holds the pending cookie that nonce was issued for.
So a forwarded redeem URL sends the nonce to the victim's device, where the app cannot confirm it as another user, and a forwarded continue URL finds no matching pending cookie.
The app confirms only a nonce whose origin is the backend it started with.
Otherwise a malicious backend the app talks to, such as one an agent published in a shared room, could redirect the first sheet to an honest backend's redeem URL holding its own start state: the honest backend's page would set the attacker's pending cookie in the victim's browser and hand the app a nonce, which the app would then post to the malicious backend, whose operator confirms it with their own token and redirects the second sheet to the resulting continue URL, leaving the victim's browser signed in as the attacker.
The redeem step answers a page that opens the app's URL, rather than a redirect to it, because iOS may drop a cookie set on a redirect to a custom scheme.
Every step's state is single use and expires after 120 seconds, and a session started this way never opens the dashboard.
Only capacitor://localhost, the app's own origin, may call these routes from a page, without credentials, whatever the dashboard's CORS settings say; the handlers do not check Origin, since the app's own bound token is the proof.
Client sessions for plugin routes
POST /api/client-sessions is public and takes a Matrix OpenID token.
MindRoom verifies it at the configured homeserver's /_matrix/federation/v1/openid/userinfo, and accepts only users of that homeserver.
Like Connections sign-in, it refuses with 403 unless the homeserver binds tokens to this deployment's audience, because without binding any backend a user opens from the client could replay their token; unlike Connections, no setting waives this.
It answers 503 when it cannot check whether the homeserver binds tokens, and verifies the token a second time after that check, requiring the same user, so binding switched off between the two requests cannot pass an unbound token.
It answers with a random session token that lives only in the backend's memory and expires after 3600 seconds, so a restart signs every client out.
DELETE /api/client-sessions ends the session whose token its Authorization: Bearer header carries at once, as a client does at sign-out, and answers 401 for a missing, unknown, or expired token.
Plugin HTTP routes check the session only when a request arrives, so a response already streaming outlives the session's expiry or revocation; a websocket signed in with client_stream closes at either.
The store keeps at most 8 sessions per user, evicting that user's oldest past it, and 10,000 in all, evicting the oldest of anyone's past that, so it never refuses a sign-in and, below 10,000 sessions, one user's sign-ins never sign another user out.
A plugin's routes_module router is served under /api/plugins/<plugin>/ by the primary, which adds no authentication of its own, so a route that does not depend on require_client_user, require_room_member, require_room_reader, require_room_messenger, or require_platform_administrator is public; plugin code already runs with the primary's full trust.
Workers never import a routes module, as long as it is its own file that the plugin's tools and hooks modules do not import.
Plugin routes share the dashboard's origin, so a route that returned text/html or other content a browser renders, built from untrusted input, could run script with the dashboard's signed-in session.
MindRoom does not filter what plugin routes return, so they must answer with JSON; as a backstop, every response under /api/plugins/ carries X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox; default-src 'none', replacing whatever the route set.
A plugin route that raises answers 500 without the error's detail, except that one using its plugin context while the current config does not load the plugin answers 503 naming only the plugin.
Plugin routes under /api/plugins/ call require_client_user from mindroom.plugin_http, which accepts Authorization: Bearer <session_token> and answers 401 for a missing, unknown, or expired token.
GET /api/plugins checks the session the same way and answers any session, whatever its user's rooms, with this MindRoom's plugin API version and the manifest name and mindroom_plugin_api of each enabled plugin that loaded, never a plugin's path, settings, or load error.
Routes that act on one room use require_room_member instead, which authenticates the caller the same way and checks the session's own user, never one a request parameter names, in the room the route's path names, never one from the query string; it reads live joined members through the client of the router bot if it is in the room, else of any running MindRoom bot in the room, answering 403 for a non-member and 503 when membership is unavailable (no running bot in the room, the Matrix call answered with an error, raised, or timed out, or the API runs without MindRoom's bots).
require_room_reader makes the same check before it reads anything else of the room, whatever the room's history visibility or join rule, and its RoomReader reads members' display names from that same lookup and power levels and direct-message status through a bot it picks the same way, each when the route asks, answering 503 rather than a refusal when a power-level read fails or times out; is_direct() is the agents' cached direct-message heuristic, which answers 503 when the bot's direct-message list or the room's state cannot be read and nothing else marks the room as direct, never an authorization.
RoomReader.set_modes() changes the room's thread and reply mode overrides only for a caller a fresh power-level read shows with room admin power, the bar !thread_mode and !reply_mode set, answering 403 otherwise and 503 when that read fails, before it writes anything.
RoomReader.history() reads the caller's membership again with the room's history visibility, answering 403 once they have left and 503 when the read fails or times out; the start of their view rests on origin_server_ts, which the sending homeserver sets, so it counts only events of the caller's own homeserver, the only one whose users get client sessions, and ends at an invite another homeserver sent.
RoomReader.agents() and agent() admit an agent by the check the worker Computer uses, under the config the API serves rather than the one the runtime runs: the user ID names a current agent, it and the caller are both joined, by the lookup that admitted the caller here and by the router's for the Computer, and under current room grants the agent's access rules let the caller converse with it there; agent() answers 503 while identities or grants are unresolved, and agents() leaves such an agent out and answers 503 only while the router's rooms are unknown; grants are current as the router's sync keeps them, refreshed through the runtime's one refresh when they need it, and the room read again when its ready grants lack a caller its live roster shows joined, and plugin routes never refresh grants under a membership policy the running runtime has not applied.
Each admitted agent's root is the workspace a turn of that agent for that caller in that room resolves, never a path from the request; files and terminal follow the agent's toolkits as their declarations and settings describe them, and give only read and watch to a caller whose power level keeps them from posting; a contact room opens none, because its turns run as the agent's owner.
terminal is none unless the agent's terminals setting is watch or type, none by default, and its shell offers run_shell_command in a worker, and type only under terminals: type where that worker mounts the workspace, a dedicated worker or a static_runner the deployment says mounts the agents' storage, because only there does typing act on the files the caller sees as the agent's root.
The terminal routes under /api/rooms/ take the same sessions and admit through RoomReader.agents() or agent() on every request, stream only with watch or type, open, close, and take input only with type, and take no path or worker from the client; their streams recheck agent() every 15 seconds under the config served then, dropping input once the caller may only watch and closing once the agent is no longer open to them.
A plugin route reaches the same terminals through RoomReader.terminals(), for a workspace agents() or agent() returned, resolved for the reader's own caller and room as these routes resolve them, and none while terminal is none; it checks nothing more, so the route itself opens, closes, and types only with type, as the plugin docs say, since plugins run with the primary's trust.
client_rooms checks each candidate room for the session's own user the same way and leaves out one it cannot check.
The workspace file routes under /api/rooms/ take the same sessions and admit the caller through RoomReader.agents() or agent() on every request, so a saved change to an agent's access applies to the next request; they serve only the root that check resolves, never a path or folder from the request, refuse paths that leave it by .. or a link, and change files only for a caller whose files is write, which needs a writing toolkit that works in the workspace: in the primary, a dedicated worker, or a static_runner the deployment says mounts the agents' storage, since only there could the agent itself change those files.
The workspace is the agent's HOME, so they hide the credentials that page lists, even through a link, and never move or delete a folder that keeps one by its place.
The secret request route POST /api/rooms/<room_id>/secret-requests/<request_id> takes the same sessions through require_room_member and answers only the person the agent asked, for a request registered in that room, once, while it is pending; under the config the API serves when the answer arrives, it checks again that the caller may manage the agent's Agent Keys, that the agent still keeps the caller's keys in the store the card was made for, and that the service still takes a user's key and has the hosts the card showed, and it writes the key only into that store, never into a scope the agent moved to.
The key never appears in a response, a log line, or a Matrix event.
The change stream rechecks agent() every 15 seconds under the config served then, closing once the workspace is no longer open to the caller or its root moved; it registers no watch by path, but scans the workspace by opening every folder from the root without following a link, as the file routes do, and reports only what those scans saw, so a link planted or swapped in the workspace never makes the primary look at or report anything outside it.
require_room_messenger makes the same check, and its RoomMessenger posts only as the router, never from a person's account: notice() is an m.notice naming no requester, and relay() names the session's own user, never one a request names, as original sender, so each agent it wakes authorizes that user, after checking again just before sending that the session is live and the user is joined and may send m.room.message.
A relay mentions only agents and teams joined to the room, and both refuse content keys under com.mindroom., io.mindroom., MindRoom Chat's chat.mindroom., or a namespace another loaded plugin reserves and the posting plugin does not, at any depth, and Matrix's own top-level keys, such as body, m.relates_to, and m.new_content, so neither a route nor its client can claim a requester, hide whom a relay is for, edit another message, or forge another plugin's card through content.
notice() checks no power level, so a member the power levels keep from posting can still have a route post a router notice; the route chooses who may.
Routes only administrators may use depend on require_platform_administrator, which authenticates the caller the same way and answers 403 unless the session's user, or the person it is a bridge alias of, is in administrators in the config the API serves when the request arrives.
The session names a Matrix user and nothing more; a plugin route that serves room data must check that user's room membership itself.
A browser cannot set a websocket's headers, so a plugin websocket route signs its caller in with client_stream from mindroom.plugin_http: the client offers the session token as the subprotocol mindroom-session.<session_token> beside mindroom-session, which the server accepts with, so the token is never echoed in the handshake answer.
Browsers apply no CORS to websockets, so client_stream itself refuses an Origin missing from MINDROOM_COMPUTER_ALLOWED_ORIGINS, and given a room it checks membership as require_room_member does before accepting and every 60 seconds after, closing the websocket when the user has left or membership is unavailable.
It refuses a user's 17th open stream before accepting, across every route that uses it, MindRoom's terminal and workspace change streams included, so one session cannot hold unbounded terminal attachments or workspace watchers.
A plugin websocket route without client_stream is public and accepts any origin.
worker_relay from mindroom.plugin_http reaches only the running dedicated worker of the worker_target a route or tool passes, never starting one, and checks no caller, so a route passes only the worker_target of an AgentWorkspace that agent() or agents() admitted for its caller, or one a tool of the plugin recorded, once the route checked that the record belongs to the route's room and agent and that its caller may use that agent there, and a tool only its own agent's; load_worker_target refuses a stored target whose worker key or private-agent visibility is not what its own scope, agent, and identity resolve, while its subagent placement only picks one of that worker's own subagent workers, which serve its workspaces and credentials, and a plugin loads only targets it stored in its state directory, which no worker mounts, never one a client sends; by name it reaches only services of the plugin whose route calls it, which it takes from the route's own scope, never from an argument, or of the plugin the context a tool passes names, and by port only what the worker's runner relays; it adds the runner token and drops any copy the route sends, and the runner adds the service's secret and drops any copy that arrives.
client_user_oauth_access_token from mindroom.plugin_http gives a route the access token of one person's own OAuth connection, the one an agent whose worker scope is user or user_agent keeps for them, refreshed as the agent's tools refresh it, only while that person may converse with the agent under its access rules, as the Connections portal requires, and may connect its accounts, as a connect link's completion requires, and never for one of MindRoom's own accounts, nor for a provider none of the agent's tools uses or whose tools act as a service account; like the portal it decides on the room grants as the runtime holds them and reads no room itself, so a caller admitted only by room membership is refused until MindRoom has read that room; it refuses any other caller or agent before opening a credential store or minting a link, because a shared or unscoped agent's connection, like a service account, serves everyone who uses that agent, and a caller removed from an agent keeps their stored connection but no longer reaches it through the agent; it trusts the ClientUser its route passes, so a route passes only the one a session dependency resolved, never one a request names, and the plugin, which already runs with the primary's full trust, decides where the token goes.
A plugin's origin_module router answers every request on its hosts, <label>.<plugin>.<MINDROOM_PLUGIN_ORIGIN_DOMAIN>, on the listener MINDROOM_PLUGIN_ORIGIN_PORT turns on, beside the API; MindRoom adds no authentication there, only the API's request body limit, so the plugin's router decides who sees each page, and a plugin reaches only hosts with its own name, which comes from the host, never from the request's path or query.
Each host is an origin of its own, so its pages share no origin with the dashboard, the API's client routes, or another plugin's hosts; they do share a site with every other host of the domain, which is why the docs put the domain on a registrable domain of its own, and MindRoom's cookie-authenticated API changes require the API's own Origin.
Every answer on the listener carries Content-Security-Policy: frame-ancestors 'self' with the origins MINDROOM_COMPUTER_ALLOWED_ORIGINS lists, as a separate policy a route can tighten but never loosen, so a page there loads only in MindRoom Chat's frames or the host's own; no other header is forced, because core never knows what a plugin serves.
On any other host, GET /ask?domain=<host> tells an on-demand TLS proxy whether the host's plugin says it serves it now, so certificates are issued only for hosts a plugin vouches for; the listener writes no access log line for its HTTP requests, since a path or query may carry a one-use link, while Uvicorn still logs each websocket handshake with its path.
The call transcript routes under /api/call-transcripts/v1/ take the same sessions and check rooms themselves through the router: room membership to read a room's live call, permission to post messages to start or join a call, and for a call's own routes the room the call is in, never one the request names, answering 404 to anyone outside it.
In a room an agent answers calls in, while no live call between people takes precedence, reading the room's live call checks room membership through that agent instead, also while call transcripts are off, and a call with the agent is read from the agent's transcript in memory, by its caller only, since other members could not tell they were heard.
CORS for /api/client-sessions, /api/plugins, /api/plugins/, /api/call-transcripts/, and /api/rooms/ reuses MINDROOM_COMPUTER_ALLOWED_ORIGINS, the list that admits MindRoom Chat to worker computers, so an origin trusted for computers is trusted for plugin, call transcript, and room routes too, and there is no separate list.
Browsers let only those origins read these paths' responses, with credentials off, and every response carries Cache-Control: no-store; behind a proxy that serves MindRoom under a root path, the paths are matched below that root path.
CORS limits which pages may read a response, not which requests reach MindRoom: a simple request from any origin still reaches a public plugin route.
Known gaps
These are tracked gaps, not intentional behaviors; fix them rather than documenting around them.
- The unconfined non-code tools
composio,postgres,redshift, andbrowserbasedo not yet followfile_access; a separate change will confine their explicit path and URL arguments. - SQL-capable tools (
duckdb,csv,sql, andpandasquery helpers) embed file paths inside queries, so guarding explicit path arguments cannot confine them; they stay unconfined until a query-level mechanism exists. - The listing and search functions of
fileandcoding(list_files,search_files,grep,find_files, andls) refuse a workspace that no longer resolves to the pinned directory and paths that lead outside it, but then walk and read by path. This matters only when an operator routes these tools to the primary process while worker code writes the same workspace, such as the Kubernetesstatic_runnersidecar withworker_toolsthat leave outfileandcoding. Code that swaps the workspace, a checked directory, or a file for a link between that check and the walk can make that one call list or return any file the primary process can read, and a planted FIFO can stall acodingcontent search. By default these tools run in a worker, where they see only what the worker already mounts. - Knowledge Git commands refuse a worktree whose path goes through a link, but Git then reopens that worktree by path. For a Git-backed knowledge base inside a workspace a worker writes, swapping the knowledge folder for a link between that check and the Git command can make that one sync check out or update files at the link target with the primary's permissions; the next sync refuses the link.
- Opening a conversation store checks for links only once, because Python's
sqlite3cannot open a database without following links. Asessionsdirectory swapped for a link inside SQLite's own resolve-then-open window at that open opens the link's target under the expected name: a file there already in the current layout opens as the store, a file in an older layout stops at the conversion's backup, which follows no link, and a missing or empty one gets the storage v2 tables. An open store then reconnects by path for each operation for the rest of the turn, so a swap made after the open is followed: that operation fails on the missing tables, and it can leave an empty<name>.dbat the link's target. Only code in the Kubernetesstatic_runnersidecar can write asessionsdirectory. - Mem0 opens an agent's Chroma store below
agents/by path on every memory call, without a link check, so a link planted there can send that store's reads and writes to the link's target. The one-time merge of the team memory copies earlier releases kept there refuses a member store holding a link when it starts, but not a link swapped in while Chroma opens it. Chroma also bundles its own SQLite 3.46, so a journal planted beside that store makes the primary delete the file the journal names when Chroma next opens it. Only code in the Kubernetesstatic_runnersidecar can write belowagents/, and team memory itself lives inteam_memory/, which no worker mounts.
Intentional behaviors
Do not report or "fix" these; they are deliberate.
- An operator who runs MindRoom without workers, for example inside a dedicated LXC container or VM, has chosen full trust;
file_access: unrestrictedmatches that choice. file_access: unrestricted, or unconfined tools in the primary process, are allowed together with worker routing; they log a warning instead of failing.- Hosted tenants may set
file_access: unrestricted; it exposes only their own instance. - With
file_access: workspace, the browser, attachments,matrix_message,chat_uicanvases, Gmail, Google Drive, Microsoft Files, Outlook mail, and Slack uploads may still use every file in the agent workspace. - A
chat_uicanvas can leak what the user types into it through WebRTC, which browsers do not let a page block, or, with libraries or remote assets on, through the addresses it requests, so agents should only show pages they wrote; remote assets also show every host a page names the viewer's IP address; see Privacy and safety. - The browser and
matrix_messagealso acceptatt_*IDs of attachments available in the conversation, andagent_manager'sset_avataraccepts only those IDs; Gmail, Google Drive, Microsoft Files, Outlook mail, and Slack take file paths only, so an agent first saves a received attachment into the workspace withget_attachment(mindroom_output_path=...)and then passes that workspace path. mindroom_output_path, attachment saves, Google Drive and Microsoft Files downloads, Outlook mail attachment downloads, Slack downloads,file_generationsaves,visualizationcharts, and report publishing always write inside the workspace regardless offile_access, because they produce MindRoom-owned output.- Writes into
.gitdirectories stay blocked forfileandcodingin both modes, because MindRoom runs Git in checkouts that may sit inside agent workspaces. - Live reply frames in an encrypted room use the room's current Megolm session without counting toward its 100-message rotation, so one session covers more ciphertexts, including live-only text, reasoning, and running tools' output that need not equal any stored event; age and membership rotation still apply. Counting them would rotate the session about every ten seconds while a reply streams, each rotation sharing a new key with every device.
- A temporary secret reaches the shell commands of the conversation whose requester gave it, in a worker too, and MindRoom removes it from tool results only on a best-effort basis; the requester accepts with each card that the agent's commands hold the value. A value kept for 24 hours lies unencrypted in a file of the primary, as the credential store's files do.
- A skill review may resend the reviewed conversation unredacted to the provider that just received it, and a digest replay redacts credentials only on a best-effort basis; see What a review sees. The check that refuses skill files holding a literal credential is a heuristic for common formats; a miss is not a vulnerability, because skills live in the agent's own workspace next to the conversation history that already held the value.
- Automatic skill learning trusts the
metadata.mindroomfrontmatter flags and the provenance and usage inskills/.usage.jsoninside the workspace, which worker code can change; that only lets it make the learner edit or archive skills worker code could already change itself. skill_manage, used in chat by agents that list it or learn skills and by skill reviews, runs in the primary process and writes only below the agent's workspaceskills/directory through no-follow descriptors, regardless offile_access, like MindRoom-owned output.- The
atlassiantool'swrite,jira_spaces, andconfluence_spaceslimit only that tool's own functions, which act as a requester who may reach more: an issue in an allowed space still shows the keys and summaries of linked, parent, and sub-issues in other spaces, searches can select allowed issues by those relations, an issue'sfieldscan set a parent elsewhere,space_not_allowedreveals that an item exists outside the allowed spaces, and the egress brokeratlassianservice, the API-tokenjiraandconfluencetools, and code execution in the primary are not limited; see Limit What An Agent Can Do. - An authored subagent, started by
run_subagentwithsystem_prompt,tools, orprofileor by a Dynamic Workflowsubagentparticipant, runs as its caller with the caller's tools, credentials, workspace, and approval rules, which for a workflow participant include the caller'sdynamic_workflowallowed_toolspre-approval and reading the skills it names when the caller could without approval; worker code that edits asubagents/*.mdprofile can change what such a child is told, but gives it nothing the caller lacks. - Each agent publishes its running background jobs in each room as unencrypted room state keyed by its own user ID: job ID, thread, kind, tool name, status, requester ID, and start time, never arguments or results, so the homeserver and every room member can read them even in an encrypted room.
- Each agent, team, and the router also publishes its runtime's origin,
MINDROOM_PUBLIC_URLorhttp://localhost:<MINDROOM_PORT>, whether it has a worker computer, and for an agent or team its configuredrole, as unencrypted room state keyed by its own user ID, so the homeserver and every room member can read the address, including a LAN or localhost one, and the role, also in an encrypted room and with the API off. MindRoom Chat uses a published origin only from agents on the viewer's homeserver, and only while that homeserver binds tokens, so a hostile agent can collect at most tokens bound to its own origin. It shows a published role likewise only from agents on the viewer's homeserver, so a person writing the same state under their own user ID shows no role. - An administrator whom a personal agent's template
accessadmits, whom an owner adds as a co-owner of an agent created withcreate_agent, or whom a team that includes such an agent admits, may use that agent, whose instructions its owner may have written, and its tools act for the administrator, so such an agent with an administrator-gated tool such asconfig_managercan make that tool act with an administrator's authority; Letting an Agent Create Agents warns to allow creation only on agents whose whole configuration each person may have. - Anyone who may talk to an agent in a room may cancel its background jobs there, including jobs another requester started, as with Stop; another agent's account never may.
- A secret request card shows a
reasonthe model wrote, so a manipulated agent can ask for the key of any service it may request with misleading text; the key still reaches only that service's hosts, which the card shows. - A secret request card also shows a title, a field hint, and a link button the model chose, so a manipulated agent can point the button at a look-alike sign-in page, as it can with a link in any message; the button names the page's host, only
httpandhttpslinks with nouser:password@part get one, and MindRoom never fetches the link. - An agent's 🛑 reaction, its Stop button included, stops nothing unless it comes from
stop_reply, which counts as the Stop of the user the agent acts for and needs that user's access to the stopped agent. - The agent or team that answers in a conversation lists, reads, and cancels the background jobs its team members started there for the same requester, because the team already receives its members' output.
!auto_approvelets a person approve every gated tool call they request in one thread, or in the whole room when it has no threads, for up to 24 hours, including tools that ask for their own confirmation but not tool calls scheduled to run later; only that person can send it, never an agent acting for them.- The router publishes each room's open
!auto_approvewindows as unencrypted room state keyed by its own user ID: thread, requester ID, and end time, so the homeserver and every room member can read them even in an encrypted room. - The router also publishes which joined members of each room are its installation's router, agent, and team accounts, as unencrypted room state keyed by its own user ID, so the homeserver and every room member can read them even in an encrypted room. Other members can send the same event type only under other state keys, so a client trusts only the list a MindRoom router on the viewer's homeserver sent under its own user ID; see Room Accounts List.
- Scheduled tasks, including their prompts, and thread tags, including the topic tags agents add automatically, are stored as unencrypted room state, so the homeserver and every room member can read them even in an encrypted room.
- A
!config setchange awaiting confirmation is stored as unencrypted room state with its config path, requester, and new value, so the homeserver and every room member can read them even in an encrypted room; a new value that display redaction would mask, or that room state cannot hold, such as a decimal number, stays only in the running process. - The
jobfunction never asks for approval, even undertool_approval.default: require_approval, because it only reads and cancels the caller's own jobs, each of which passed its own approval. config_manager'smanage_config(operation="inspect")andmanage_agent(operation="validate")calls never ask for approval, even under a matching rule ortool_approval.default: require_approval, because they only read configuration.- Inviting an agent to a shared directory makes it readable to every requester of that agent. An invitation from a user who may use that agent takes effect at once, because that user could already relay the files in chat; any other invitation waits until a user who may use the invited agent accepts it through that agent, and declining needs such a user too.
- A pending invitation names only the directory's owner and name in the invited agent's prompt, never its path, files, or the inviting user, and an agent holds at most 10 pending invitations, so the line stays short; anyone who may use a shareable owner can add such an entry for any shareable agent.
- A user who may use both agents can restart the invited agent's dedicated workers by inviting and removing it repeatedly, which ends their background shells.
- Removing a member or deleting a shared directory takes effect for a member's dedicated worker on that worker's next tool call, so until then its running processes can still read the directory, including files written after the removal.
- Removing a service from
defaults.worker_grantable_credentials, or removing the environment variable that declares a granted credential and restarting, deletes its copy from a running dedicated worker at that worker's next tool call, not at the config reload, so until then, or until the worker stops for being idle, its running processes can still read the credential. Worker code may already have copied a credential it was granted, so rotate the credential at its provider to revoke it. - A team's
accessauthorizes its exact member agents for team requests, in Matrix and the OpenAI-compatible API, even members whose ownaccesswould not admit the requester directly; adding an agent to a team is a deliberate grant. - A response's CLI grant, in minimal mode or for a standard-mode agent whose shell can reach MindRoom, is in the environment of its shell commands, so other code in the same worker can use that requester's tools through it until the response and its background jobs end; code that shares a worker already shares its trust. A terminal's shell never gets it, because the shell outlives the response (Persistent Terminals).
- Approval rules judge the text of each command an agent runs, not what running it does, so files an earlier approved or allowed command left in the workspace can change what a later allowed command does, such as a
.mindroom/worker-env.shthat setsBASH_ENV, whose file Bash then reads before each later shell command. The terminal toolkit's typing rule above follows from the same limit. - A plugin's
tool:environmenthook decides which variables a tool call'sshellcommands receive, in the primary or a worker, including values it passes through from the primary's process environment; plugins already run with the primary's full trust, the variables travel only with that call's request, except that a terminal aterminal_opencall starts keeps them in its shell, and other code in the same worker can read them, as with the CLI grant. - A shared agent's knowledge graph holds facts from every requester's conversations and tool results, and any requester of that agent can query it, like shared-agent memory; private agents get one graph per requester.
- A shared agent's later turns in a conversation replay each earlier turn's context, including another requester's
persist=Falsehook items such as a location, so it can repeat them to anyone in that conversation, like persisted items; private agents keep each requester's conversations apart. - Unless
knowledge_graph_editsis off, any requester of a shared agent, or a tool result that steers it, can have it delete facts and entities from the shared graph, merge its entities, or rewrite their summaries, as with any write tool; the edits reach only that agent's own graph. - Redacting a message does not remove facts the knowledge graph already extracted from it; ingestion skips turns derived from messages redacted before it reached them, so raising
knowledge_graph.generationrebuilds the graphs without them; replies and voice calls already running finish on the old graphs, which stay stored untilknowledge_graph/is deleted with MindRoom stopped; anexplorationprompt can still list a redacted turn's tool calls until the agent next replies in that conversation. - An
explorationrun is an ordinary turn started by an automation prompt, with the agent's own tools and approval rules, so content it reads can steer it as it could any turn that reads untrusted content; approval rules, not the prompt's instruction to only read, stop writes. - A shared agent's exploration follows tool calls from every requester's conversations with that agent's own credentials, so one requester can lead it to read something their own access cannot and then query the result in the shared graph; use a private agent when requesters must stay apart.
- Knowledge graph extraction reads tool results that worker code produced, so a crafted result can add wrong facts to the graph, each attributed to its source; it runs nothing in the primary.
- A personal
slack_downloadsaves a file the requester can see in Slack into the agent's workspace, so on a non-private agent every requester of that agent can read it; personal Slack belongs onprivateagents. google_drive_download_file, on by default, saves a file the connected Google account can see into the agent's workspace, so on a non-private agent with requester-owned Google Drive connections every requester of that agent can read another requester's downloads; such connections belong onprivateagents.- A non-private agent's workspace is shared by every requester's runtime for that agent, including
useranduser_agentworkers, so files one requester leaves there (such as.mindroom/worker-env.sh,.pthfiles, or Git config) can run in another requester's runtime; useprivateagents when requesters need isolation from each other. - Likewise, a non-private agent's primary-process
browserprofiles and default artifacts live in that agent's state root and are shared by all of its requesters, as is a started profile's running browser with its open tabs, so one requester can use web sessions another signed in, read pages another left open, and upload screenshots another took; they never cross agents or the requesters of a private agent. - A browser egress proxy in a sandbox runner receives destination hostnames, because an approved-egress proxy decides by name, so rebinding between the relay's check and that proxy's own lookup is the proxy's responsibility; in the primary the relay tunnels to the address it validated.
- A proxy environment the primary cannot follow, such as a SOCKS proxy or
auto_proxy, makes the relay dial directly within the browser's destination policy instead of refusing to start, because no MindRoom egress policy depends on that proxy there; a sandbox runner refuses. - A shared knowledge base whose path lies inside an agent workspace, such as that agent's thread exports, or inside a shared directory is bound without following links below that directory, so even an operator-made link there is refused; shared knowledge outside every agent workspace and shared directory still follows operator links.
- On Linux, the knowledge folder watcher finds a base's folders without following links and then watches each one by path, so keeping its watches inside the base is best effort. A folder swapped for a link between that walk and its watch moves its own watch, and those of the folders the walk found below it, to the link's target and the matching folders below that target; each watch stays not recursive and within the folder cap, and lasts until the watcher next rebuilds its watches, such as when a folder appears in the base. A change there can start a refresh of the base, which still reads only files reached inside the base without links, as code that writes inside the base can already do by writing a file there.
egress_broker.private_networkslets the broker, which runs in the primary, dial the listed private ranges for workers, including primary-host addresses in them (such as thedocker0gateway) and destinations a Kubernetes worker's NetworkPolicy blocks; loopback and metadata addresses stay refused, and Private networks describes the exposure.- The egress broker streams request bodies, so a valid request head can reach the right upstream before a bad or oversized body gets 400 or 413 and the upstream connection is aborted; the head carries the secret only to the host the request was routed to, and Egress Broker Design Decisions gives the reason.
- The egress broker's check for stray bytes on a reused tunnel upstream cannot see bytes that reach the socket just after the check polls it. Such bytes can only come from that tunnel's own upstream, and no other tunnel, host, or requester is affected.
- A team approval continuation checks only that each approved call keeps the arguments its card showed, not whether the saved team run holds other calls ready to run, because team runs live below
teams/, which no worker mounts. - The Kubernetes
static_runnersidecar mountsagents,private_instances, andshared_directoriesread-write as the primary's user, so tool code it runs can read and change every agent's sessions, memory, learning data left on disk from before Learning was retired, shared directories, and private-instance contents; the shared sidecar is not an isolation boundary between agents or requesters, and dedicated Kubernetes workers are the option that is. - A dedicated worker's runner relays the primary's requests to the servers the worker runs on its loopback, including one through which worker code serves a server of an operator's extra container in a Kubernetes worker pod, because worker code can already reach each of them; it refuses a port that any process outside the runner's process tree and cgroup holds a listening socket on, the runner's own port, and every port when
/proccannot say who holds it; a port found to be the worker's stays reachable while the same sockets listen on it, even if worker code hands them to another process, because that code could serve the other process's server itself; and the shared runner relays to none, because its loopback holds every agent's servers and, in the hostedstatic_runnersidecar, the primary's own. - The relay reaches a plugin's worker service by name only while the runner runs it for that plugin, and by port too, since worker code can already reach that port; only a request by name carries the service's secret, so the service refuses one by port.
- The relay lists and reaches MindRoom's own loopback helpers in a dedicated worker, such as the browser tool's SOCKS relay and URL verifier, because the worker's processes hold them; each answers only its own protocol or a request carrying its token.
- A plugin's worker service runs the plugin's program in the agent's dedicated worker as the runner's user, never in the primary or the shared runner; its per-start secret, handed over on a socket as stdin so that it is in neither the program's environment nor its command line and cannot be read again through
/proc, keeps out plain connections from other processes in the worker, not code there that can read or trace the program's memory, which could equally run its own server. - A worker service that presents its running instance's secret may watch the agent's Computer browser page through the agent's browser bridge and, while it holds the Computer's control, act on it with input, navigation to
http,https, orabout:blankunder the browser's own request checks, and viewport changes, never script, cookies, storage, or other targets; the worker trusts the service, so the plugin's route decides who may watch or take control through it, and the desktop's viewers share the same single control. - After an upgrade from workers that mounted whole state roots, startup stops those workers before serving, failing until none remain, and warns; it does not scan for or repair links they may have planted above workspaces, because a scan on every start is costly and an automatic repair could itself follow a planted entry, so an operator runs the upgrade check.
- Conversation OAuth connect and reset links for shared-scope credentials work without a dashboard login; the short-lived single-use link and the recheck of the issuing requester's credential-management permission authorize them, because some deployments give users no dashboard access.
- Anyone who can use an agent may connect or reset their own requester-owned OAuth connection (user or user-agent credential scope) through its chat links, as on the Connections portal; the browser must authenticate as the link's requester, and shared-scope connections still require an administrator or credential manager.
- The Connections portal signs users in either through trusted upstream auth or through a Matrix OpenID token that MindRoom Chat hands to the portal window, from the origins
MINDROOM_CONNECTIONS_ALLOWED_ORIGINSlists or, unset, from MindRoom's hosted Chat and, for a portal on a local address, any Chat on a local address. Under the default list, MindRoom accepts that sign-in only while the homeserver binds tokens, because otherwise any backend a user opens from Chat could replay their token to it, and request headers cannot show that a portal is out of such a backend's reach; an explicit list is the operator's choice. The session cookie names the verified Matrix user and a fixed one-hour lifetime, signed with a key each MindRoom process generates at start, and it authenticates the portal and its APIs, its user's own conversation connect and reset links for requester-owned connections, the OAuth callback for flows it started, the OAuth success page, andGETrequests for published reports. The portal opens a connect or reset link given as?next=after its sign-in attempt, which grants nothing beyond opening that link directly: the link still checks that the signed-in user is its requester, and the user still approves at the provider or on the reset confirmation page. Outside hosted platform mode, it also opens the dashboard, but only for a user inadministratorswhose token the homeserver bound to this deployment at sign-in; everyone else, and every session on a homeserver that does not bind tokens, needs the API key for the dashboard. Binding is proven by the homeserver's/_matrix/client/versionsand a second verification of the token after reading it, so turning binding on or off once during a sign-in cannot promote an unbound token; turning it on and off again within that one sign-in is not covered. An allowlisted origin can sign a browser in as any Matrix user whose OpenID token it holds, so list only Chat origins you operate or trust; with the default list, a page served from any local address can do so for a portal on a local address. Over plain HTTP on a local address, the session cookie and the OAuth flow cross that network unencrypted, as the rest of a plain-HTTP stack does, and because cookies ignore ports, every other web service on that host receives the session cookie too. On a homeserver that does not bind tokens to one deployment, a backend that Chat opens could replay a user's token to another deployment on the same homeserver until it expires; audience binding closes that where the homeserver supports it. The/connectionspage shell is served without authentication, while every API stays protected. - While published reports require sign-in, a signed-in browser opens a report under a view address whose four-hour key, signed with a key each MindRoom process generates at start, opens that one report, because a sandboxed site's own requests carry no cookie.
Anyone holding the view address opens that report, and no other, until the key expires, the report is revoked, or MindRoom restarts; its answers carry
Access-Control-Allow-Origin: *, which the site's module scripts and CSS fonts need and which gives nothing beyond holding the address. - With
personal_rooms.agentnaming apersonal_agentstemplate, every human member of an onboarding room gets a Matrix account and a running agent; membership of that room is the only gate, so its join policy and invitations control who gets one. - A
personal_agentstemplate whoseaccessadmits other people exposes each owner's agent, including its memory, files, and shared credentials, to them and to their own agents acting for them; owner-only access is the default. - An accepted contact lets the other side start turns of an agent that run with its owner's authority, limited to the tools the owner approved for that contact; anything those tools can reach, the other side can ask for, and a code-execution tool such as
shellreaches everything the agent's worker or process can. A contact turn also keeps the agent's instructions, preloaded files, and memory recall, so the other side can try to extract them. - A contact turn can post into its contact room only through
matrix_message, after the contact's message policy; any other message, edit, reaction, or file that the turn, its tools, or its plugin hooks send into that room is refused, and so is one that amessage:receivedorreaction:receivedhook sends there for an event in that room; only the fixed 👀 that MindRoom puts on the message the turn answers skips the policy. - A contact request puts text its requester controls, the
reasonand the requesting agent's display name, into a new thread of the target owner's personal room, and any owner whose personal agent hascontactscan send one after approving their own request card. When the target owner replies in that thread, their personal-room agent reads that text in a normal turn with the owner's full tools, so the text can steer it like any untrusted content; approval cards, whichaccept_contactalways shows unless the owner turned on!auto_approvethere, and the owner'stool_approvalrules for other tools are what stop writes. - A personal agent whose
contacts.remote_agentsnames agents of other deployments treats an invite from any matching account as a contact request, which puts the invite'sreasoninto its owner's personal room like a request from this deployment; an empty list, the default, accepts none. Only the other agent's Matrix ID, which federation authenticates, is trusted for such a contact: its owner is not exchanged and starts no turn here, and its unmentioned messages start none either. The contact room and every message in it are stored on the other deployment's homeserver as well. The other agent has power level 100 in a contact room once it joins, and in a room it created for its own request it is the room's creator, which on room version 12 and later also lets it remove this deployment's agent; either way it can invite more accounts to read the conversation and remove the owners there, and its deployment's own policy, not this one, decides whether it does. - A Connections portal session can accept, decline, change, and remove its user's contacts on the Contacts page without an approval card, as it already connects accounts and allows Agent Keys; those requests must come from the portal's own origin, and no model takes part in them.
- A contact's rules and judge are model judgments, not a security boundary; they reduce accidental disclosure, but a determined counterparty can still extract what the agent's context and contact tools expose.
- A tool the owner approves for a contact reaches what it reaches, so with
fileapproved the other side's requests can change files the agent reads in every turn, such asMEMORY.md; MindRoom adds no write guard there, because an approved tool is the owner's choice of what the other side may drive. GET /api/oauth/<provider_id>/client-metadata.jsonis public, because the authorization server of a remote MCP server fetches it without a login: it answers only while the provider's stored OAuth client is identified by that document, and it holds MindRoom's client name and the provider's callback and scopes, nothing secret.POST /api/slack/eventsis public: it has no dashboard login, accepts a request only when it carries a valid signature from the Slack app's signing secret made within five minutes, and answers 404 while no Slack app is configured.- A Slack message wakes a project agent as the MindRoom account that its author's confirmed Slack email maps to through
slack.email_domainandslack.matrix_user_id_template, still subject to the agent'saccess, so whoever can set that email on a full member account of the workspace can act as that MindRoom account; guests, bots, other workspaces, and emails that map to one of MindRoom's own accounts or to a configuredbot_accountsentry never map. Slack text is delivered as a fenced block that is never parsed for Matrix mentions, so it cannot wake other agents. Only messages in the agent's listed channels wake it, and only while Slack confirms at that moment that the app is still a member there, never in a direct message. - A personal Slack watch delivers only into a room where the owner is the only human, nobody is invited, and people who join later cannot read earlier messages; the turn runs as the owner, and the toolkit refuses Slack writes in it, but work that turn schedules or delegates still runs as the owner, so
tool_approvalrules for Slack's write functions (slack_post,slack_edit,slack_delete,slack_react, andslack_upload) are the boundary for those. - The MCP gateway runs an agent's tools without its instructions, so it withholds agents whose worker scope is
sharedor unset unlessmcp_gateway_shared_credentialsopts one in; an opted-in agent's users can call its tools directly with its shared accounts and worker, and the shared workspace and browser profiles of a non-privateuseroruser_agentagent stay reachable through the gateway as they are in chat.
Reviewing security findings
Classify every finding before proposing a change.
- Name the boundary it crosses: worker to primary, tenant to tenant, Matrix user to agent, or none.
- Check whether the agent involved is trusted under the trust model above.
- Check the intentional behaviors list.
- Only a finding that crosses a real boundary and matches no intentional behavior is a bug.
A fix that restricts a trusted setup, or that blocks workspace and attachment flows an agent legitimately needs, is not a security fix. When a maintainer rejects a finding as intended behavior, add it to the list above in the same change so the next reviewer does not rediscover it.