Filesystem layout

Every directory and file under <host-home>. What writes it, what reads it, when it's safe to remove.

Top-level layout

<host-home>/
├── host.json                       # Host config
├── host.status.json                # live status (only present while Host is running)
├── host.pid                        # supervisor pidfile (transient)
├── runtimes/
│   └── <runtime-id>/
│       └── runtime.json            # one per runtime, plus aux state
├── runtime-env/
│   └── <env-name>/
│       └── <runtime-id>.env        # per-runtime env file
├── logs/
│   ├── host.stdout.log
│   ├── host.stderr.log
│   ├── nats.stdout.log             # source-checkout install only
│   ├── nats.stderr.log             # source-checkout install only
│   ├── host-bootstrap.log          # .deb install only
│   └── runtimes/
│       ├── <runtime-id>.stdout.log
│       └── <runtime-id>.stderr.log
├── packages/
│   ├── system/node_modules/        # system-internal package store
│   └── global/node_modules/        # user-facing package store
├── credentials/
│   ├── hivecast-install.json       # installId
│   ├── hivecast-link.json          # link record (only after pairing)
│   └── factotum/                   # Factotum-managed provider creds
├── nats/
│   └── host-default/
│       ├── nats-server.conf        # generated each start
│       ├── nats-server.pid         # transient
│       └── jetstream/              # JetStream message data
├── bin/
│   └── nats-server[.exe]           # bundled NATS binary
├── webapps/                        # bundled static webapp assets (gateway-served)
└── branding/                       # bundled branding assets

This layout is created by seedHostProductHome (hivecast.mjs:348-394). The host-paths.ts file in host-service has the canonical path constants.

Writers and readers

Path	Written by	Read by	Safe to remove?
`host.json`	`hivecast install` (only if absent), `hivecast seed`	host-service on every start	NO — without it, the Host won't start
`host.status.json`	host-service while alive	wrapper, `hivecast status`, `hivecast doctor`	yes — overwritten on next start
`host.pid`	host-service	wrapper	yes — overwritten on next start
`runtimes/<id>/runtime.json`	`host-service up`, host-control, the runtime itself	host-service, `system.runtimes`, `hivecast doctor`	yes — runtime needs to be `down` first; record will be regenerated by `hivecast up`
`runtime-env/<env>/<id>.env`	manually or via env-management tools	runtime spawn	yes — runtime falls back to defaults
`logs/host.{stdout,stderr}.log`	host-service	operator	yes — append-only, never truncated by code; rotate manually
`logs/runtimes/<id>.{stdout,stderr}.log`	runtime spawn	operator	yes — same
`logs/host-bootstrap.log`	`.deb` shim	operator	yes
`logs/nats.{stdout,stderr}.log`	wrapper-spawned NATS	operator	yes
`packages/system/node_modules/`	`seedBundledHostPackages`, `matrix install`	host-service for runtime spawns	yes — re-mirrored on `hivecast install` / `hivecast seed`
`packages/global/node_modules/`	`seedBundledHostPackages`, `matrix install`	host-service for runtime spawns	yes — same
`credentials/hivecast-install.json`	`ensureHiveCastInstallIdentity` (mx-cli)	wrapper, system-auth	NO unless you want to regenerate `installId`
`credentials/hivecast-link.json`	`system-auth` link redemption (via mx-cli `login`)	host-control, system-auth, `hivecast whoami`	only via `hivecast logout` (preserves cloud-side link); `rm` directly leaks the cloud-side link
`credentials/factotum/`	Factotum exclusively	Factotum exclusively	follow Factotum's revocation flow
`nats/host-default/nats-server.conf`	`ensureNatsConfigFile` on every start	NATS sibling	yes — regenerated
`nats/host-default/nats-server.pid`	NATS sibling	wrapper	yes — clean stop removes; otherwise the next start clears stale
`nats/host-default/jetstream/`	NATS itself	NATS itself	depends on what's in JetStream — may include user data
`bin/nats-server[.exe]`	`hivecast install`	wrapper	yes — `hivecast install` re-copies from bundle
`webapps/`, `branding/`	`hivecast install`	gateway	yes — re-copied from bundle

What `<host-home>/runtimes/` looks like in practice

After a fresh install:

runtimes/
├── RUNTIME-HOST-LOCAL-1F746E58793D-SYSTEM/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-HOST-CONTROL/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-GATEWAY/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-WEB/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-EDGE/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-DIRECTOR/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-CHAT/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-INFERENCE-SETTINGS/
│   └── runtime.json
├── RUNTIME-HOST-LOCAL-1F746E58793D-FLOWPAD/
│   └── runtime.json
└── RUNTIME-HOST-LOCAL-1F746E58793D-SMITHERS/
    └── runtime.json

The token 1F746E58793D is the first 12 hex chars of sha256(<host-home>) (defaultRuntimeScope in hivecast.mjs:1297-1302). Every Host's default runtimes have stable predictable ids based on this token.

Differences between source-checkout and `.deb`

Path	Source-checkout default	`.deb` default
`<host-home>`	`~/.matrix`	`/var/lib/hivecast`
Owner	running user	`hivecast` user (or `${SUDO_USER}` via drop-in)
Mode	`0755`	`0750`
`nats-server` location	`<host-home>/bin/nats-server`	`/opt/hivecast/dist/bin/nats-server` (the binary itself; `/var/lib/hivecast/bin/nats-server` is a symlink-or-copy in newer builds, depending on packaging)
NATS data dir	`<host-home>/nats/host-default/`	`/var/lib/hivecast/nats/service/` (note `service/`, not `host-default/`)
systemd journal capture	none	host stdout/stderr captured by systemd
Bootstrap log	(no shim)	`/var/lib/hivecast/logs/host-bootstrap.log`

The .deb install's nats/service/ vs the wrapper's nats/host-default/ is a real divergence, set by the postinst's nats-server.conf writing JetStream store_dir: "/var/lib/hivecast/nats/service/jetstream".

Things that are NOT under `<host-home>`

/lib/systemd/system/hivecast-{nats,host}.service — systemd unit files (.deb only)
/etc/systemd/journald.conf.d/hivecast.conf — journald hardening (.deb only)
/etc/systemd/system/hivecast-{nats,host}.service.d/10-workstation-user.conf — workstation-user drop-in (.deb only)
/opt/hivecast/ — wrapper code, bundled Node, dist (.deb only)
/usr/bin/hivecast, /usr/bin/matrix — bash wrappers (.deb only)
~/.npm/, ~/.node/, etc. — separate from HiveCast

Sensitive files

File	Sensitivity
`host.json` (`auth.sessionSecret`)	secret if set
`credentials/hivecast-install.json`	semi-secret (per-install id)
`credentials/hivecast-link.json`	secret (carries per-Device JWT)
`credentials/factotum/*`	very secret (provider tokens)
`nats/host-default/jetstream/*`	depends on stream contents

Don't include credentials/ in diagnostic captures. See Troubleshooting → Collect diagnostics.

Filesystem layout ​

Top-level layout ​

Writers and readers ​

What <host-home>/runtimes/ looks like in practice ​

Differences between source-checkout and .deb ​

Things that are NOT under <host-home> ​

Sensitive files ​

See also ​