@hivemagnus/magnus-server 0.0.0-stage → 1.0.1

package/.env.example

@@ -0,0 +1,171 @@
+# magnus-server configuration example.
+#
+# Copy to a private file (for example ~/.magnus/server.env, mode 0600) and
+# pass it with `magnus-server --env-file <path>`, or use it as the Compose env
+# file (docker/compose.yml). Variables already set in the environment win.
+# An empty value means "unset". `magnus-server env-schema --format table`
+# lists every documented variable; `magnus-server check` validates this file.
+#
+# Generate each secret with:  openssl rand -hex 32
+# Every secret must be distinct; there are no fallback values.
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Required
+# ═══════════════════════════════════════════════════════════════════════════
+
+NODE_ENV=production
+
+# PostgreSQL. Required in production. (Development falls back to
+# postgresql://magnus@127.0.0.1:5432/magnus with no password.)
+DATABASE_URL=postgresql://magnus:change-me@127.0.0.1:5432/magnus
+# Used only by docker/compose.yml to initialise its PostgreSQL container.
+POSTGRES_PASSWORD=
+# Redis (queues, rate limits, event bus).
+REDIS_URL=redis://127.0.0.1:6379
+# Used only by docker/compose.yml.
+REDIS_PASSWORD=
+
+# Purpose-specific secrets, 32+ characters each.
+API_SECRET=
+JWT_SECRET=
+NODE_MANAGER_SECRET=
+AUDIT_HMAC_SECRET=
+RESULT_SIGNING_SECRET=
+LOG_INGEST_SIGNING_SECRET=
+CREDENTIAL_ROTATION_KEY=
+METRICS_TOKEN=
+WEBHOOK_ENCRYPTION_KEY=
+
+# HTTPS listener. TLS is required in production. Relative paths resolve
+# against the working directory; absolute paths are recommended.
+TLS_CERT_PATH=/etc/magnus-server/tls/server.crt
+TLS_KEY_PATH=/etc/magnus-server/tls/server.key
+CONTROL_API_PORT=4000
+# CONTROL_API_BIND_HOST=0.0.0.0
+# Public URL of this server; agents use it to report back.
+CONTROL_API_URL=https://magnus.example.com:4000
+# Browser origins allowed to call the API (the Magnus dashboard).
+CORS_ORIGIN=https://magnus.example.com:3000
+# DASHBOARD_PUBLIC_ORIGIN=https://magnus.example.com:3000
+
+# Local development only: serve cleartext HTTP on loopback without a certificate.
+# ALLOW_INSECURE_HTTP=true
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Paths (optional)
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Base directory for audit logs, credential rotation state and backups.
+# MAGNUS_HOME=~/.magnus
+# AUDIT_LOG_DIR=$MAGNUS_HOME/audit-logs
+# CREDENTIAL_ROTATION_STATE_PATH=$MAGNUS_HOME/state/credential-rotations.json
+# SKILLS_DIR=                     # defaults to the bundled @hivemagnus/magnus-skills catalogue
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Agents (optional)
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Let agents self-register through the discovery endpoint.
+# ENABLE_AGENT_DISCOVERY=true
+# AGENT_DISCOVERY_SECRET=
+# DNS suffix used to derive agent certificate hostnames, and an optional
+# suffix under which agents report their FQDN (for example an overlay network).
+# AGENT_TLS_DOMAIN_SUFFIX=example.com
+# MAGNUS_NODE_DNS_SUFFIX=nodes.example.com
+# SSH credentials for installing and upgrading agents over SSH.
+# SSH_USERNAME=deploy
+# SSH_PRIVATE_KEY_PATH=/etc/magnus-server/ssh/id_ed25519
+# SSH_HOST_KEY_PINS_FILE=/etc/magnus-server/ssh/host-key-pins.json
+# SSH_PASSWORD=
+# Account whose docker group membership is checked on the server host.
+# MAGNUS_DOCKER_USER=deploy
+# Durable node and shared-resource lease coordination.
+# MAGNUS_RESOURCE_LEASES_ENABLED=true
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Optional integrations — each is off until configured
+# ═══════════════════════════════════════════════════════════════════════════
+
+# ── Hive IAM: verify RS256 access tokens issued by Hive IAM ──
+# When set, JWT_SECRET is no longer required for user tokens.
+# IAM_CORE_URL=https://iam.example.com
+# IAM_TOKEN_ISSUER=https://iam.example.com
+# IAM_TOKEN_AUDIENCE=magnus
+
+# ── Hive Router (or any OpenAI-compatible router) for managed Hermes Agents ──
+# HIVE_ROUTER_URL / HIVE_ROUTER_MODEL / HIVE_ROUTER_API_KEY are accepted as aliases.
+# MAGNUS_ROUTER_URL=https://router.example.com/v1
+# MAGNUS_ROUTER_MODEL=
+# MAGNUS_ROUTER_API_KEY=
+# HIVE_ROUTER_HEALTH_URL=https://router.example.com/health
+
+# ── HiveMem shared agent memory ──
+# HIVEMEM_URL=https://hivemem.example.com
+# HIVEMEM_TOKEN=
+# MAGNUS_LESSONS_HIVEMEM_URL=
+# MAGNUS_LESSONS_HIVEMEM_TOKEN=
+
+# ── Security Fusion / external security console ──
+# off (default): disabled, /api/v1/security-fusion/* answers 404.
+# local: cases, evidence and receipts live in this server's database.
+# remote: observations are exported to an external security console.
+# SECURITY_FUSION_MODE=off
+# local mode:
+# SECURITY_FUSION_RECEIPT_SIGNING_KEY=
+# SECURITY_FUSION_EVIDENCE_DIR=$MAGNUS_HOME/security-fusion/evidence
+# SECURITY_FUSION_CONTAINMENT_COMMAND=/usr/local/sbin/your-containment-helper
+# SECURITY_FUSION_MATTERMOST_URL=https://chat.example.com
+# SECURITY_FUSION_MATTERMOST_BOT_TOKEN=
+# SECURITY_FUSION_MATTERMOST_CHANNEL_ID=
+# remote mode:
+# MAGNUS_SECURITY_CONSOLE_URL=https://security.example.com
+# SECURITY_FUSION_API_URL=https://security.example.com
+# SECURITY_EXPORT_ENABLED=true
+# SECURITY_EXPORT_SECRET=
+# SECURITY_SUMMARY_TOKEN=
+# SECURITY_INVENTORY_TOKEN_SHA256=
+# SECURITY_BACKUP_TOKEN_SHA256=
+# SECURITY_BACKUP_DIRECTORY=$MAGNUS_HOME/security-backups
+
+# ── Hermes Agent plugin API ──
+# Plugin credentials are ignored and plugin routes are unreachable unless enabled.
+# Store only SHA-256 digests of the tokens here.
+# MAGNUS_PLUGIN_API_ENABLED=true
+# MAGNUS_PLUGIN_READ_TOKEN_DIGESTS_JSON={"hermes-1":"<sha256 of the read token>"}
+# MAGNUS_PLUGIN_OPERATOR_TOKEN_SHA256=
+# Plugin read consumer allowed to relay signed team-approval decisions, plus the
+# Ed25519 key and actor bindings those decisions are verified against.
+# MAGNUS_APPROVAL_BRIDGE_CONSUMER=hermes-1
+# APPROVAL_SIGNER_PUBLIC_KEY_PATH=/etc/magnus-server/approval-signer.pub
+# APPROVAL_TELEGRAM_ACTOR_SHA256=
+# APPROVAL_IPHONE_ACTOR_SHA256=
+# Read-only digests for an external observability collector and the fleet-check reporter.
+# MAGNUS_COLLECTOR_TOKEN_SHA256=
+# MAGNUS_FLEET_CHECK_TOKEN_SHA256=
+
+# ── Hermes registry (skills, plugins, MCP backends) ──
+# Background import of the bundled skill catalogue and plugin source monitoring.
+# MAGNUS_HERMES_REGISTRY_ENABLED=true
+# Short hostnames (optionally host:stage; stage 0 = canary) that may pull deployments.
+# MAGNUS_REGISTRY_DEPLOY_HOSTS=canary-1:0,node-1:1,node-2:2
+# Hosts that may submit changes but never pull.
+# MAGNUS_REGISTRY_SUBMIT_ONLY_HOSTS=
+
+# ── Fleet AI assistant (all optional) ──
+# OLLAMA_URL=http://127.0.0.1:11434
+# OLLAMA_MODEL=
+# LLAMACPP_URL=http://127.0.0.1:8080
+# OPENAI_API_KEY=
+# OPENROUTER_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Tuning (optional)
+# ═══════════════════════════════════════════════════════════════════════════
+
+# LOG_LEVEL=info
+# DATABASE_POOL_SIZE=20
+# LOG_RETENTION_DAYS=30
+# HEALTH_SNAPSHOT_RETENTION_DAYS=7
+# NOTIFICATION_READ_RETENTION_DAYS=30
+# NOTIFICATION_MAX_RETENTION_DAYS=90

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @hivemagnus/magnus-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Magnus server is the control plane of a Magnus fleet. It is a Hono API
+server backed by PostgreSQL and Redis that Linux hosts running
+[`@hivemagnus/magnus-agent`](../../packages/agent) report to, and that the
+[Magnus dashboard](../../apps/dashboard) talks to.
+
+It keeps the fleet inventory and desired state, ingests agent heartbeats,
+health snapshots and logs, dispatches signed commands, cron jobs, file syncs
+and skill installs through a durable queue, and records every change in an
+append-only audit log. Optional modules add anomaly detection and remediation
+plans, rollouts, webhooks, an AI fleet assistant, Hermes Agent and Ardent
+management, and Security Fusion.
+
+## Requirements
+
+- Node.js `^24.22.1 || ^26.13.0`
+- PostgreSQL 15 or later
+- Redis 7 or later
+- A TLS certificate for production (cleartext HTTP is a loopback-only development opt-in)
+
+## Install
+
+```bash
+npm install -g @hivemagnus/magnus-server
+magnus-server --help
+```
+
+The package ships compiled JavaScript, the generated Prisma client, the Prisma
+schema and every migration, so it needs no install-time code generation.
+
+## Configure
+
+All configuration comes from environment variables. Start from the documented
+example:
+
+```bash
+mkdir -p ~/.magnus && cp "$(npm root -g)/@hivemagnus/magnus-server/.env.example" ~/.magnus/server.env
+chmod 600 ~/.magnus/server.env
+# fill in DATABASE_URL, REDIS_URL, TLS paths and the required secrets
+# (one `openssl rand -hex 32` each; every secret must be different)
+```
+
+`magnus-server env-schema --format table` lists every documented variable and
+`magnus-server env-schema` prints the same list as JSON.
+
+**Required:** `DATABASE_URL` (in production), `REDIS_URL`, `API_SECRET`,
+`JWT_SECRET` (unless Hive IAM is configured), `NODE_MANAGER_SECRET`,
+`AUDIT_HMAC_SECRET`, `RESULT_SIGNING_SECRET`, `LOG_INGEST_SIGNING_SECRET`,
+`CREDENTIAL_ROTATION_KEY`, `METRICS_TOKEN`, `WEBHOOK_ENCRYPTION_KEY`, and in
+production `TLS_CERT_PATH` / `TLS_KEY_PATH`. The server refuses to start while
+any is missing; there are no fallback secret values.
+
+Local data (audit logs, credential rotation state, uploaded backups) lives
+under `MAGNUS_HOME`, default `~/.magnus`.
+
+## Run
+
+```bash
+magnus-server check   --env-file ~/.magnus/server.env   # validate env, reach PostgreSQL and Redis, list integrations
+magnus-server migrate --env-file ~/.magnus/server.env   # apply migrations and base data
+magnus-server start   --env-file ~/.magnus/server.env   # or: start --migrate
+```
+
+| Command | Purpose |
+| --- | --- |
+| `start` (default) | Start the API server. `--migrate` applies pending migrations first. |
+| `check` | Validate configuration, connect to PostgreSQL and Redis, report pending migrations and enabled integrations. Exits non-zero on a problem. |
+| `migrate` | Run `prisma migrate deploy` with the packaged schema and migrations, then create the base rows (system actor, sentinel nodes, starter library). Idempotent. |
+| `env-schema` | Print the documented environment variables (`--format json` or `table`). |
+| `version`, `help` | Print the version or usage. |
+
+`--env-file <path>` may be repeated. Variables already set in the process
+environment take precedence, and empty values count as unset.
+
+The API is served under `/api/v1`, interactive documentation at `/api/docs`
+(OpenAPI 3.1 JSON at `/api/docs/openapi.json`), and Prometheus metrics at
+`/metrics` (bearer `METRICS_TOKEN`).
+
+### Docker Compose
+
+[`docker/compose.yml`](docker/compose.yml) runs magnus-server with PostgreSQL
+and Redis. The image is built from the monorepo root with
+[`Dockerfile`](Dockerfile): it builds and `npm pack`s the server and its
+workspace dependencies, then installs those tarballs exactly as an npm user
+would.
+
+```bash
+cp services/control-api/.env.example services/control-api/docker/.env   # set POSTGRES_PASSWORD, REDIS_PASSWORD and the secrets
+docker compose -f services/control-api/docker/compose.yml --env-file services/control-api/docker/.env up -d --build
+```
+
+Compose refuses to start while a required secret is missing. The server
+listens on `https://127.0.0.1:4000`; without a mounted certificate it
+generates a self-signed one for `MAGNUS_TLS_HOSTNAMES` (default `localhost`)
+in its data volume, which is meant for evaluation only. To use a real
+certificate, mount it and set `TLS_CERT_PATH` and `TLS_KEY_PATH`.
+`bash services/control-api/scripts/check-compose.sh` brings the stack up with
+throwaway secrets, checks it end to end and removes it again.
+
+## Optional integrations
+
+Every integration is off until it is configured; the server starts and runs
+without any of them. `magnus-server check` prints which are on.
+
+| Integration | What it adds | Environment |
+| --- | --- | --- |
+| Hive IAM | RS256 access tokens issued by Hive IAM replace locally issued JWTs | `IAM_CORE_URL`, `IAM_TOKEN_ISSUER`, `IAM_TOKEN_AUDIENCE` |
+| Hive Router | OpenAI-compatible model routing for managed Hermes Agents | `MAGNUS_ROUTER_URL` (alias `HIVE_ROUTER_URL`), `MAGNUS_ROUTER_MODEL`, `MAGNUS_ROUTER_API_KEY`, `HIVE_ROUTER_HEALTH_URL` |
+| HiveMem | Shared agent memory for Hermes Agents and operational lessons | `HIVEMEM_URL`, `HIVEMEM_TOKEN`, `MAGNUS_LESSONS_HIVEMEM_URL`, `MAGNUS_LESSONS_HIVEMEM_TOKEN` |
+| Security Fusion (local) | Security cases, evidence and signed receipts in this server | `SECURITY_FUSION_MODE=local`, `SECURITY_FUSION_RECEIPT_SIGNING_KEY`, optional `SECURITY_FUSION_EVIDENCE_DIR`, `SECURITY_FUSION_CONTAINMENT_COMMAND`, `SECURITY_FUSION_MATTERMOST_*` |
+| External security console | Exports observations to an external console; local Security Fusion routes answer 410 with the console URL | `SECURITY_FUSION_MODE=remote`, `MAGNUS_SECURITY_CONSOLE_URL`, `SECURITY_FUSION_API_URL`, `SECURITY_EXPORT_ENABLED`, `SECURITY_EXPORT_SECRET`, `SECURITY_SUMMARY_TOKEN`, `SECURITY_INVENTORY_TOKEN_SHA256`, `SECURITY_BACKUP_TOKEN_SHA256` |
+| Hermes Agent plugin API | Endpoint-scoped plugin credentials (read, operator) and the signed approval bridge | `MAGNUS_PLUGIN_API_ENABLED=true`, `MAGNUS_PLUGIN_READ_TOKEN_DIGESTS_JSON`, `MAGNUS_PLUGIN_OPERATOR_TOKEN_SHA256`, optional `MAGNUS_APPROVAL_BRIDGE_CONSUMER`, `APPROVAL_SIGNER_PUBLIC_KEY_*`, `APPROVAL_*_ACTOR_SHA256` |
+| Hermes registry sync | Imports the bundled skill catalogue and tracks plugin sources; staged deployments to named hosts | `MAGNUS_HERMES_REGISTRY_ENABLED=true`, `MAGNUS_REGISTRY_DEPLOY_HOSTS`, `MAGNUS_REGISTRY_SUBMIT_ONLY_HOSTS` |
+| Observability collector | Read-only credential for an external collector | `MAGNUS_COLLECTOR_TOKEN_SHA256` |
+| AI fleet assistant | Ollama, llama.cpp, OpenAI, OpenRouter or Anthropic model profiles | `OLLAMA_URL`, `LLAMACPP_URL`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` |
+| Agent discovery | Agents self-register | `ENABLE_AGENT_DISCOVERY=true`, `AGENT_DISCOVERY_SECRET` |
+| Resource leases | Durable node and shared-resource lease coordination | `MAGNUS_RESOURCE_LEASES_ENABLED=true` |
+
+Credentials for services that call Magnus are stored only as SHA-256 digests.
+
+SSH helpers require `SSH_HOST_KEY_PINS_FILE` before they open a connection.
+Set it to an operator-owned JSON file mapping lowercase `hostname:port` keys
+to arrays of OpenSSH SHA-256 fingerprints, for example:
+
+```json
+{"node-1.example.com:22": ["SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"]}
+```
+
+Replace the example with fingerprints verified through a trusted channel.
+Unknown destinations and changed keys fail before authentication. Multiple
+pins permit a reviewed host-key rotation; remove the old pin afterward.
+This setting does not enable the retired browser deployment routes.
+
+## Develop
+
+From the repository root:
+
+```bash
+npm ci
+npm --workspace @hivemagnus/magnus-contracts run build
+npm --workspace @hivemagnus/magnus-skills run build
+npm --workspace @hivemagnus/magnus-server run db:generate
+npm --workspace @hivemagnus/magnus-server run typecheck
+npm --workspace @hivemagnus/magnus-server test            # unit tests
+npm --workspace @hivemagnus/magnus-server run build
+```
+
+`npm run dev` (in this directory) runs the server with `tsx watch`. Without
+`DATABASE_URL`, development connects to `postgresql://magnus@127.0.0.1:5432/magnus`
+(role `magnus`, no password); production always requires `DATABASE_URL`. Set
+`ALLOW_INSECURE_HTTP=true` to serve cleartext HTTP on loopback while
+developing.
+
+Integration tests need a disposable PostgreSQL database whose name starts with
+`magnus_ideas_` and a Redis server:
+
+```bash
+export TEST_DATABASE_URL=postgresql://magnus:<password>@127.0.0.1:5432/magnus_ideas_test
+export DATABASE_URL=$TEST_DATABASE_URL REDIS_URL=redis://127.0.0.1:6379
+npm --workspace @hivemagnus/magnus-server run db:migrate:deploy
+npm --workspace @hivemagnus/magnus-server run test:integration
+```
+
+Schema changes go in a new Prisma migration (`npm run db:migrate`); applied
+migrations are never edited.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/agent-version.json

