Capability declarations

Status: present state minimal, target state aspirational. The current permissions block is a small set of policy flags validated structurally by the CLI. A richer capability declaration surface, where packages request specific bus mounts, secrets, and filesystem scopes and the Host enforces them, is target state. See P1.15 in WORKSTREAMS/loose-ends/.

Present state — the permissions block

matrix.json:permissions is the only capability declaration the validator inspects today (packages/mx-cli/src/utils/manifestValidator.ts:117-142):

{
  "permissions": {
    "fsPolicy": "global-readonly",
    "hostApi": "same-origin",
    "network": true,
    "subprocess": false,
    "env": true
  }
}

Field	Required	Allowed values	Meaning
fsPolicy	yes	none, matrix-only, project-readonly, project-readwrite, global-readonly	Filesystem scope the runtime may touch
hostApi	no	none, same-origin	Whether the package accesses the Host HTTP API
network	no	boolean	Outbound network allowed
subprocess	no	boolean	Spawning subprocesses allowed
env	no	boolean	Process environment variables visible

Per-component override:

{
  "components": [{
    "type": "SystemGatewayHttpActor",
    "fsPolicy": "global-readonly"
  }]
}

fsPolicy may be overridden on each component to widen or narrow what one actor inside a package can touch.

Filesystem policy semantics

Value	What is allowed
none	No filesystem access
matrix-only	Read/write inside <MATRIX_HOME>/packages/<pkg>/ only
project-readonly	Read inside the package's own directory only
project-readwrite	Read/write inside the package's own directory
global-readonly	Read anywhere; no writes

Today the validator only enforces the field's shape. Whether the runtime actually sandboxes filesystem access at the OS level is a separate question and depends on the execution class (see runtime.executionClassCompatibility). In the default shared_host_service class the package runs inside the Host process; sandboxing is by convention.

Live examples

// system — needs broad read + env
"permissions": {
  "fsPolicy": "global-readonly",
  "network": true,
  "subprocess": false,
  "env": true
}

// chat — backend has network access, no fs writes
"permissions": {
  "fsPolicy": "none",
  "network": true,
  "subprocess": false,
  "env": false
}

// director — pure browser app, no permissions needed
"permissions": { "fsPolicy": "none" }

Target state — declarative capabilities

Status: target state, not implemented. The following describes the direction P1.15 is moving in. None of this is enforced in the current code tree.

A future capabilities block on matrix.json will let packages declare the resources they need and let Hosts grant or deny them on install/start:

{
  "capabilities": {
    "filesystem": [
      { "scope": "package-data", "mode": "readwrite" }
    ],
    "secrets": [
      { "name": "ANTHROPIC_API_KEY", "via": "system.factotum",
        "purpose": "outbound LLM calls" }
    ],
    "bus": [
      { "mount": "system.inference.*",
        "ops": ["complete", "embed"], "direction": "request" },
      { "mount": "chat.events", "direction": "publish" }
    ],
    "network": [
      { "host": "api.anthropic.com", "method": "https" }
    ]
  }
}

Operators would see exactly what a package will do before granting install. Hosts could enforce these declarations at runtime instead of trusting the package to behave.

Recommended discipline today

Even though the validator is shallow, document your intent honestly:

1. Set fsPolicy to the minimum you actually need. Default none.
2. Set network: false if you really don't reach out.
3. Set subprocess: false unless you spawn child processes.
4. Override per-component when one actor needs more (e.g. the HTTP gateway actor needs global-readonly while the rest of the package keeps none).

This is the practice the live tree follows; see system's split between top-level global-readonly and per-component overrides.

See also

• Authoring → Package manifest
• Reference → Manifest schema
• WORKSTREAMS/loose-ends/items/P1.15-capability-declarations.md

Source: Present state in projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts. Target state tracked in WORKSTREAMS/loose-ends/items/P1.15-capability-declarations.md.