Filesystem layout

The Host owns one directory: <host-home>. Defaults are ~/.matrix for per-user installs and /var/lib/hivecast for the .deb. Every path here is documented exactly as the Host's code constructs it (host-paths.ts:50-62).

Tree

<host-home>/
├── host.json                         ← Host config (atomic write)
├── host.status.json                  ← live Host status (atomic write; deleted on stop)
├── host.pid                          ← supervisor pid
├── host.start.lock                   ← startup lock (cli.ts:1031-1057); transient
├── bin/
│   └── nats-server[.exe]             ← bundled NATS binary (wrapper installs)
├── credentials/
│   ├── hivecast-install.json         ← install identity (always present)
│   ├── hivecast-link.json            ← Device Link (only after pairing)
│   └── credentials.json              ← NATS credentials (link references)
├── nats/
│   └── host-default/                 ← (or `nats/service/` for .deb)
│       ├── nats-server.conf          ← generated NATS config
│       ├── nats-server.pid           ← NATS pidfile
│       └── jetstream/                ← JetStream store
├── packages/
│   ├── system/node_modules/...       ← seeded by `hivecast install` / `hivecast seed`
│   └── global/node_modules/...       ← user-installed via `matrix install`
├── runtimes/
│   ├── RUNTIME-HOST-LOCAL-...-SYSTEM/
│   │   └── runtime.json              ← durable record (atomic write)
│   ├── RUNTIME-HOST-LOCAL-...-HOST-CONTROL/runtime.json
│   ├── RUNTIME-HOST-LOCAL-...-GATEWAY/runtime.json
│   └── ...
├── runtime-env/
│   ├── <runtimeId>.environment.json  ← per-runtime env (regenerated on every Host start)
│   └── ...
└── logs/
    ├── nats.stdout.log               ← wrapper-managed NATS sibling stdout
    ├── nats.stderr.log               ← wrapper-managed NATS sibling stderr
    ├── host-bootstrap.log            ← .deb ExecStart wrapper bootstrap log
    ├── host.stdout.log               ← optional, wrapper-installs only
    ├── host.stderr.log               ← optional, wrapper-installs only
    └── runtimes/
        ├── RUNTIME-HOST-LOCAL-...-SYSTEM/
        │   ├── stdout.log
        │   └── stderr.log
        └── ...

Per-file ownership

Host-managed (Host writes; do not edit by hand)

Path	Source	Read by
`host.status.json`	`MatrixHostService.start/stop`	CLI, host-control, supervisor RPC clients
`host.pid`	`HostStateStore.writeStatus`	external monitors
`host.start.lock`	`acquireHostStartLock` (`cli.ts:1031-1057`)	concurrent `start` invocations
`runtimes/<id>/runtime.json`	`HostStateStore.writeRuntimeRecord`	bootstrap, `host.control`, operators
`runtime-env/<id>.environment.json`	`writeRuntimeEnvironmentFile`	the spawned runtime child process
`logs/runtimes/<id>/{stdout,stderr}.log`	child process stdout/stderr	operators
`nats/host-default/nats-server.conf`	`ensureNatsConfigFile` (`hivecast.mjs:606-625`)	`nats-server`

Operator-managed (you edit; Host respects on next start)

Path	Purpose
`host.json`	`IMatrixHostConfig` — see Host config
`credentials/hivecast-install.json`	install identity; do not delete; back this up
`credentials/hivecast-link.json`	Device Link; cleared by `hivecast logout`
`credentials/credentials.json`	NATS credentials referenced by `host.json transport.nats.credentialsRef`

Package-managed (user-installed packages own these)

Path	Purpose
`packages/global/node_modules/.../package-state`	wherever a package decides to put its own state

Per-package state lives inside the package directory by convention. The Host does not allocate "data dirs" for packages; if a package needs persistent state, it picks where (typically under its own package directory or a sibling data/ dir).

Wrapper / installer-managed

Path	Purpose
`bin/nats-server[.exe]`	bundled NATS binary; redropped by `hivecast install`
`packages/system/node_modules/...`	bundled default packages; redropped by `hivecast seed`

Per-install differences

Wrapper install (per-user)

Defaults to ~/.matrix on Linux/macOS, %USERPROFILE%\.matrix on Windows. Owned by the running user. NATS pid file at <home>/nats/host-default/nats-server.pid. Logs at <home>/logs/.

`.deb` install

Hard-coded to /var/lib/hivecast. Owned by hivecast system user (or the ${SUDO_USER} who installed). NATS data at /var/lib/hivecast/nats/service/jetstream. Host stdout/stderr go to journald instead of <home>/logs/host.{stdout,stderr}.log.

Container

Defaults to /root/.matrix (per matrix-worker/Dockerfile). Mounted from the host filesystem as a bind mount in docker-compose.yml. NATS sibling logs to <home>/logs/nats.{stdout,stderr}.log.

Sizes

Approximate steady-state sizes (varies by runtime count and JetStream usage):

Path	Typical	Notes
`host.json`	< 2 KiB	static
`runtimes/`	< 100 KiB total for default runtime set	one record per runtime
`runtime-env/`	< 20 KiB total	regenerated every start
`packages/system/`	200–500 MiB	bundled apps
`packages/global/`	depends on user packages	unbounded
`nats/.../jetstream/`	bounded by Stream limits	typically 100s of MiB to GB
`logs/`	grows linearly until rotated	unbounded by default; journald cap helps

Where the Host does NOT touch

~/.bashrc and other shell config — no env-var injection.
System-wide /etc/ files — only when installed via .deb, and only the journald drop-in + units.d overrides.
The user's node_modules. The Host has its own package store under <home>/packages/; npm/pnpm of the user's checkout is unrelated.

Filesystem layout ​

Tree ​

Per-file ownership ​

Host-managed (Host writes; do not edit by hand) ​

Operator-managed (you edit; Host respects on next start) ​

Package-managed (user-installed packages own these) ​

Wrapper / installer-managed ​

Per-install differences ​

Wrapper install (per-user) ​

.deb install ​

Container ​

Sizes ​

Where the Host does NOT touch ​

See also ​