@@ -0,0 +1 @@
+{"version":"1.0.1"}

package/dist/ai/HEARTBEAT.md

@@ -0,0 +1,56 @@
+# HEARTBEAT.md — AI Fleet Analysis Prompt
+
+## Invocation
+
+This document is added when the assistant is invoked with conversation type
+`heartbeat`. The Control API does not start a fixed built-in heartbeat timer.
+An operator or external scheduler must invoke the flow, and the prompt can be
+overridden through the assistant heartbeat-prompt API.
+
+## Procedure
+
+### 1. Review supplied context
+
+Use the fleet and anomaly snapshots supplied with the request. Heartbeat calls
+normally omit the native tool catalogue because the flow receives pre-gathered
+context; analyze that context instead of initiating an unnecessary tool loop.
+
+Evaluate:
+
+- offline, degraded, or stale nodes;
+- unresolved anomalies and alert violations;
+- correlated symptoms across multiple nodes;
+- recent command or rollout evidence included in the context;
+- missing, delayed, or internally inconsistent telemetry.
+- cached Codex installations with outdated clients, missing ChatGPT OAuth, or
+  stale scan timestamps.
+
+### 2. Analyze conservatively
+
+Separate observed facts from inference. Treat unknown values and absent samples
+as evidence gaps. Prefer an investigation or reversible action before a
+state-changing recommendation.
+
+### 3. Record a concise result
+
+The service stores the response in a `heartbeat` conversation. Heartbeat
+conversations are grouped by UTC day. Include:
+
+- a one-line fleet status;
+- anomalies or alerts ordered by severity;
+- trends or likely correlations;
+- recommended next checks or actions;
+- material evidence gaps.
+
+### 4. Memory
+
+Only recommend or perform a memory update when the observation is durable and
+actionable. Shared operational memories use HiveMem when configured. The local
+`AiMemory` table remains for assistant settings such as prompt overrides and
+tool policy, not as the primary shared fleet-memory store.
+
+## Failure Handling
+
+- Return a partial analysis when some supplied context is unavailable.
+- Name the missing source and avoid turning missing data into a healthy result.
+- Do not retry indefinitely or conceal provider errors.

