DocsBuildAPI ReferenceSDK Reference

Getting Started with OpsGraph on HUMΛN

Connect once, confirm what HUMΛN discovered, author Success Profiles, and ask whether work is actually healthy — not whether a server answered a ping.

What You're Looking At

OpsGraph is HUMΛN's product-first operations graph. Phase 1 is read-only topology and Process Contracts. Phase 1.5 adds Success Profiles and askable analytics. Phase 2 adds Process Contract evaluation, latent-failure detection, product-impact triage, and environment-aware alerts. Phase 3 adds the Access Broker: delegated typed remediation and short-lived SSH certificates — discovery still never silently grants remediation authority.

  • Topology — organization → product → environment → capability → runtime, plus typed workflow edges
  • Success Profiles — pack-authored fingerprints, collectors, and non-liveness objectives
  • Analytics — same contracts on Companion, MCP, and CLI
  • Monitoring — findings → cp_incidents correlation → impact + read-only triage
  • Access Broker — propose → HITL approve (scoped Delegation) → typed dispatch; HUMΛN OpenSSH CA for human access

Developer guides live under docs/guides/opsgraph/ (setup, monitoring, remediation, analytics, and more).

Prerequisites

  • HUMΛN org with Operations read access
  • @human/sdk or @human/cli (bundle namespace opsgraph from humanos.bundle.opsgraph.v1)
  • Delegation token with org context (human login)
  • For remediation / certificates: OpsNode enrolled with an AgentPassport, plus authority to approve HITL proposals

Step 1: Read topology

import { HumanClient } from '@human/sdk';

const client = new HumanClient({
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});

const { data: nodes } = await client.opsgraph.listTopology({ limit: 50 });
const { data: processes } = await client.opsgraph.listProcesses();

human opsgraph topology
human opsgraph processes
human opsgraph observations

Step 2: Confirm discoveries (never silent)

Fingerprint match proposes Success Profiles. Only human confirmation promotes them to canonical. Staging/dev must not silently become production.

See docs/guides/opsgraph/discovery-handshake.md.

Step 3: Ask analytics (Companion = MCP = CLI)

Companion prompts:

  • “Which hosts are least stable over the last 30 days?”
  • “Where are we overspending?”
  • “Which hosts need urgent security patches?”
  • “Spend Monitor status for ai.usage_cost.”

CLI recipes:

human opsgraph stability --grain host --window 30d
human opsgraph cost --view overspend
human opsgraph patch-posture --min-severity urgent
human opsgraph spend --signal-key ai.usage_cost

MCP tools: human.operations.analytics.stability · .cost · .patch_posture · .spend

Full table: docs/guides/opsgraph/analytics.md.

Step 4: Inspect monitoring (Phase 2)

human opsgraph findings
human opsgraph incidents
human opsgraph impact <incidentId>
human opsgraph triage <incidentId>

const findings = await client.opsgraph.listFindings();
const triage = await client.opsgraph.triageIncident(incidentId);

Canvas opens platform incidents_list / incident_detail (no duplicate OpsGraph incident renderer). Guide: docs/guides/opsgraph/monitoring.md.

Step 5: Delegated remediation (Phase 3 Access Broker)

Discovery never grants remediation authority. Inventory and monitoring remain read-only until a human proposes a typed action (for example host.service.restart) — never raw shell — then approves it. Approval mints a short-lived, scoped Delegation; only then may OpsNode dispatch through the constrained privileged helper.

human opsgraph remediation propose
human opsgraph remediation status <proposalId>
human opsgraph remediation approve <proposalId>
human opsgraph remediation deny <proposalId>
human opsgraph remediation dispatch <proposalId>
human opsgraph access certificate

const proposal = await client.opsgraph.proposeRemediation({
  action_id: 'host.service.restart',
  target: { class: 'host', id: hostId },
  parameters: { unit: 'nginx' },
  subject_did: subjectDid,
});
await client.opsgraph.approveRemediation(proposal.proposal_id);
await client.opsgraph.dispatchRemediation(proposal.proposal_id);
const cert = await client.opsgraph.issueAccessCertificate({ /* principal, host, pubkey, TTL */ });

MCP: human.operations.remediation.propose|get|approve|deny|dispatch · human.operations.access.certificate.issue

Recovery: a successful restart is not recovery — product-outcome verification must pass. Companion Canvas opsgraph_remediation_approval shows authority, target, risk, expiry, and recovery proof before HITL approve.

Human SSH access uses short-lived certificates from the HUMΛN-operated OpenSSH CA (no Teleport/Boundary). Guide: docs/guides/opsgraph/remediation.md.

Step 6: Author a pack (optional)

human opsgraph profile create my-edge --family edge --out ./packs
human opsgraph profile test ./packs/opsgraph-profile-my-edge

SDK: defineServiceProfile / defineProfilePack / harness in @human/opsgraph-profile-sdk — see docs/guides/opsgraph/profile-sdk.md.

Next

← All guides