Local actor ops

Edge does not invoke bus ops directly (it is HTTP-only). But the user often invokes ops via matrix invoke ... to manage the Device. This page lists the ops most relevant to a Device owner.

Calling shape

matrix invoke <mount> <op> '<json-payload>' --home <host-home>

--home is required when running on a Device with a non-default Host home. On a default install (/var/lib/hivecast/host-home for systemd or ~/.matrix-home etc.), it can be omitted.

host.control (Host supervisor)

Op	Purpose
host.status	Supervisor + NATS status.
host.restart	Restart every runtime.
runtimes.list	List runtime records on this Host.
runtimes.get	One runtime record.
runtimes.declare	Add a runtime record.
runtimes.start / stop / reload / restart / remove	Lifecycle ops.

Examples:

matrix invoke host.control status '{}'

matrix invoke host.control runtimes.declare '{
  "runtimeId": "MY-PKG",
  "package": "@open-matrix/some-package",
  "mount": "my.pkg",
  "env": "hivecast",
  "serve": true,
  "port": 5050,
  "startup": "auto",
  "restart": "always"
}'

matrix invoke host.control runtimes.restart '{"runtimeId":"DIRECTOR"}'

system.runtimes (runtime registry)

Op	Purpose
runtimes.list	List bus-registered runtimes.
runtimes.status	Status + deployment slice.
runtimes.start / stop / reload / restart	Lifecycle by mount.
runtimes.heartbeat	Internal — runtime self-heartbeat.

matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.runtimes runtimes.restart '{"mount":"director"}'

system.registry (logical mounts)

matrix invoke system.registry registry.list '{}'

Lists logical mount claims published by runtimes. Useful for "what addresses are exposed on this Host."

system.devices (Device facade)

# Local Device should be in the list (when paired)
matrix invoke system.devices devices.list '{"includeOffline":true}'

# Inspect this Device specifically
matrix invoke system.devices devices.get '{"deviceId":"<deviceSlug>"}'

# List runtimes registered against this Device
matrix invoke system.devices devices.runtimes.list '{"deviceId":"<deviceSlug>"}'

system.auth (auth, principals, Spaces, Host Links)

Op	Purpose
auth.identity.resolve	Internal — used by gateway.
auth.principal.list	Principal list (one entry on a typical Device).
auth.principal.get	Fetch a principal.
auth.principal.authorityRoot	Resolve authority root.
auth.namespace.list	List public-namespace claims.
auth.namespace.resolve	Resolve a path.
auth.space.get	Fetch a Space.
auth.hostLink.list	Host Links for a principal.
auth.hostLink.get	Inspect one Host Link.
auth.hostLink.revoke	Revoke a Device.
auth.hostLink.refresh	Refresh lastRefreshedAt.
auth.hostLink.credentials.refresh	Issue fresh device-scoped NATS JWT.
auth.device.start / status / approve / poll / exchange / cancel	Device-flow pairing ops.
auth.pair.start / status / approve / exchange / cancel	Pair-flow ops.

For typical Device-owner use:

# Inspect your Host Link
matrix invoke system.auth auth.hostLink.list '{"principalId":"<your-id>"}'

# Force a credential refresh
matrix invoke system.auth auth.hostLink.credentials.refresh \
  '{"principalId":"<your-id>","hostLinkId":"<id>"}'

# Disconnect this Device
matrix invoke system.auth auth.hostLink.revoke '{"hostLinkId":"<id>"}'

system.factotum (credential authority)

The credential authority. Per Rule 4, the only actor that reads/writes credential files. Ops are package-internal — package authors interact with Factotum via well-defined contracts; end users typically don't invoke Factotum ops directly.

App actor mounts

Each running app exposes its own mount:

• chat — Chat package.
• director — Director package.
• system.inference.openai / system.inference.anthropic / etc. — inference drivers.
• flowpad, smithers — other app packages.

These are reached via product URLs (/<spacePath>/chat/) or directly via matrix invoke <mount> <op>.

Where to learn more about an actor

# Introspect any actor for its op list
matrix invoke <mount> $introspect '{}'

The $introspect op returns the actor's accepts map, children, and metadata — same data the dashboard uses for route-plan diagnostics.

See also

• Local routes — HTTP routes.
• Config — host.json config.
• Diagnostics — Endpoint Diagnostics panel.
• HiveCast Platform / Reference / Actor surfaces — platform actor surfaces (superset).

Source: Each actor's accepts declaration in its source. The mx-cli matrix invoke command lives in projects/matrix-3/packages/mx-cli/.