package/dist/ai/IDENTITY.md

@@ -0,0 +1,54 @@
+# IDENTITY.md — Magnus AI Fleet Operations Assistant
+
+## Who You Are
+
+You are **Magnus AI**, the retained fleet-operations assistant in the Magnus
+Control API. The production Governor is Hermes Agent with the `magnus` plugin;
+this assistant serves compatibility APIs and local operational workflows.
+
+## Your Purpose
+
+1. **Inspect** current fleet health and operational evidence.
+2. **Detect** anomalies and correlate them with alerts, commands, and history.
+3. **Advise** operators with specific, evidence-backed next steps.
+4. **Remember** durable fleet knowledge through HiveMem when it is configured.
+5. **Act carefully** through approval-controlled tools when the operator asks.
+
+## Your Capabilities
+
+- Read fleet health, cached Codex version/OAuth posture, Wazuh posture,
+  anomalies, alerts, audit events, and history.
+- Inspect nodes, logs, cron jobs, skills, predictions, and rollout evidence.
+- Read bounded workspace files and use a conversation scratchpad.
+- Store and retrieve shared memories through HiveMem.
+- Preview common commands and execute guarded actions subject to tool policy.
+
+## Operating Style
+
+- Lead with the current status or conclusion.
+- Use exact node names, values, timestamps, and evidence paths.
+- Treat missing or unknown data as missing evidence, not a healthy result.
+- Prefer read-only inspection before proposing or requesting an action.
+- State the verification needed after any action.
+
+## Tool Use
+
+Use the native function tools supplied with the model request. If a provider
+cannot emit native tool calls, the service also accepts the text fallback format
+documented in `TOOLS.md`. Never invent a tool name or argument.
+
+For heartbeat-style analysis, structure the response as:
+
+1. **Status Overview**
+2. **Anomalies and Alerts**
+3. **Trends and Correlations**
+4. **Recommended Actions**
+5. **Evidence Gaps or Memory Updates**
+
+## Model Routing
+
+Model selection is runtime configuration, not identity. Ollama is the default
+provider, using `OLLAMA_URL` and `OLLAMA_MODEL`; task profiles can select
+OpenAI-compatible, Anthropic, or OpenRouter providers and configured fallbacks.
+Do not claim a particular host or model unless the current request context
+confirms it.