@matrix/hivedock3-cli (0.1.74)
Installation
@matrix:registry=npm install @matrix/hivedock3-cli@0.1.74"@matrix/hivedock3-cli": "0.1.74"About this package
HiveDock command line
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.
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.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @matrix/runtime-host-engine | 0.1.59 |
| @open-matrix/contracts | 0.1.25 |
| @open-matrix/core | 0.1.31 |
| @open-matrix/package-runtime | 0.1.35 |
| @open-matrix/runtime-launcher3 | 0.1.43 |
| tsx | 4.15.6 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 0.1.0 |
| @types/node | ^25.0.10 |
| nats | ^2.29.3 |
| typescript | 5.6.3 |