@open-matrix/hivecast (1.1.33)
Installation
@open-matrix:registry=npm install @open-matrix/hivecast@1.1.33"@open-matrix/hivecast": "1.1.33"About this package
HiveCast Command Line
hivecast is your account (who you are, your keys, your machines) and the
product spelling of the other tools. This package also declares the matrix,
hivedock, hivedock3 and hive-pm binaries as thin forwarders, so one
global install gives every tool, the way the .NET SDK does. A forwarder never
reimplements a verb.
Prior art: gh and aws (account, keys, sessions); docker compose
forwarding to the engine for the porcelain verbs. One of five tools
(governing design §10.1).
Related UX opportunities
The signup, provisioning, installation and pairing study connects the existing retained setup operation to clearer progress and recovery, and separates minimal local installation from account availability. Current setup returns to Store with the exact computer selected; the person chooses an app there. A Store-to-setup-to-selected-app round trip is a proposed extension, not a demonstrated missing installer requirement. The study keeps the current CLI/workflow owners, without a replacement engine or GUI prerequisite. Reusable recipes are later ideas, not copies of machine credentials. These suggestions add no installer acceptance gates.
Verbs
| Verb | Does | Prior art |
|---|---|---|
hivecast login |
Signs in without enrolling the machine; writes the login home other commands read (--home, default ~/.matrix) |
gh auth login |
hivecast pair |
Enrols this machine as a managed device | az login + device registration |
hivecast setup-ssh <host> |
Inspects a known Linux SSH target; --action install installs a verified portable bundle, then --action connect requests headless approval |
System SSH + the standard user-machine installer |
hivecast hivedocks create|status|resume|cancel|start|stop |
Creates an independent HiveDock and controls its retained service locally or over SSH | Existing installer, enrollment and OS service owners |
hivecast register |
Creates an account | gh sign-up |
hivecast whoami / logout |
Shows or clears the signed-in identity | gh auth status / logout |
hivecast api-keys create|list|revoke |
Your API keys | gh auth token, AWS access keys |
hivecast installations list|revoke, disconnect |
Your managed machines | az devices |
hivecast installations prepare |
Prepares this target's public identity for one-time enrollment, without sign-in or an access grant | Device enrollment preparation |
hivecast fleet inspect |
Verifies this checkout's committed non-secret Fleet descriptor and prints the exact trust boundary; it does not enroll or claim work | gh repo view plus explicit cluster context review |
hivecast fleet eligible |
Discovers the installed repository/program/workload route through Registry and lists only central Tickets that its current worker can admit; it is read-only | gh issue list constrained by an owner-proved execution route |
hivecast fleet claim <ticket-id> |
Revalidates the eligible set, then invokes the installed route's existing atomic fleet.route.run operation exactly once |
An explicit queue claim through the owning coordinator |
hivecast invoke <mount> <operation> [payload] |
Calls any actor operation on the bus: forwards to matrix invoke. Anything a Console does, from the shell |
kubectl, curl |
hivecast up / down / status / dev / adopt |
Forward to hivedock |
docker compose |
hivecast release <package> |
Refuses: HiveCast releases as one service with one version, so a release is cut with pnpm release in a source checkout |
gh release create |
For example, signed in with hivecast login:
hivecast invoke system.registry registry.list '{}' --json
hivecast invoke system.directory directory.status '{}'
Do not install this package globally beside @open-matrix/cli unless you
deliberately want the package manager to choose which package owns the matrix
bin. The public getting-started path installs only hivecast.
Login
hivecast login opens the HiveCast browser login by default and always prints
the recovery URL. The platform resolves a new user's personal namespace, so
--space is optional on this door. To suppress the local browser launcher for
a browser sidecar or remote browser, use:
hivecast login --cloud https://hivecast.ai --no-open
Headless machines use one of two explicit stdin modes. A pre-issued API key has no
browser exchange from which to resolve a namespace, so it requires --space:
printf '%s\n' "$HIVECAST_API_KEY" \
| hivecast login --api-key-stdin --space personal-namespace
printf '%s\n' "$HIVECAST_PASSWORD" \
| hivecast login --password-stdin --email person@example.com
The two stdin modes are mutually exclusive. Secrets are never accepted as positional arguments or command-line option values.
Inspect a repository's selected Fleet home
Git-only development remains valid. Fleet participation is optional and begins with one authored, non-secret file at the verified Git root:
schema: hivecast.repository-participation/v1
repository:
locator: github.com/your-org/your-repository
fleet:
cloud: https://staging.hivecast.ai
workHome: chosen-authority-root
program: program:your-admitted-program
workload: source-check
repository.locator is the credential-free identity of the actual origin.
The cloud must be one HTTPS origin, workHome one canonical authority root,
program a program: identity, and workload a lowercase capability hint.
Unknown fields, YAML aliases, symlinks, untracked or modified descriptors, and a
copied descriptor whose origin differs all refuse. Credentials, broker URLs,
mutable development targets, task IDs and grants are not descriptor fields.
There is no ambient descriptor or home fallback. hivecast fleet inspect
starts at --repository or the current directory, resolves its real Git root,
and reads exactly that root's committed .hivecast/estate.yaml. Descriptor
values win because there are no command-line or environment overrides for
them. The command prints the exact source revision, cloud, work home, program,
workload and incumbent system.tickets / system.fleet owners without writing
an identity, selecting a development target, discovering work or claiming it:
hivecast fleet inspect
hivecast fleet inspect --json
After comparing those public values, authenticate through the existing owner:
hivecast fleet join --trust-revision <exact-revision-from-inspect>
fleet join re-reads the descriptor and refuses when the checkout revision has
changed. It accepts no cloud or work-home override and delegates to the same
installed identity owner as hivecast login. Its next step acts through the
person-owned Tickets and Fleet services, so a new join uses the short-code
browser door and explicitly asks Let this command line act as you?. Refusal,
expiry or interruption retains repository trust, pairing and installation
state; repeat the same join instead of pairing or enrolling again. Automation
may supply an already approved account-session key over stdin only after
revision-bound trust:
printf '%s\n' "$HIVECAST_API_KEY" \
| hivecast fleet join --trust-revision <exact-revision> --api-key-stdin
The key is neither printed nor stored in Git. An ordinary access or installation key is not silently widened and will be refused by the owner proof. Successful session consent validates the exact descriptor-selected home; it does not pair a worker, discover work or claim a ticket. Pair a qualified worker only when the selected workload requires one; account-session consent is not a Fleet-claim grant.
After sign-in, prove that the stored signed-person session resolves the exact declared home and its published Tickets and Fleet owners:
hivecast fleet status --trust-revision <exact-revision-from-inspect>
hivecast fleet status --trust-revision <exact-revision-from-inspect> --json
fleet status revalidates the descriptor/revision, exchanges the existing
stored identity for short-lived proof, and calls $ping on the contract-owned
system.tickets and system.fleet mounts. Transport is resolved by the existing
package runtime; repository DNS is never converted into a broker or subject.
The command refuses a different authority root, a credential not issued into
the home account, or an owner reply that does not name the exact home and mount.
Output contains only public owner/root and timing facts—never the API key,
short-lived proof, JWT, seed, broker URL, or credential path. This is owner
reachability and identity proof, not ticket discovery or claim.
To discover work without creating a second backlog or starting a worker, ask Registry for an installed route that advertises the Fleet route interface and proves the exact repository, program, workload, admitted recipe, and currently ready configured worker:
hivecast fleet eligible --trust-revision <exact-revision-from-inspect>
hivecast fleet eligible --trust-revision <exact-revision-from-inspect> --json
The command reads the selected home's shared board from central system.tickets
with the descriptor's program filter, so eligible work filed by other people
can appear. Tickets still applies the caller's read permissions within that
home. The client keeps only unclaimed source-ready cases for the program and
the route's supported ticket kinds, and asks that route to explain the exact
admitted recipe. It performs no claim, ticket transition, task creation,
session start, or workspace mutation. If no installed route admits all three
coordinates—or more than one does—the command refuses rather than guessing.
Claiming is a separate, explicit action using a ticket returned by the current eligible read:
hivecast fleet claim <ticket-id> --trust-revision <exact-revision-from-inspect>
Before acting, the client repeats repository trust, route discovery, worker
readiness, and central-ticket eligibility. It then calls the one incumbent
atomic operation, fleet.route.run, on that exact owner-qualified route.
Central Tickets still owns the claim and workflow binding; the installed Fleet
route still owns worker selection and retained execution. Repeating the command
therefore observes or continues those owner records rather than creating a
client-side assignment. The joining checkout is never assumed to be the source
worker, and repository metadata never grants claim authority.
Demos lesson
S30, “Run a Fleet ticket through its owners,”
is the canonical executable explanation of the same repository/program/workload
discovery and admitted ticket → attempt → independent integration route. After
the native inspect/join/eligible selection, S30 queries the current home Registry
for that exact relation and accepts exactly one non-claiming route description.
It still requires the person's explicit Continue action before the same
fleet.route.run operation used by fleet claim. Native inspection/login
remains outside an already connected Shell and S30 never pretends that reading,
discovery, or filing a ticket enrolled this checkout. Until its installed
browser walk passes, the Demos catalogue truthfully labels it planned.
hivecast up forwards to the installed HiveDock workflow. Add --explain to
print its read-only hivedock init (when fresh) plus hivedock start
decomposition and consume-once source labels.
Add an independent local HiveDock
Use an extracted, verified native-installation portable download. The command requires Node/npm and the supported current-user service manager; it does not install the whole platform or replace an existing HiveDock.
hivecast hivedocks create --bundle /path/to/extracted-download --request-id my-second-hivedock --label "Work"
hivecast hivedocks status <operation-id> --json
hivecast hivedocks resume <operation-id>
hivecast hivedocks stop <operation-id>
hivecast hivedocks start <operation-id>
For a durable coding peer, select --profile agent-peer and a verified
agent-peer bundle. Supply explicit --scope, --install-root and --checkout
(the absolute root of an existing Git checkout or worktree). The immutable
intent retains the canonical checkout and defaultWorkspace.workingDirectory.
The installed recipe sets the existing Codex peer's default working directory;
worker.status advertises its workspace and coding capabilities. The same
current-user OS service owns startup and restart. Status, stop/start and
uninstall operate only on this installation; uninstall never deletes the
associated checkout. The agent-peer bundle seals only the coding peer runtime
closure; it does not copy the product's starter applications onto the worker.
Native installation remains the default. Checkout peer
creation is local (including the local web review); SSH creation does not
accept checkout/profile overrides.
hivecast hivedocks create --bundle /path/to/agent-peer-download --request-id checkout-peer \
--profile agent-peer --checkout /path/to/checkout \
--scope /path/to/management --install-root /path/to/peer --label checkout-peer --prepare-only
Add --web to create or resume for a guided local review, ordinary browser
approval, live runtime observation, and a Store link pinned to that installation.
The screen uses the same operation as the terminal. Refreshing the tab does not
create another HiveDock. Keep the runner open; Finish for now pauses at the
next safe boundary, and the printed continuation command reopens the saved
operation. Signing in and approving the device still happen on the selected
platform, never in the loopback screen. This portable path uses Node.js 22+ and
npm already on the computer; it does not install the shared platform.
The saved request fixes the installation identity, destination, platform and
release. Repeating it does not create another peer. --prepare-only returns its
public installation identity and intent digest without installing software;
apply <operation-id> --intent-digest <digest> accepts that review.
--defer-enrollment installs software but leaves sign-in for a later resume.
Resume supports ordinary browser approval, --headless, or
--enrollment-token-stdin; credentials never enter the operation record.
Status reads the installed identity/runtime owners, not just saved progress.
Locally ready, remotely discoverable and application usable are separate facts.
An intentionally stopped peer is reported as stopped, not as a failed install.
Start/stop keep its identity, installed applications, settings and service registration;
they do not pair again, recreate a missing service or touch another HiveDock.
These commands also accept the same --ssh, --setup-root and remote --scope
options as creation. If an effect's reply is lost, read status before repeating it.
Cancel stops at a safe boundary and retains installed files and services. Use
the existing uninstall workflow to remove them. Prepared reviews expire after
24 hours; accepted operations remain resumable. One worker runs per local
management scope, with at most 256 retained operations; active operations are
never evicted. Account-managed creation in Machines is a separate surface.
Opt-in account-managed peer controls
On the target computer, the OS user can enable a native installation to expose its registered same-home peers. This is a local decision, not a remotely callable self-grant. Keep the management scope outside the hosting deployment:
hivecast hivedocks manage enable --deployment /path/to/host/deployment --scope /path/to/management
hivecast hivedocks manage status --deployment /path/to/host/deployment --json
hivecast hivedocks manage disable --deployment /path/to/host/deployment
The exact hivedock-capabilities.management.<installation-mount> endpoint offers
collection.describe / collection.list (collection: "hivedocks") and the
shared HIVEDOCK_MANAGED_OPERATIONS status/start/stop contract. Its collection
returns the scope ID/revision and each retained target's operation ID, identity
and intent digest; controls must echo those coordinates with a request ID.
Collection rows show Check status, not stale journal health. Live status
comes from the selected installation's existing owners.
The capabilities owner separately grants hivedock-managed-read,
hivedock-managed-start and hivedock-managed-stop on the hosting installation.
Existing discovery and application-installation grants are unchanged. Every
request checks current permission, local enablement, same-home custody and exact
target. No remote path, command, environment or enrollment token is accepted.
Repeating a request ID returns its retained result, so an old Start does not undo
a newer Stop; read live status separately. Reusing it for another action refuses.
Each peer retains up to 256 remote control receipts; reaching this bound refuses
new requests rather than silently forgetting replay protection. Local/SSH
controls remain available.
Disabling the role does not stop peers. Stopping its hosting HiveDock makes this
remote route unavailable but does not stop peers. This endpoint currently offers
read/start/stop only; it does not yet advertise remote creation, update, removal,
or a Machines creation form. The fixed managed-request stdin protocol is an
internal trusted OS-user subprocess boundary, not an unauthenticated network API.
Create or resume through SSH
Once setup-ssh --action install has installed a Linux runner, the same creation
command can run there using its verified retained bundle:
hivecast hivedocks create --ssh user@server --setup-root /home/user/hivecast \
--request-id workshop-peer --label "Workshop" --prepare-only --json
hivecast hivedocks resume <operation-id> --ssh user@server --setup-root /home/user/hivecast
hivecast hivedocks status <operation-id> --ssh user@server --setup-root /home/user/hivecast --json
The runner need not be signed in. Each peer gets its own identity, minimal
installation and current-user service. Approval opens on the selected platform
in your browser; the runner's credentials are never reused. The default
management scope is the remote user's ~/.hivecast/management. An explicit
--scope or --install-root is also remote and must stay inside that user's home,
outside the setup runner. --bundle, --web and enrollment-token input are not
accepted on this SSH door. Repeat the same request or resume its operation after
interruption; never create a replacement to retry. The printed continuation
retains the SSH host, port, runner and scope. Existing known-host checks apply.
Install on another Linux computer
For unattended enrollment, run hivecast installations prepare --cloud https://YOUR_PLATFORM --json
on the target. In that platform's Settings → Devices → Advanced: one-time enrollment
token, paste the public JSON, review the exact target and create its short-lived
token. Transfer the downloaded token through your protected file/secret channel
and feed it to hivecast pair --enrollment-token-stdin on that target, with the
same --cloud and --home (if supplied). The public preparation is not a credential
or proof of ownership. Repeating preparation retains the installation identity;
never copy its identity home into a machine/container template. Enrollment and
starting a background HiveDock remain distinct steps; the retained installer
connect --enrollment-token-stdin performs both for installed software.
Repeating the retained installer's connect on an initialized, running
deployment reads its actual runtime status and returns existing-deployment.
It does not sign in, consume another token, change identity, or restart services.
An initialized deployment that is stopped or cannot answer status is preserved
and reported as needing attention; inspect it with hivecast status from its
deployment directory. Re-pairing is not a repair action, and changing accounts
requires an explicit disconnect. An interruption before deployment initialization
is not covered by this completed-setup rerun path.
On macOS, reopening HiveCast reads the retained deployment. If its recorded launchd service is stopped, Start HiveDock starts that same service without another sign-in or enrollment. Setup then checks runtime readiness separately; an accepted start request is not a running confirmation. An unknown or unmanaged service is never replaced automatically. Starting an already-running installation is a read-only no-op.
Use an existing SSH configuration alias or user@host. The remote user must be
unprivileged and have Node.js 22+, npm and tar. The install action installs
software only: it does not enroll the machine or start a background service.
It uses your SSH configuration/key agent without forwarding the agent. Unknown
or changed host keys are refused; independently verify the server fingerprint
and update your SSH configuration before retrying. No private key is uploaded.
hivecast setup-ssh user@server --install-root /home/user/hivecast
hivecast setup-ssh user@server --install-root /home/user/hivecast \
--action install --bundle ./hivecast-user-machine.tgz --sha256 TRUSTED_BUNDLE_SHA256
hivecast setup-ssh user@server --install-root /home/user/hivecast \
--action connect --name 'Workshop Linux'
The first command is read-only. Installation verifies the reviewed digest on
both machines, extracts only the portable bundle layout and calls its normal
installer. The bundle retains its own platform origin. Output includes progress
and the retained connection command. The explicit connect action runs that
installer's headless flow and prints a browser approval link and matching code.
It preserves the installed platform and identity home; it never forwards the
runner's account credentials or replaces an existing enrollment. Credentials or
an existing deployment cause a refusal with recovery guidance. Installer success
and runtime readiness are separate outcomes. Existing nonempty directories are
never overwritten. Disconnecting stops the setup process and any pending pairing
wait, not an independently managed service. After a dropped connection, inspect the same directory and
use its retained installer; do not erase an installation to retry. Other target
operating systems, elevation and automatic Node installation are not supported
by this command.
Guided installation from a local runner
Start --web with the verified artifact, then choose the SSH host and installation
folder in the browser. You can also preselect them with the normal CLI arguments:
hivecast setup-ssh --web --bundle ./hivecast-user-machine.tgz --sha256 TRUSTED_BUNDLE_SHA256
Open the printed loopback URL on the runner computer. The page identifies this runner, checks the known SSH host and requirements, then reviews the target, remote account, package version, platform and path before Install on this machine. It calls the same installer as the terminal command. The browser can choose an SSH alias or user@host, an optional port, and a dedicated installation folder. Selection alone opens no SSH connection. Changing the selection clears its review and readiness; stale-tab actions are refused. The artifact and platform stay pinned, and the browser cannot send a shell command or upload a key. A first-seen host shows OpenSSH's SHA-256 fingerprint. Compare it with an independently trusted source, then explicitly confirm it; OpenSSH saves the accepted key in its existing known-hosts configuration. Cancelling accepts no key. Changed keys are blocked, not offered for replacement. Resolve those with the owner in your SSH configuration. The runner uses public-key authentication and refuses password/passphrase prompts; unlock an existing key in your SSH agent before connecting. This is a local product runner, not a platform-selected paired-machine runner or a Codex capability.
Software installation finishes without enrollment or service startup. Choose
Connect now separately, or close the runner and use the retained
setup-ssh ... --action connect command later. Returning to the same verified
artifact and unpaired installation also offers Connect now. The guided flow
shows the existing identity owner's short code and approval link on the
reviewed platform; sign-in and consent stay there, not on the local runner.
The remote installer rechecks the retained platform and source revision before
requesting approval. Completion means enrollment and service setup finished,
not runtime or application readiness. Check runtime status reads the installed
enrollment and HiveDock owners without signing in, restarting or repairing.
It shows the exact installation, live versus persisted status, configured runtime
counts and observation time. Only a live supervisor with every configured runtime
running earns a ready result; this is not an application behavior test. Returning
with the same artifact and folder can inspect status without granting access again.
The same read-only observation is available with setup-ssh ... --action status.
After readiness, Choose an app for this HiveDock opens the platform Store
with the exact public installation selected. Sign in to its owning home, then
choose an app's Install on a HiveDock action. Review resolves that installation
through the existing discovery owner; missing or foreign targets are never
replaced with another machine. The link grants no access, installs nothing,
and carries no credential. Choose a different HiveDock explicitly returns
to the normal picker. Hosted Add to my home remains a separate action.
Existing credentials or a partial
deployment require the retained installer's recovery instead of a fresh grant.
Keep the runner terminal open. Cancel setup stops the owned setup process, retains remote
files and requires another inspection before retrying. Closing the browser
alone does not cancel a running installation. Close runner (or Ctrl+C in
its terminal) closes the local listener and cancels pending setup, but never
stops independently managed HiveDock services. Existing folders are not erased
or overwritten. No private key or account credential goes to this web page.
Native Windows release signing
Unsigned internal builds remain available. Trusted distribution uses the existing
Azure Artifact Signing decision, not a second installer: NSIS 3.09+ on Linux,
Jsign 7.6 and osslsigncode 2.5+ with current system CA certificates. The publisher
must first have a validated Azure Public Trust certificate profile and signing
role. Supply its short-lived access token through the builder's protected
HIVECAST_WINDOWS_SIGNING_TOKEN environment variable; never put the token in a
command argument, source, log or artifact. Obtain it through the existing Azure
identity/secret workflow for the https://codesigning.azure.net resource.
node tools/release/build-windows-installer.mjs \
--bundle /absolute/path/hivecast-user-machine.tgz \
--output /absolute/path/HiveCast-Setup.exe \
--signing-endpoint REGION.codesigning.azure.net \
--signing-profile ACCOUNT/PROFILE
Both options are required together. The builder signs and verifies the generated uninstaller before embedding it, then signs and verifies the final setup EXE. Azure's timestamp is mandatory. It records the verified publisher subject, selected signing profile and final signed bytes in the manifest only after both operations succeed; failure leaves the previous output untouched. Node retains its vendor signature. No certificate trust store or Windows protection is changed. The build-side signing helper is not installed on the user's machine.
Run HIVECAST_REQUIRE_NSIS_SIGNING_TEST=1 node --test tools/release/windows-installer/signing.test.mjs
on the Linux builder to exercise the actual product NSIS hook and its failure
path. This is integration coverage, not a real Azure signature or customer
acceptance. Actual signing access, Windows trusted-publisher verification and
public promotion remain release prerequisites; signing alone does not promise
zero SmartScreen reputation warnings. Changed bytes require a new release
version, never replacement of an immutable unsigned release.
See Jsign's Azure Artifact Signing integration and NSIS's standard uninstaller signing hook.
Native macOS release signing
The native wrapper still uses the same packaged installer. Build from a clean
exact source revision and its matching portable bundle. Omitting signing options
keeps the explicit unsigned internal-build path. For trusted distribution,
configure Developer ID Application and Developer ID Installer certificates for
the same Apple team in the builder's keychain, and store notarization credentials
with Apple's xcrun notarytool store-credentials interactive/keychain workflow.
No password, private key or API key belongs in a command argument or repository.
node tools/release/build-mac-installer.mjs \
--bundle /absolute/path/hivecast-user-machine.tgz \
--output /absolute/path/HiveCast-Setup.pkg \
--sign-application 'Developer ID Application: Publisher (TEAMID1234)' \
--sign-installer 'Developer ID Installer: Publisher (TEAMID1234)' \
--notary-profile hivecast-release
All three signing options are required together. The builder signs Node with
hardened runtime and JIT/native-addon entitlements, without the vendor binary's
debugging entitlement, then runs and verifies that exact executable. The final
executable digest distinguishes its retained runtime from unsigned copies;
existing running runtimes are not overwritten. It signs the app inside-out,
builds the signed package, requires Apple's Accepted notarization response,
staples and validates the ticket, and checks macOS installation assessment.
Only then does it record signed: true, notarized: true, the team/submission
identifiers and the final package digest. A refusal publishes neither a new
output nor a success manifest. No Gatekeeper setting is changed.
Implementation and local tooling tests are not an Apple-approved release. An actual Developer ID/notarization run, native install/launch acceptance and public promotion remain separate release gates. Use a new release version for changed bytes; never replace an already-published unsigned artifact in place.
This uses Apple's standard notarization workflow, not an App Store submission or an alternate installation engine.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @matrix/hivedock3-cli | 1.1.33 |
| @open-matrix/cli | 1.1.33 |
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/hive-pm | 1.1.33 |
| @open-matrix/hivecast-brand | 1.1.33 |
| @open-matrix/identity-client | 1.1.33 |
| @open-matrix/subjects | 1.1.33 |
| commander | ^11.0.0 |
| yaml | ^2.8.1 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 1.1.33 |
| @types/node | ^25.0.10 |
| esbuild | ^0.27.3 |
| tsx | ^4.15.6 |
| typescript | ^5.7.0 |