# Security (https://docs.neuralisapp.com/enterprise/security)

The security model is the spine of Neuralis, not a hardening guide bolted on
afterwards. The platform exists to let AI agents do consequential work, and
that is only acceptable if every actor is governed the same way. Neuralis is
built for multi-tenant deployments where most users are employees of an
organization signing in through admin-configured auth.

On this page a **floor** is a guarantee the code enforces whatever any
setting, role or policy says: no configuration can switch it off, and a fix
that would weaken it is refused. Every other page calls these guarantees or
hard limits.

## Six layers, each deny-by-default [#six-layers-each-deny-by-default]

Every request (a human in the browser, an agent tool call, a skill script, a
scheduled workflow run, an external MCP client) passes six layers:

1. **Authentication.** Registration is closed: accounts exist because setup
   or an admin created them. Failed logins lock that account from that address
   after five tries, and an address that sprays many accounts is slowed down;
   the address is the connecting socket unless you declare your reverse proxy
   (see [Deployment](https://docs.neuralisapp.com/enterprise/deployment.md)). A disabled or deleted account is
   refused on its next request everywhere: browser, MCP client, terminal socket
   or scheduled run.
2. **Project membership.** Non-members cannot even infer that a project's
   packages, agents, sources or runs exist. A member removed mid-stream loses
   access on their agent's next call (see [Multi-tenancy](https://docs.neuralisapp.com/enterprise/multi-tenancy.md)).
3. **Role and feature grants.** Every route and tool declares the feature it
   requires, checked on the server before any data access. Hiding a UI tab is
   never the defence (see [Roles](https://docs.neuralisapp.com/enterprise/roles.md)).
4. **URI policy.** Per-package path rules gate the filesystem at the route,
   the UI, the tools (the sandboxed shell included) and the vector index. A path
   no rule covers is denied, and a path an immutable rule makes unreadable is
   never newly embedded into the search index (see
   [URI policies](https://docs.neuralisapp.com/package-system/uri-policies.md)).
5. **Trust tier.** Native, trusted and untrusted packages get different
   runtime bindings; untrusted code runs in a WASM sandbox. A package dropped
   into a project loads untrusted until a project owner raises its trust, and it
   never becomes native.
6. **Audit.** Privileged operations and denials land in an append-only audit
   log (see [Audit trail](#audit-trail)).

## One session identity [#one-session-identity]

Caller identity (user, project, agent, role, granted features) travels as one
canonical session. Skill scripts call back into the host with a short-lived
**per-stream session ticket** minted from that session and re-minted on every
shell call; routes derive the project and agent from the verified ticket and
gate on the caller's real role and features. There is no service account,
synthetic owner, or admin-token path that a skill could escalate through, so a
skill can never act with more authority than the user whose session activated
it. The ticket stops verifying when its stream ends, and failed verifications
are audited with their reason. Successful skill calls are audited with the
calling bundle's id. External MCP callers cannot override their scope with
headers either (see [The MCP boundary](#the-mcp-boundary)).

## What the model sees is filtered too [#what-the-model-sees-is-filtered-too]

System-prompt contributions (skills, instructions, rules, agents, docs and the
package overview) inherit their package's enable state and the caller's grants.
A capability the caller cannot use is not rendered as "locked"; it is absent.
An owner-only skill is not listed, not injected and not activatable from a
member's stream, and a tool outside the caller's features is missing from the
model's catalog: a hallucinated call to one fails with a generic not-available
error.

## Administration [#administration]

The [admin package](https://docs.neuralisapp.com/admin.md) is the most privileged surface, and it applies the
same posture without exception:

- **Server-side gates.** Every admin route declares a feature checked against
  the caller's real grants before the handler runs; a request crafted directly
  against the API meets the same gate as one from the widget.
- **Graduated inside an endpoint.** Every role holds the dashboard feature, so
  the routes it gates answer for the session's project and widen only for the
  matching `platform.*` feature, which no role holds by default: cross-project
  usage needs `platform.projects`, per-user spend `platform.users`, and a
  project you do not belong to answers `404`.
- **Role assignment and editing.** A caller may assign only a role at or below
  their own strength, may edit only roles strictly weaker than their own (never
  their own role, so locking yourself out is impossible), and may grant or
  revoke only features they hold. The rules key on the priority number, never
  on a role name (see [Roles](https://docs.neuralisapp.com/enterprise/roles.md)).
- **Destructive actions are explicit.** The vector reset drops every project's
  collections, and with them every `brain://` file; it has its own feature,
  `platform.vector.reset`, and requires the literal confirmation `RESET` in the
  body. There is no GET-triggered variant.
- **One validated writer.** Source configuration changes go through the brain's
  single validated writer; admin never writes source files directly.
- **Provider status without environment secrets.** The health report counts
  LLM providers from the encrypted credential store, never from `*_API_KEY`
  environment variables. The one environment secret in scope, the vector
  database key, is boot infrastructure, sent only to the vector database and
  never shown (the Config tab reads `(set)` or `(unset)`).

## Secrets [#secrets]

Long-lived secrets live in an encrypted credential store, scoped four ways
(platform, project, user, agent) and resolved most-specific-wins; see
[Credentials](https://docs.neuralisapp.com/package-system/credentials.md). The API never returns a stored
value, only whether one exists.

- **Two tiers.** Reading the catalog (`project.credentials`) and writing a
  value (`project.credentials.write`) are separate features. A write reaches
  only the caller's own scope; another project, user or agent, or the
  platform-wide scope, also needs `platform.scope`, which no role holds by
  default. Even that key is confined to principals inside the caller's own
  projects; the platform-wide scope is the one arm with no tenant to confine it
  to, which is why `platform.scope` carries no default grant. Writes are capped at 10 per
  minute per user and audited with id and scope, never the value.
- **Self-service writes cannot reach another scope.** Connecting your own chat
  channel or storing your own git token goes through ports that take a user id
  and nothing else, so "write this to the platform scope" is unrepresentable
  there, not merely denied.
- **A declaration is not a grant.** Declaring a credential in a manifest adds a
  catalog row an owner can fill; it confers no authority. The id namespaces of
  the self-service writes can be declared only by native packages.
- **The shell environment is rebuilt, not inherited.** Secret-like variables
  (`*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*API_KEY*`, `*CREDENTIAL*`, provider
  prefixes) are stripped from the base environment and from caller overrides.
  The only way through is a skill's declared `credentials:` list, resolved at the
  caller's scope within their tier, injected only for the person who activated
  the skill, and never for the reserved connect-flow ids.

## Agent data and conversations [#agent-data-and-conversations]

Agent-core partitions its data per agent, and **every agent is private to the
user who created it**: nobody else, owners and admins included, can chat with
it, run it, reach it over MCP or schedule it until they are attached to it
(Admin → Agents). An attached user shares the agent's memory, identity,
workflows, plans and logs; conversations stay per user. Every run carries the
rights of the user who started it, never the creator's. An agent's own subtree
is read-write from its own runs; another agent's subtree is not readable from
them (owners and admins read it for oversight, except the agent's record, which
only the platform writes). **A conversation belongs to the user who started it:** another
member can neither list, read nor continue it, through the chat history or the
filesystem tools, and a member's own container shell is held by the same rule
at the operating-system layer. Workflow run folders are engine-written and
read-only for every caller. The runtime's own conversation files (the
transcript, its metadata and the summary archive) are protected by a floor: no
tool or route writes them, not even an owner. Historical summaries are never
embedded or searchable.

Every agent shell passes command analysis and the URI-policy check before it
spawns, and runs inside a kernel filesystem sandbox whose roots are exactly
what the caller's policy grants. The details are on
[agent-core Tools](https://docs.neuralisapp.com/agent-core/tools.md).

## Folders on a device [#folders-on-a-device]

Neuralis can reach a paired device (the server itself, or a person's own
machine) through a broker running on that device. It ships off, it has no
per-role bypass, not even for an owner, and the device dials out: the
application holds no host secret, and nothing from the device is ever a request.
A folder on a device is an ordinary source: brain-core enforces the caller's
scope and URI policy first (a user-scope folder on a device is its owner's
alone; no admin grant reaches it), and the device's broker independently clamps every
read and write against the ceiling its owner set. Pairing, ceilings and
revocation are on [Devices](https://docs.neuralisapp.com/getting-started/devices.md).

## The MCP boundary [#the-mcp-boundary]

The hosted MCP server applies the same identity discipline to external
clients. A caller authenticates with a per-agent API key or an OAuth 2.1 token,
both resolving to a fixed user, project and agent. An agent API key acts as the
user who created the key, never as the agent's creator, and stops working when
that user may no longer use the agent. Identity headers from
external callers are ignored, the reserved system identity is refused before
dispatch, and tool results are size-capped (by default 50,000 characters of
content, 20,000 of structured content and 256,000 of `_meta`; platform settings
`toolResultContentCapChars`, `toolResultStructuredCapChars` and
`toolResultMetaCapChars`), so a tool cannot flood the wire or the model. See [MCP access](https://docs.neuralisapp.com/enterprise/mcp-access.md).

## The MCP Apps sandbox [#the-mcp-apps-sandbox]

Interactive HTML from a connected MCP server (an MCP App) is untrusted
external content and never touches the app origin:

- It runs inside an isolated-origin sandbox, a throwaway origin on a second
  published port that serves nothing but a static relay shell. The sandbox is
  mandatory: without it the card refuses to render. The relay answers only the
  one trusted app origin, so open the workspace on exactly the origin your
  `APP_URL` names; another loopback spelling renders MCP Apps inert.
- Its Content-Security-Policy is injected on the server from the resource's
  declared domains over a deny-by-default baseline.
- Rendering requires the `mcp.apps` feature, which no role below admin holds.
- Every app operation is bound to a short-lived View lease that lives only in
  server memory; each operation re-runs a fresh access check, and losing
  access tears the view down.
- An app may call tools only on the server that owns it, through the same
  policy gate as a model call. An approval runs the tool once from the
  originally stored input, a view can never approve itself, and an app message
  only prefills the composer; it never sends. External links open only after a
  human confirms.

## Tool calls [#tool-calls]

Every tool call passes five deny arms in a fixed order (the global blocklist,
the package's trust ceiling, its capability gate, the untrusted-package
allowlist, and the tool's declared features) before the conversation's guard
profile decides whether it runs or waits for approval. The guard can never
grant what an arm refused. A package cannot gate or block another package's
tool. Approval replays re-validate against the originally stored input, so an
approver cannot be shown different arguments than the ones that run.

## What a package file may do to the prompt [#what-a-package-file-may-do-to-the-prompt]

Package and source markdown is assembled into the system prompt inside
labelled containers, and every value the platform did not author is treated as
data. A body cannot close the container it sits in (its own tag is visibly
folded) and cannot forge a second block. Every injected value is escaped and
bounded; identifiers the model passes back (a tool, command or delegate name)
are never truncated, and above a far higher ceiling they are dropped with a
stated reason. These rules hold for every trust tier, native included, beneath
the visibility gates that decide whether a file is injected at all.

## Audit trail [#audit-trail]

Security-relevant events land in an append-only log in the platform zone,
outside any package data folder an audited agent could reach. No record is
ever deleted; rotated generations stay readable. Recorded: logins (failures and
rate-limit hits included); user, project, agent and package lifecycle;
credential reads and writes; config writes; every successful shell call with its
command and working directory; every failed tool call; terminal attach, detach
and blocked input; conversation deletion and updates; and every skill-originated
API call. A second platform file, the route log, records one line per
package-route dispatch and which gate refused a call, never the request path.
The audit hooks only observe: they never block or slow a call, and they never
record a credential.

Reading the audit and route logs needs `platform.audit`, because their entries
carry no project id. The admin package's own `audit` and `logs` folders deny
reading by default and re-open it only for an owner- or admin-strength role;
that path rule is a second line, and the cross-project gate stays the feature.
