@matrix/hivedock3-cli (1.1.33)
Installation
@matrix:registry=npm install @matrix/hivedock3-cli@1.1.33"@matrix/hivedock3-cli": "1.1.33"About this package
HiveDock command line
hivedock runs packages on a machine and supervises them: one HiveDock per
machine or deployment, holding a RunList of what should run.
The executable reads its installed package version once and passes it to the
host engine at construction. host.describe reports that HiveDock version
without rereading package metadata for each request.
Prior art: docker and docker compose (bring a composition up, look at it,
take it down); systemctl (supervise, restart, logs). One of five tools
(governing design §10.1).
Verbs
| Verb | Does | Prior art |
|---|---|---|
hivedock up in a package folder |
Development session: runs this package from source as you, puts it in your Start menu, serves its user interface with hot replacement; Ctrl-C removes it | dotnet watch run, docker compose up (foreground) |
hivedock up / down (deployment) |
Starts or quiesces this machine's whole deployment | docker compose up -d / down |
hivedock up <package> |
Adds the package, then starts it | docker compose up <service> |
hivedock init --profile <name> |
Creates a deployment folder from a profile | docker compose project creation |
hivedock add <package> / remove <package> |
Adds or removes a RunList entry | docker compose service add/remove |
hivedock adopt <package>@<version> |
Swaps a running package to a published release, with rollback | kubectl rollout |
hivedock status, logs <runtime>, restart <runtime> |
Supervision | systemctl status, journalctl -u, systemctl restart |
hivedock runtime list|start|restart |
One runtime at a time | docker ps, docker start |
hivedock service install|uninstall|status |
Puts HiveDock under the operating system's service manager | systemctl enable |
hivedock doctor, drift, explain-config |
Every copy of "what version is what", side by side; drift from a profile; where configuration came from | docker info, kubectl diff |
hivedock role add|remove|list |
Machine roles that releases address | Kubernetes node labels |
Who hivedock up runs as, in a folder: --home <login home>, else
--deployment <folder> (or HIVECAST_DEV_DEPLOYMENT), else the checkout's own
.hivecast/deployment. Inside a development checkout it refuses the machine-wide
~/.hivecast/deployment, because on shared machines that is devint.
Being deleted (design §15): the duplicate spellings start, dev,
runtimes, start-runtime, stop-runtime, restart-runtime,
reload-runtime, and the hivedock3 binary name. Use the verbs above.
Portable software setup and later connection
On macOS, Linux and Windows, the portable bundle can install software without opening sign-in, enrolling a device, or starting a service:
node install.mjs --install-root /absolute/path/to/hivecast install
The result is Installed, not Connected. Setup prints a retained connect
command and includes its executable and argument list in the JSON result.
Repeating install on a healthy installation is read-only and returns
changed: false: it keeps the saved release, platform and identity home,
without running npm or starting a service. An explicit different identity home
is refused. Use repair for damaged software or update to adopt a new release;
reopening a newer download does not silently update the existing installation.
Run that exact command later; append --headless when using SSH. It uses the
installed software and saved platform/identity home, without npm or the
original download. The retained package closure must remain present.
Successful explicit pairing then initializes the selected profile and installs
the operating-system service. A refused or expired pairing does neither; the
same connection command is retryable.
install accepts an optional --home for the identity location. connect
cannot change that home or the selected platform. No password, pending code,
or enrollment token is saved in setup state. Existing pair (also the default)
still installs and connects in one foreground flow; login remains access-only.
If command software is missing or damaged, run node install.mjs --install-root /absolute/path/to/hivecast repair from a current installer.
Repair verifies and reinstalls the installation's retained package version,
not the new download's packages. It accepts no identity or platform overrides
and does not rewrite the saved setup, package closure, credentials, settings or
service registration. Missing or changed retained artifacts are refused.
Windows also supports explicit install and retained connect: installation
exposes the bundled commands and writes .hivecast/connect.cmd, but does not
request sign-in or register a task. Opening that command later completes pairing
before registering the current user's logon task. A cancelled connection remains
retryable. Without --install-root, Windows retains the current user's default
identity and product home. pair and connect both complete visible sign-in and initialize
the deployment before asking hivedock service install to register its service.
Windows, macOS and Linux use this same lifecycle owner; the installer does not
create a separate task, launch agent or service. The Windows EXE chooses install, offers an unchecked Connect this
computer now option, and provides HiveCast Connect in the Start Menu.
Its uninstaller accepts a never-connected setup only when the exact retained
installation has an empty deployment and Task Scheduler confirms no product
task exists; initialized deployments still require the existing lifecycle teardown.
The portable entry still requires Node and npm for installation; this is not
a bundled-runtime native Mac installer.
A separate Windows installation
From an extracted portable bundle, use a dedicated absolute folder:
node install.mjs --install-root "C:\HiveDocks\Second Dock" install
& "C:\HiveDocks\Second Dock\connect.cmd"
The first command installs software only; the second starts ordinary pairing.
This copy has its own package closure, deployment and identity home. It does not
change the shared user PATH or replace the default installation. Its retained
connect.cmd and resume.cmd select this copy, and its npm\hivedock.cmd
selects this deployment even when called from another working directory. The
existing OS-service owner gives each deployment its own service name; one
HiveDock does not supervise the other.
For direct identity commands, explicitly select this copy's identity home, for
example --home "C:\HiveDocks\Second Dock\identity"; changing the working
directory alone does not select an identity. The portable route requires a
persistent Node/npm installation. Do not launch it with a temporary Node runtime
or one that will disappear when another installation is removed. The Windows
EXE still installs the default copy; a graphical Add HiveDock flow is separate.
Container with persistent installation state
The extracted customer bundle includes a Dockerfile. Build from that bundle
directory, not the repository or an existing installation:
docker build -t hivecast-user-machine:local .
docker volume create hivecast-installation
docker run -d --init --name hivecast \
--mount type=volume,source=hivecast-installation,target=/home/node/.hivecast \
hivecast-user-machine:local
docker logs hivecast
Image creation installs verified software only as the non-root node user;
it does not create an identity, enroll, start a service or configure inference.
The image includes Node. Its default command prints the real headless approval
link. The bundle's selected platform and advertised broker must be reachable
from the container; a host's loopback address is not a container route.
The retained installer run command calls the same pairing and hivecast up
owners in the foreground, with stop signals forwarded. No systemd or privileged
container is required. run requires an explicit dedicated installation root,
retains the installed platform and identity home, and refuses a running or
OS-service-managed deployment. Readiness comes from hivedock status --json,
not from the container merely having started.
Recreate the stopped container with the same named volume and image to retain
its identity, apps and settings. It reuses durable enrollment without another
approval or token exchange. Give a second installation a new empty volume;
never share a writable installation between running containers, copy an enrolled
volume into an image, or use docker commit to make an enrolled template. The
volume contains private machine credentials and must be protected accordingly.
Changing the image does not upgrade packages already retained in its volume.
For automation, use the installed hivecast installations prepare command on
that same volume to obtain its public installation ID, then issue a bound token
through Settings. Pass it over stdin by replacing the image's --headless
argument with --enrollment-token-stdin and using Docker's -i option; never put
the token in an argument, URL, image layer or environment variable. Container
restart policy and host boot return are operator choices, not native OS-service
acceptance.
The internal Mac wrapper is built from a clean committed bundle with
node tools/release/build-mac-installer.mjs --bundle <bundle.tgz> --output <HiveCast-Setup.pkg>.
It builds only the host architecture, installs HiveCast.app into the current
user's Applications folder, and includes its own verified Node/npm runtime.
Opening the app offers software installation into ~/.hivecast, then
Connect now or Finish for now. Pairing stays in the system browser;
launchd supervision starts at user sign-in, not before sign-in. The wrapper
does not migrate an older installation automatically. Its packaged terminal
entry is HiveCast.app/Contents/MacOS/HiveCast --setup [--install-root PATH] install|repair|connect|status.
Reopening checks the command package and offers Repair software if it is
missing or mismatched; it does not falsely report that copy as installed.
The native package is an unsigned, unnotarized internal candidate, not public
Mac delivery. Apple Silicon, native UI acceptance and reboot persistence need
their own target-machine verification; an Intel build proves none of those.
The Debian wrapper bundles Node/npm and installs only bootstrap files as root.
Run hivecast-setup install as the user who owns the installation, then
hivecast-setup connect (add --headless over SSH). Opening HiveCast Setup
installs the user's software and offers an optional Connect now prompt; choosing
Finish for now, or noninteractive use, does not request sign-in. The default
terminal action is software-only installation. hivecast-setup status inspects
retained setup and command availability without changing them. Later install
is a no-op when healthy, or repairs missing/mismatched command software from
the retained package. Explicit repair can restore damaged software too. connect
uses the retained package closure, platform and runtime, not a newly downloaded
bundle. Older installations without native setup custody are preserved and
must use their original setup command. Ordinary diagnostics and account-only
hivecast login do not require a completed pairing or service record.
Development sessions
hivedock up in a package directory is intentionally a foreground development
session. Its existing defaults remain: build, launch one source peer, renew its
ephemeral Directory projection, watch source, and tear down on Ctrl-C. A shell,
SSH session, CI step, or agent command wrapper is not a supervisor for a peer
that must remain available after that session ends.
Alongside its human-readable log, the command writes one JSON line for each
projection, ready, and source reload lifecycle event. Consumers select
only records with schema hivecast.folder-dev-session/v1; log wording is not an
interface.
When HIVECAST_FOLDER_DEV_SESSION_EVENT_LOG names a file, the command also
appends only those whitelisted lifecycle records there after applying core's
shared credential redaction. The file rotates by byte count at 1 MiB, including
when an existing crash remnant has no newline; human stdout and stderr never
enter this durable stream.
The checkout-bound development actor is the supervised exception: it resolves
this package's declared hivedock binary, records the detached process PID and
boot/start identity per application, and reattaches that custody after its own
bootstrap. An ordinary detached wrapper has neither that durable record nor a
safe PID-reuse check and remains unsupported.
Long-lived local development peers
Put the unchanged foreground command under the operating system's user-level process manager. Use one service identity per package directory, absolute paths for the package, deployment, executable, and logs, and the enrolled deployment's credential reference. Never copy credential contents into a unit, property list, scheduled task, command line, or repository file.
The manager must invoke hivedock up directly and keep that foreground process
as its child. Do not put &, nohup, Start-Process, disown, tmux, or a
session-owned command wrapper between them. Those forms can leave an orphaned
peer when the launching shell is reaped; they also hide the real exit status
from the manager. Restart-on-exit is the final safety net. Transient broker
loss is recovered in-process and must not produce a replacement peer.
Before enabling a manager, stop any existing foreground copy with Ctrl-C and
confirm no other hivedock up owns the package's mounts. Starting two copies
would make the NATS queue group split traffic between them.
Linux: systemd user unit
Create ~/.config/systemd/user/hivecast-dev-<package>.service:
[Unit]
Description=HiveCast local development peer for <package>
After=network-online.target
[Service]
Type=simple
WorkingDirectory=/absolute/path/to/package
ExecStart=/absolute/path/to/hivedock up --deployment /absolute/path/to/deployment
Restart=always
RestartSec=5
KillSignal=SIGTERM
[Install]
WantedBy=default.target
Then run systemctl --user daemon-reload,
systemctl --user enable --now hivecast-dev-<package>.service, and inspect
systemctl --user status hivecast-dev-<package>.service. Use
journalctl --user -u hivecast-dev-<package>.service -f for the complete
process log. systemctl --user stop ... is an intentional stop and is not
restarted despite Restart=always.
macOS: launchd LaunchAgent
Create ~/Library/LaunchAgents/ai.hivecast.dev.<package>.plist with absolute
paths and XML-escaped values:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>ai.hivecast.dev.<package></string>
<key>ProgramArguments</key>
<array>
<string>/absolute/path/to/hivedock</string>
<string>up</string>
<string>--deployment</string>
<string>/absolute/path/to/deployment</string>
</array>
<key>WorkingDirectory</key><string>/absolute/path/to/package</string>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>ThrottleInterval</key><integer>5</integer>
<key>StandardOutPath</key><string>/absolute/path/to/logs/dev-peer.log</string>
<key>StandardErrorPath</key><string>/absolute/path/to/logs/dev-peer.err.log</string>
</dict>
</plist>
Load it with
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.hivecast.dev.<package>.plist
and inspect it with
launchctl print gui/$(id -u)/ai.hivecast.dev.<package>.
launchctl bootout ... is the intentional stop path.
Windows: Scheduled Task
Create a stable user-owned PowerShell launcher outside the checkout. It must
set the package directory, invoke the absolute hivedock.cmd path with
up --deployment <absolute-deployment-path>, preserve $LASTEXITCODE, and
append stdout/stderr to stable log files. Register that launcher as the current
user with:
Set-Location 'C:\absolute\path\to\package'
& 'C:\absolute\path\to\hivedock.cmd' up --deployment 'C:\absolute\path\to\deployment' *>> 'C:\absolute\path\to\logs\dev-peer.log'
exit $LASTEXITCODE
- an
AtLogOntrigger (orAtStartupfrom an elevated shell); MultipleInstances = IgnoreNew;RestartCountgreater than zero and a boundedRestartIntervalsuch as five seconds; and- no execution time limit.
For example, build the settings with
New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -RestartCount 999 -RestartInterval (New-TimeSpan -Seconds 5)
and register one uniquely named task per package. Verify with
Get-ScheduledTask -TaskName <name> and
Get-ScheduledTaskInfo -TaskName <name>. Stop or disable the scheduled task
before starting a foreground copy.
Proving manager custody
Do not close the launching shell on faith. Record the manager's process view,
close that shell, and confirm the same foreground peer remains its managed
child: systemctl --user show <unit> -p MainPID -p ActiveState -p SubState,
launchctl print gui/$(id -u)/<label>, or Get-ScheduledTask plus
Get-ScheduledTaskInfo. Then interrupt the broker route without stopping the
manager and verify the peer PID does not change while its registration renews
again. Finally, terminate the peer process once and verify that the manager
starts a new PID. That last replacement proves only the safety net; the
same-PID transport recovery is the primary pass condition.
Transport recovery
The package-runtime connection owns one reconnect policy for TCP and WebSocket NATS: reconnect enabled, unlimited attempts while the host is operational, a 500 ms retry delay, and up to 250 ms jitter. Folder-dev registration renewal continues independently with bounded exponential backoff and refreshes the ephemeral projection after the connection returns. Authentication failures and an explicitly closed connection remain terminal; a transient disconnect does not require a second peer or a process restart.
Checking an ordinary source checkout
The CLI's native fixtures declare their real service/UI inputs as development
dependencies. They are not customer preinstallation requirements. Build the
declared graph before pnpm --filter @matrix/hivedock3-cli test; the Fleet
affected-owner qualifier does this and restores cached runtime publications
through tools/build/refresh-stale-bundles.mjs before running tests and typecheck.
A Turbo cache hit alone does not populate a new checkout's immutable build store.
Profile contract tests inspect authored manifests without starting the platform. Installed-composition tests copy committed published bytes, as the release packer does, rather than copying checkout-specific publication pointers. The native engine tests start and clean up their own isolated processes; they do not restart the shared environment. Fleet's canonical S30 lesson remains the product path for submitting the checked candidate to its independent integration owner.
Durable checkout peers
hivecast hivedocks create defaults to native-installation. Select
--profile agent-peer --checkout <absolute-git-worktree> with explicit
--scope and --install-root and an agent-peer portable bundle to retain a
checkout-bound coding peer. Prepare fixes the checkout and default workspace
in the immutable intent without installing software. Apply passes that binding
to the existing installer, which retains it with setup and derives its runtime
configuration from the bundled agent-peer recipe. Current-user OS service
custody, status, stop/start, resume and uninstall use the ordinary lifecycle.
Uninstall removes only this peer, preserving the repository checkout.
The portable bundle builder accepts --profile agent-peer; omitting the flag
still builds the minimal native-installation closure. Only explicit peer bundles
retain the agent-peer recipe and its declared runtime closure. Example:
node tools/release/build-user-machine-bundle.mjs --output <archive> --origin <https-origin> --profile agent-peer.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @matrix/runtime-host-engine | 1.1.33 |
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/identity-client | 1.1.33 |
| @open-matrix/package-runtime | 1.1.33 |
| @open-matrix/runtime-launcher3 | 1.1.33 |
| tsx | 4.15.6 |
Development Dependencies
| ID | Version |
|---|---|
| @hivecast/fleet-desk | 1.1.33 |
| @matrix/test-utils | 1.1.33 |
| @open-matrix/credential-plane | 1.1.33 |
| @open-matrix/dashboard-components | 1.1.33 |
| @open-matrix/executable-actor-control | 1.1.33 |
| @open-matrix/hermes-agent | 1.1.33 |
| @open-matrix/host-control | 1.1.33 |
| @open-matrix/service-module-gateway | 1.1.33 |
| @open-matrix/shell-frame | 1.1.33 |
| @open-matrix/system-observability | 1.1.33 |
| @open-matrix/system-platform | 1.1.33 |
| @open-matrix/system-registry | 1.1.33 |
| @types/node | ^25.0.10 |
| nats | ^2.29.3 |
| nkeys.js | ^1.1.0 |
| typescript | 5.9.3 |