Use the Headless Lifecycle Package

Use nemoclaw/lifecycle when a service needs deterministic Hermes planning and read-only observation without invoking the NemoClaw command-line interface (CLI). The first API version supports Hermes 0.19.0 with OpenShell 0.0.106.

Understand the Boundary

Your service supplies an OpenShellHermesAgentObserver implementation that owns its OpenShell authentication and transport. The observer is a trusted boundary that must independently authenticate the requested target and inspect the live OpenShell resource, image, Hermes version, configuration fingerprint, sandbox phase, and Hermes health endpoint. It must not return request values without verifying them against live evidence. NemoClaw validates the request, calls that capability once, derives readiness, verifies the observed identities, and returns a redacted result.

The public package does not read an ambient OpenShell profile, start a local Gateway, open a terminal, run a subprocess, or persist lifecycle state. It does not expose OpenShell software development kit (SDK), gRPC, protobuf, or CLI types.

Plan and Observe Hermes

Provide SHA-256 identities for the target Gateway, OpenShell resource, sandbox image, and Hermes configuration. Keep credentials and private endpoint values inside your injected capability.

1
import {
2
  HERMES_LIFECYCLE_DEFINITION,
3
  NEMOCLAW_LIFECYCLE_API_VERSION,
4
  observeHermesLifecycle,
5
  planHermesLifecycle,
6
  type HermesLifecyclePlanRequest,
7
  type LifecycleDigest,
8
  type OpenShellHermesAgentObserver,
9
} from "nemoclaw/lifecycle";
10
11
declare const observer: OpenShellHermesAgentObserver;
12
13
const digest = (value: string) => value as LifecycleDigest;
14
const request: HermesLifecyclePlanRequest = {
15
  apiVersion: NEMOCLAW_LIFECYCLE_API_VERSION,
16
  target: {
17
    gatewayIdentity: digest(process.env.GATEWAY_IDENTITY!),
18
    workspace: "hermes-workspace",
19
    openshellVersion: HERMES_LIFECYCLE_DEFINITION.openshellVersion,
20
  },
21
  sandbox: {
22
    name: "hermes-agent",
23
    resourceIdentity: digest(process.env.RESOURCE_IDENTITY!),
24
    imageDigest: digest(process.env.IMAGE_DIGEST!),
25
    configurationFingerprint: digest(process.env.CONFIGURATION_FINGERPRINT!),
26
  },
27
};
28
29
const plan = planHermesLifecycle(request);
30
if (!plan.ok) throw new Error(plan.error.message);
31
32
const observation = await observeHermesLifecycle({ plan: request, timeoutMs: 5_000 }, observer);
33
if (!observation.ok) throw new Error(observation.error.message);

The plan rejects unknown fields, unsupported versions, invalid names, and malformed digests. The observation fails closed when the target, resource, image, agent, or configuration identity differs from the plan. NemoClaw derives sandbox readiness from the closed OpenShell phase set and derives Hermes readiness from the health status code. The combined readiness is ready only when the sandbox phase is Ready or Running and the Hermes health endpoint returns status 200. When the capability reports that the resource is missing, the result has state: "missing" and readiness: "not_ready".

Respect the First API Limits

This API does not define an image reference, entrypoint, provider, network policy, checkpoint, ownership record, or mutation authority. It does not create, stop, start, replace, delete, or clean up a sandbox. OpenShell 0.0.115 requires separate compatibility evidence before a later API definition can support it.