Mounts

A mount is the bus address an actor lives at. It is composed from three layers, declared in three different places:

1. Package mount — declared in matrix.json:components[].mount.
2. Runtime mount — derived from runtimeId at up time.
3. Wire prefix — taken from the runtime's runtimeWireRoot (the environment, not the package).

The full NATS subject is <wirePrefix>.<runtimeMount>.$inbox for ops sent to a runtime control actor, and <wirePrefix>.<packageMount>.$inbox for ops sent to a package's declared actor.

Layer 1 — package mount

Declared at authoring time. From system/matrix.json:

{
  "type": "RuntimeManagerActor",
  "mount": "system.runtimes",
  ...
}

The mount is relative. It does not include the wire prefix. Two different runtimes can both mount the same package and end up serving the actor at the same package mount — only the wire prefix differs.

CLAUDE.md "Bus addressing" calls out the three names a live thing has:

• Binding name — canonical: system.runtimes, chat.conversation
• Runtime identity — which process serves it: runtime://chat-dev-01
• Wire prefix — environment root on NATS: COM.NIMBLETEC.RICHARD-SANTOMAURO

Layer 2 — runtime mount

Derived at up time (packages/host-service/src/cli.ts:154-156):

const runtimeId = options.runtimeId ?? defaultRuntimeIdForTarget(target, options.home);
const runtimeMount = defaultRuntimeMount(runtimeId);
const controlMount = defaultRuntimeControlMount(runtimeId);

Spec field	Default derivation
runtimeId	from --id, or auto-allocated like RUNTIME-HOST-CHAT
runtimeMount	system.runtimes.<slug-of-runtimeId>
controlMount	system.runtimes.<slug-of-runtimeId>.control

The runtime mount is where system.runtimes knows the runtime lives; the control mount is where the supervisor sends shutdown / reload / etc.

Override with --id and --mount on hivecast up. The override flows directly into the runtime record.

Layer 3 — wire prefix

The wire prefix comes from the running Host's transport config (host.json:transport.root). Standard examples:

Wire prefix	When
COM.NIMBLETEC.RICHARD-SANTOMAURO	A user's authenticated Matrix root
COM.OPEN-MATRIX.LOCAL.AUTHORITY	The default for an unlinked install
SPACE.SPC_<id>	A Public Space's authority root

Two Hosts with different wire prefixes can mount the same package at the same package mount and not collide because their full bus subjects differ.

Composition

NATS subject = <wirePrefix>.<mountPath>.$facet

Examples:
  COM.NIMBLETEC.RICHARD-SANTOMAURO.system.runtimes.$inbox
  COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.conversation.$inbox
  COM.NIMBLETEC.RICHARD-SANTOMAURO.system.runtimes.chat-host.control.$inbox

Where $facet is one of $inbox, $reply.<correlationId>, $events, $state, $presence (see CLAUDE.md "Bus addressing").

Mount conflicts

Two runtimes attempting to claim the same logical mount under the same wire prefix is an error. system.registry enforces uniqueness for singleton system mounts (CLAUDE.md):

Singleton system mounts (system.runtimes, system.registry, system.devices, system.auth, host.control) must have one live owner per authority root.

For non-singleton mounts, the registry permits the second registration to displace the first; this is rarely what you want and usually indicates a misconfiguration. Use distinct mounts for distinct logical actors.

Mount aliases via consumes / exports

A package can declare which mounts it expects to find (consumes) and which mounts it promises to serve (exports). From chat/matrix.json:

"consumes": [
  { "contract": "IChatConversationService", "required": true,
    "bindingKey": "conversation-service" }
]

exports from system/matrix.json:

"exports": [
  "system", "system.runtimes", "system.registry",
  "system.bindings", "system.catalog", "system.packages",
  "system.auth", "system.cli",
  "system.gateway", "system.gateway.http"
]

These are advisory today: they document what a package needs and provides. Hard binding enforcement is target state — see system.bindings (today, the legacy compatibility table) versus the future capability declarations.

See also

• Deployment Profiles → Runtime instances
• Authoring → Actor declarations
• Authoring → Package manifest
• Reference → Manifest schema

Source: projects/matrix-3/packages/host-service/src/cli.ts:145-235 derives runtime mounts at up time; packages/mx-cli/src/utils/runner-runtime-control.ts is the control mount facade.