Matrix Package Lifecycle

In docker-for-actors / npm-for-actors terms, a Matrix package is the image: a tarball published to a registry, installable into any Host, runnable as one or more DeploymentInstances (the substrate's containers). This site is the package author's manual for that lifecycle, end to end.

Motivation

Going from "I wrote a Matrix actor" to "it is running on a hosted Device for me or for someone else" is not one step — it is seven discrete stages: author, build, test, publish, install, run, operate. Each stage has its own tools, its own pitfalls, and its own failure modes, and until now the answers were scattered across package READMEs, workstream notes, and tribal knowledge. This package documents the whole journey end to end so authors do not have to assemble it from fragments. Read these docs if you are shipping a Matrix package for the first time, if you have been doing it ad hoc and want the canonical path, or if you operate Hosts and want to know exactly what arrives when an author hands you a package reference.

What this is, and why it exists

A Matrix package is the unit of distribution and the unit of declaration: one matrix.json manifest declares everything the substrate needs to install it, instantiate it, and route to it. The lifecycle has seven stages, in order:

author → build → test → publish (to Gitea) → install (hivecast install)
       → run (mx run / mx up)
       → operate (hivecast logs, hivecast up/down, host.control invocations)

mx run and mx up share the same body — mx run foregrounds, mx up registers the runtime under the Host so it auto-restarts. Same code path, different supervision. This is intentional design.

Where this fits in the whole

This is substrate plumbing, not a vertical. Every vertical (Personal AI runtime, Inference market, Compositional UIs, third-party Matrix pages) ships as one or more Matrix packages. The lifecycle is the same for system packages (@open-matrix/system, @open-matrix/system-gateway-http), user-app packages (@open-matrix/chat, @open-matrix/director), and third-party packages (whatever a developer publishes to Gitea).

Audience

The primary audience is package authors — people writing actor packages, web app packages, or service factories that get installed and supervised by a Matrix Host. Operators and platform admins are a secondary audience for Installing, Running, and Deployment Profiles.

What a Matrix package is, in one paragraph

A Matrix package is a directory containing a matrix.json manifest, a package.json, source under src/, build output under dist/, and optional per-environment files under .matrix/<env>.environment.json. The mx/matrix CLI (projects/matrix-3/packages/mx-cli/src/index.ts) packs, publishes, installs, validates, and runs packages. The hivecast wrapper (projects/matrix-3/packages/hivecast/bin/hivecast.mjs) installs a local Host, seeds the bundled package store, and supervises declared runtimes through Host Service.

Status: target state — single manifest (P1.41). Today some packages still ship a separate matrix.service.json with the bootstrap factory reference. P1.41 absorbs that file: matrix.json becomes the single manifest with explicit runtime / instance / components / service sections, and the per-component relativeMount is mandatory. Pages that mention matrix.service.json mark it as the present implementation while the absorption is in flight. See P1.41.

Five-minute quickstart

Author a tiny package, run it from the source tree, deploy it under a Host. No publishing or installation required for local development.

# 1. Scaffold a new package.
mx init my-feed --kind feed
cd my-feed

# 2. Build.
pnpm build

# 3. Run it once in the foreground (mx run).
matrix run . --env dev

# 4. Or register it under a Host (mx up — same body, supervised).
matrix up . --env dev --serve --runtime-id MY-FEED-DEV

# 5. Inspect what got mounted (bus is authority).
matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.registry registry.list '{}'

# 6. Stop cleanly.
matrix down . --runtime-id MY-FEED-DEV

mx run and mx up use the same factory call; the only difference is whether the Host registers the runtime for auto-restart. That equivalence is documented at Running.

Conceptual map

Question you have	Read
What is a Matrix package, an actor, an app, a runtime?	Overview
How do I declare a manifest, components, web app, config contract?	Authoring
How do I build, test, run in place?	Local Development
How do I publish to Gitea (Matrix-native)?	Publishing
How does hivecast install resolve and place a package?	Installing
How do I supervise it (hivecast up/down, logs, health, update)?	Running
How do I describe a desired-state set of runtimes?	Deployment Profiles
Manifest, package metadata, deployment profile, CLI reference	Reference

The DeploymentInstance ontology (target state)

Status: target state — DeploymentInstance as a first-class noun (P1.42). Today the codebase conflates Package with one running copy. P1.42 introduces three nouns: ComponentType (declared), DeploymentInstance (a running copy with two-tier identity — opaque inst-<hex> ID + human InstanceName), and Mount (the bus path). matrix deploy @open-matrix/chat --instance-name personal-chat will let multiple instances of the same package coexist, each with its own state directory under <host-home>/instances/<instanceId>/. See P1.42.

Sister docs

• docs-runtime-host — the supervisor that hosts the runtimes lifecycle stage 6 lives in.
• docs-registry — where Gitea lives, how the catalog and live actor registry surface this lifecycle's published and running output.
• docs-gateway — how a package's webapp declaration becomes a browser-reachable URL.
• docs-sdk — the actor-development SDK (accepts/emits/streams, testing, migration). This site is the lifecycle; docs-sdk is the programming.

Source portability: All pages follow CommonMark + GFM only, blockquote callouts, no MDX components. See WORKSTREAMS/product-consolidation-and-documentation/PORTABILITY-RULES.md.