Overview

This section establishes the mental model the rest of the site assumes.

Docker-for-actors at a glance

Same shape as Docker and npm, mapped onto the Matrix actor system (THESIS Part 1):

Concept	Docker / npm world	Matrix substrate
The thing you publish	Image / npm package	Package (@open-matrix/<x>)
The registry	Docker Hub / npm / Gitea	Gitea (Matrix-native) or HiveCast-hosted package registry
The thing that runs	Container	DeploymentInstance (target state, P1.42)
The runtime that runs them	Docker engine / Node	Matrix runtime (a Node process; substrate for actors)
The host that runs runtimes	Linux box / VM	A Matrix Host (the user's machine)
The orchestration	Compose / Kubernetes	Host Service + future composer
Inter-container comms	TCP/IP, sockets	NATS subjects, typed bus messages
Isolation declaration	seccomp, namespaces	matrix.json runtime.isolation field

A user deploys packages into runtimes. Multiple packages can share a runtime when their isolation declarations allow. A runtime is a substrate for actors, not "the runtime for one specific package."

The four substrate units

The repo CLAUDE.md states the architectural rule explicitly:

Environments own ports, storage, and credentials. Packages own source, build output, components, and relative mounts. Runners turn a package into a process. Hosts supervise runners.

The four-unit split is the spine of every other page in this section. Pages here introduce them in order:

Pages

• What is a Matrix package? — directory shape and required files
• Package vs actor — distribution unit vs runtime bus participant
• Package vs app — backend package vs web app surface
• Package vs runtime — install artifact vs process
• Package lifecycle — the seven stages: author, build, test, publish, install, run, operate
• Deployless lifecycle — running a package from a checkout without ever publishing it

Cross-references

• The architectural ontology (Environment / Package / Runner / Host) is described in projects/matrix-3/packages/docs/content/architecture/package-design.md. This section repeats only what package authors need; deployment-profile details are in Deployment Profiles.
• The Authoring section is the next stop after this one for somebody starting a new package.

Multi-package runtimes (target shape)

Status: target state — multi-package runtimes (P1.40-a). Today the codebase implements a simpler one-package-per-runtime shape. The substrate target is multi-package runtimes with declared per-package isolation. Read every "the runtime for this package" claim with that correction in mind. See P1.40.