[Enhancement]: Epic: serve harnesses' native interfaces through one adapter contract #547

Current scope (2026-11-06): This closed issue preserves the historical specification and research. #577 now scopes GTC DC P0 to OpenClaw and Hermes. Deep Agents Code adapter, cold resume, mounted skills and qualification are deferred until after GTC DC in #566; historical dcode P0 references below do not restore that delivery commitment. Shared Fabric lifecycle and transport requirements remain applicable. LangChain Deep Agents is unaffected.

Closed on 2026-11-02. GTC DC P0 work is tracked in #577, and deferred work, including #565 and #550 to #560, in #566. The P0 specification below still applies; #578 (cold resume) and #579 (OpenClaw's and Hermes's terminals) extend it.

Affected area: Harness adapter; Schemas or configuration; Consumer integration; Documentation or examples

How to read this issue. This description is the specification. It consolidates the decisions, clarifications and reviews that were posted as comments; those comments are hidden as outdated, and the change log records what changed. To change the specification, edit this description and add a change-log line. Sub-issues hold only their adapter's details.

Problem or opportunity

Consumers that run agents for people, such as NVIDIA NemoClaw, want to offer each harness's own interfaces: an API, a browser dashboard with chat, or a terminal UI. Fabric's adapters configure and supervise the harness, so they are the only place that can turn those interfaces on safely. Answered separately, each adapter would get a different shape for settings, credentials, ports and health, and each consumer would need adapter-specific code to reach them. This epic defines one contract and leaves each adapter's specifics to its sub-issue.

Not covered: the Deep Agents SDK adapter has no native interface (#546 covers Deep Agents Code); mini-swe-agent offers only an interactive terminal and a trajectory inspector; NOOA's nooa start-dev is a trace and evaluation viewer, not an agent console; and the remote-agent adapter's remote service owns its interfaces.

Status

The P0 specification below is confirmed by the epic's author, including #540's runtime-bound scope, and two specification reviews judged it implementable. An adversarial review then raised nine questions, which the epic's author settled on 2026-10-30; the requirements below include the answers, and Resolved questions records them. A Fabric maintainer can still object; until one does, implementers build against this text.

Reference implementation. NemoClaw's team builds the P0 adapters in cv/NeMo-Fabric to validate this specification and unblock NVIDIA/NemoClaw#14011. The Fabric team can review, cherry-pick or merge from it at its own pace. Gaps found while building it are settled by editing this description.

P0 specification

Applies to #541 (OpenClaw), #540 (Hermes) and #546 (Deep Agents Code). The IDs are for tests and reviews; a requirement marked with a question (Qn) was settled by that question's answer below.

Settings

• S1. harness.settings.interfaces is an object of named interfaces. Absent means off; present means on unless enabled: false; enabled defaults to true.
• S2. HTTP interfaces require port: an exact loopback port with no default, so the consumer always knows it. Before launching a child, start checks that nothing listens on its port; after the child passes health, start confirms that the child is still running and owns the listening socket. Otherwise start fails because the port is taken (Q5). The ownership check reads Linux procfs; on other platforms, only the check before launch applies. Adapters with derived ports state which ones they check and which they reserve (Q7).
• S3. Two interfaces of one runtime can't share a port. Equal ports fail start; planning doesn't catch them, because JSON Schema can't compare sibling values.
• S4. Terminal interfaces take no port.
• S5. public_origins, for browser interfaces that support it (OpenClaw's dashboard in P0; not Hermes's), is a list of origins (scheme://host[:port]) accepted in addition to http://127.0.0.1:<port> and http://localhost:<port>. OpenClaw accepts any loopback origin regardless of this list, with its token still required, so a consumer doesn't need to list a different local forward port; public_origins matters for non-loopback origins (Q6).
• S6. Adapters may add interface-specific fields.
• S7. Names in P0: OpenClaw dashboard; Hermes api and dashboard; Deep Agents Code terminal.
• S8. Each P0 descriptor lists exactly its supported names under settings_schema.properties.interfaces.properties, with additionalProperties: false there and on each interface object. Fabric's existing settings_schema validation then rejects unsupported names and fields during planning, and a consumer can check the image catalog's descriptor before deploying.
• S9. There is no optional field in P0; an enabled interface that can't start always fails start ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566).

Lifecycle

• L1. Interfaces live with a managed runtime, because consumers that drive agents through fabric-agent-ctl have no service operations. Services (prepare_service(), attach_service()) reject interfaces with a stable error before starting anything; service binding is [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.
• L2. An interface can't start when its child process exits, doesn't pass its health endpoint within the startup timeout, or fails S2's port check. start then fails, stops the children it already started, and leaves no token files or markers (Q1, Q5).
• L3. startup_timeout_seconds is one deadline for all of start: children start concurrently and must all pass health within it. Default 60, maximum 75, which leaves time for cleanup within core's 90-second limit on an adapter's start. Adapters without a startup timeout gain this setting; OpenClaw's existing one also became one deadline for all of start, with the same default and maximum (Q3).
• L4. An interface that is the agent's own server is covered by the runtime check. A separate interface process never fails the runtime check, and Fabric doesn't restart it.
• L5. stop first removes the runtime's token files and interface markers, then sends SIGTERM to each interface child's process group, waits up to 5 seconds, and sends SIGKILL to what remains; in-flight interface requests are cut off. Where the harness has its own shutdown drain, the adapter configures it below 5 seconds (Q4).
• L6. A consumer-chosen port stays fixed across restarts; the adapter fails rather than choosing another.
• L7. If core kills or loses the adapter host (a crash, or core's start or stop limit), nothing removes the runtime's token files and markers in P0, and processes the adapter didn't start as its children aren't tracked (A4). Each adapter's README documents this (Q2, Q8).

Paths

• P1. <artifact root> is the runtime's Fabric artifact root: RuntimeContext's artifact directory, or exactly <base>/artifacts when it's unset, regardless of where an adapter keeps its other files; /sandbox/artifacts in NemoClaw.
• P2. <adapter> is openclaw, hermes or deepagents-code.
• P3. Tokens are at <artifact root>/.fabric/<adapter>/runtimes/<runtime-id>/interfaces/<name>.token for interfaces that have one: OpenClaw's dashboard and Hermes's api. Hermes's dashboard and Deep Agents Code's terminal have none.
• P4. Deep Agents Code's terminal launcher is .../interfaces/terminal, with its marker .../interfaces/terminal.running. The launcher checks only the marker, so after L7 it can open a session against the old runtime's configuration until the sandbox is replaced (Q2).
• P5. These paths stay valid after [Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565, whose handle fields report the same locations.

Credentials and output

• T1. The adapter generates each token at every start and writes it owner-only (0600) only after every child passes health, as it does markers (Q1); a child that needs its token at launch receives it in its environment. Tokens never appear in handles, plans, results or logs.
• T2. Consumers keep tokens out of desired-state files, plans, deployment state, their own command output and logs, and test artifacts, and print the command that retrieves a token rather than the token. A person's explicit retrieval, for example openshell sandbox exec -n SANDBOX -- cat <path>, is the intended disclosure to that person.
• T3. The agent's own tools can read the token. In a NemoClaw sandbox, openshell sandbox exec runs as the harness's identity, so owner-only files are readable, though another process's environment is not. P0 documents this limitation; verifier credentials are [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.
• T4. Each adapter documents how a person signs in, for example OpenClaw's #token= URL. Generic discovery ([Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565) locates interfaces and credentials; applying a credential stays adapter-specific until [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566's scheme fields.

Access

• A1. Interfaces listen on loopback only. Exposing them is the consumer's job, for example with OpenShell's forward service.
• A2. Discovery is by convention: the consumer chooses the port, and finds the token at P3 using the runtime ID that fabric-agent-ctl start returns. Handle fields and a read-only status command come in [Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565 (fabric-agent-ctl: read-only status command for the owned runtime #420).
• A3. Terminal interfaces are reached with openshell sandbox exec -n SANDBOX --tty -- <launcher path>. openshell sandbox connect attaches to the sandbox's main process, which in NemoClaw is fabric-agent-ctl serve, not a shell; sandbox exec has no -t short form.
• A4. Hermes's dashboard has no sign-in in P0. Hermes's dashboard (v0.22.4 and v0.22.5) embeds its session token in the page it serves, and that token only gates direct API calls; a non-loopback dashboard.public_url switches on Hermes's provider-based auth gate, which refuses to start without a configured provider. So the dashboard is reached only through a gateway-authorized forward, which is its access control, with no dashboard token and no public_origins; its README says anyone who can reach its port, including the agent's own tools, can use it. Exposed service URLs for it wait for [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566. Hermes's API server keeps its Bearer token. The dashboard's gateway actions, such as restart and migrate, start detached Hermes processes that replace the Fabric-started gateway and can outlive stop; P0 documents this (Q8).

Configuration and behavior

• C1. The adapter generates the harness's configuration from FabricConfig at each start. Every harness process that calls a model, including interface children, uses FabricConfig's endpoint and the key from its api_key_env, set in that process's configuration only (Q9). Changes made through an interface aren't supported and don't survive a restart; each adapter documents this.
• C2. Conversations in an interface aren't promised to share threads with Fabric invocations; each adapter documents its behavior.
• C3. Update checks, automatic updates and telemetry that an interface's harness makes on its own stay off unless configured.
• C4. Each README documents what an environment needs for its interfaces (packages, built frontends, binaries) and the interface features that would let the agent bypass its guardrails, such as approvals, configuration edits or plugin installation; disabling them is [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.

Resolved questions

An adversarial review reproduced findings 1 to 8 against the pinned harnesses and Fabric core, and a TLA+ model of the lifecycle raised Q1. The epic's author settled all nine on 2026-10-30.

Follow-up: exact-origin enforcement is requested upstream in openclaw/openclaw#190113 (Q6).

Earlier questions, answered for P0: credentials are regenerated at each start (T1), retained ones wait for state_dir (#566); interfaces are runtime-bound (L1); terminal interfaces are launched by path (A3) until #565 reports a command in the handle; conversations aren't promised as shared (C2).

---
title: "P0 interface lifecycle, scratch model of NeMo-Fabric issue 547"
---
stateDiagram-v2
  state "Legend" as legend {
    lg0: live
    lg1: ended
    lg2: Breaks MarkerOnlyWhileRunning or NoChildOutlivesItsRuntime or TokenOnlyWhileServing
    lg3: Path to the MarkerOnlyWhileRunning or NoChildOutlivesItsRuntime or TokenOnlyWhileServing bug
  }
  class lg0 teal
  class lg1 tan
  class lg2 breaks
  class lg3 bugPath
  s0: Not started
  s1: Starting
  s2: Adapter killed (token file left)
  s3: Start failed (token file left)
  s4: Adapter killed (children left running, token file left)
  s5: Running
  s6: Adapter killed (children left running, token file left, marker left)
  s7: Stopped
  s8: Adapter killed (token file left, marker left)
  [*] --> s0
  s0 --> s1: start writes the token
  s1 --> s2: the adapter is killed
  s1 --> s3: a child exits or times out
  s1 --> s1: a child launches or passes health
  s1 --> s4: the adapter is killed
  s4 --> s2: a leftover child exits
  s1 --> s5: every child passes health
  s5 --> s6: the adapter is killed
  s5 --> s7: stop
  s6 --> s8: a leftover child exits
  s5 --> s8: the adapter is killed
  classDef breaks fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834
  classDef teal fill:#bfe3df,color:#000
  classDef tan fill:#e5d9ce,color:#000
  classDef bugPath stroke:#1680f3,stroke-width:2.5px
  class s0 teal
  class s0 bugPath
  class s1 teal
  class s1 bugPath
  class s2 tan
  class s2 breaks
  class s3 tan
  class s3 breaks
  class s3 bugPath
  class s4 tan
  class s4 breaks
  class s4 bugPath
  class s5 teal
  class s5 bugPath
  class s6 tan
  class s6 breaks
  class s6 bugPath
  class s7 tan
  class s8 tan
  class s8 breaks

Pinned versions

A4 and the Hermes findings were established on v0.22.4, while Fabric main tests v0.22.5, 261 commits later. A spot check of v0.22.5 found the same agent.cron_drain_timeout (default 30) and agent.restart_drain_timeout settings, the POST /api/gateway/restart route, the browser-chat flag and APIServerAdapter; #540's reference implementation confirmed A4 on v0.22.5, where the loopback dashboard still embeds its session token.

Target contract (after P0)

The full contract the P0 adapters start from. #565 delivers discovery and shared code; #566 tracks the rest. Where this list differs from the P0 specification, the P0 specification wins for P0.

1. Settings. Each interface is opt-in under harness.settings.interfaces.<name> (S1 to S9). Browser interfaces add public_origins, which the adapter maps to the harness's own setting, such as Hermes's dashboard.public_url, OpenClaw's allowedOrigins or OpenCode's --cors. An adapter rejects an interface it doesn't support, or one its lifecycle shape can't serve, during planning.
2. Discovery ([Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565). The descriptor declares the interfaces an adapter supports, with each one's kind (HTTP, terminal or stdio). The service or runtime handle reports each enabled interface's loopback port and path, and where its credential is, never the credential itself, so a consumer can forward any adapter's interfaces without adapter-specific code.
3. Network. Interfaces listen on loopback only, and exposing them is the consumer's job. Each interface declares its authentication scheme (Bearer, Basic, custom header, cookie or verifier) and which exposure paths it works through ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566).
4. Credentials. Two modes, declared per interface. Adapter-generated (P0: T1 to T3). Consumer-supplied verifier ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566): the consumer keeps the raw credential outside the agent's environment, and the harness, or a verifying proxy in the adapter, receives only its hash. Each adapter documents the interface features that would let an agent bypass its guardrails, and disables them in the adapter-generated mode ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566).
5. State ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566). state_dir keeps the harness's state and the credential across runtimes and services, under a stable consumer-chosen key, with one owner at a time and documented stale-lock recovery, resume or a documented lack of it, documented concurrent writes, the harness version that wrote it, and cleanup that never deletes it.
6. Configuration ownership. Generated from FabricConfig at each start (C1). A terminal command reported in a handle includes the adapter's configuration flags and environment. Fabric-owned settings (model and endpoint, keys, instructions, tools, MCP servers, skills, approval mode, telemetry, workspace) can't be changed through an interface; session choices stay within what FabricConfig declares; personal preferences are retained in state_dir. The handle or ready check reports a configuration digest and drift ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566).
7. Lifecycle. The descriptor declares whether each interface lives with a runtime or a service (P0: runtime, L1). Startup failure, fixed ports, failure and stop as L2 to L6; optional interfaces, service binding, terminal clients honoring a state lock and exiting when the runtime stops, and serializing interface turns with Fabric invocations or reporting them in activity are [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.
8. Health. P0 keeps separate interface processes out of the runtime check (L4). An interface check target with live, active and ready levels, declared in the descriptor, is [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.
9. Conversations. Each adapter documents whether interface conversations share threads with Fabric invocations (C2); a shared default is [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.
10. Outbound requests. As C3.
11. Packaging. As C4, and the descriptor lists the binaries it runs.

Implementation strategy

B, C and D run in parallel. GTC needs A to E.

Public contract and compatibility impact

• Rust API: none expected, unless handle discovery needs typed fields.
• Python API: none; consumers use the existing service and runtime calls.
• Schemas or adapter contract: descriptor fields for supported interfaces, handle fields for enabled ones, and each adapter's interfaces settings.
• Harness or consumer integrations: a consumer reads interface ports and credential locations from handles instead of adapter-specific knowledge.
• Backward compatibility: additive; every interface defaults to off.

Alternatives considered

• Each adapter on its own. It works, but consumers would integrate a different shape for each of the fourteen sub-issues, and later adapters would add more.
• A generic native-configuration passthrough. It lets consumers turn interfaces on themselves, but it widens the contract and lets their configuration conflict with Fabric-owned settings (see [Enhancement]: OpenClaw adapter: browser dashboard and chat #541).
• Consumer-side supervision. Consumers would duplicate configuration, credential, state and lifecycle handling outside Fabric and drift from it.

Acceptance criteria

• P0: [Enhancement]: OpenClaw adapter: browser dashboard and chat #541, [Enhancement]: Hermes adapter: API server, browser dashboard and chat #540 and [Enhancement]: Deep Agents Code adapter: new adapter with terminal UI #546 meet their acceptance criteria under the P0 specification, and Offer the P0 agents' native interfaces: OpenClaw's Control UI, Hermes's dashboard and API, and Deep Agents Code's terminal NemoClaw#14011 reaches each of their interfaces by convention.
• After P0 ([Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565): handles report interfaces, the shared settings fragment and Python common code exist, and a consumer test locates each P0 interface through the handle and stored credential, with per-adapter sign-in.
• Later ([Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566 and the negotiable sub-issues): each implements its interfaces on the same contract.

Additional context

NemoClaw's counterparts: NVIDIA/NemoClaw#13969 (Hermes), NVIDIA/NemoClaw#13360 (OpenClaw's dashboard) and NVIDIA/NemoClaw#13973 (signing in to it). NemoClaw forwards loopback services through OpenShell and doesn't patch adapter-owned configuration (NVIDIA/NemoClaw#13318).

Background research

The research behind the contract, moved here from comments. It records what was found and proposed at the time; where it differs from the P0 specification, the specification wins.

"interfaces": {
  "dashboard": { "kind": "http", "browser": true, "credential": "bearer", "lifecycles": ["service", "runtime"], "shares_conversations": false },
  "terminal":  { "kind": "terminal", "lifecycles": ["runtime"], "shares_conversations": true }
}

harness:
  settings:
    interfaces:
      dashboard: { enabled: true, port: 19119, allowed_origins: ["https://example.test"] }

"interfaces": {
  "dashboard": { "kind": "http", "address": "127.0.0.1", "port": 19119, "path": "/",
                 "credential_file": "/sandbox/artifacts/.fabric/hermes/runtimes/RUNTIME_ID/interfaces/dashboard.token" },
  "terminal":  { "kind": "terminal", "argv": ["kilo", "attach", "http://127.0.0.1:4096"],
                 "credential_env_files": { "KILO_SERVER_PASSWORD": "/sandbox/artifacts/.fabric/kilo/runtimes/RUNTIME_ID/interfaces/terminal.token" } }
}

Change log

• 2026-10-29: epic opened; implementation notes, discovery, network and credentials, state, and lifecycle research posted as comments (now under Background research).
• 2026-10-30: P0 decisions narrowed the scope: runtime-bound interfaces, adapter-generated tokens at each start, discovery by convention; [Enhancement]: Interfaces: generalize discovery and shared adapter code from the P0 adapters #565 and [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566 split out; [Enhancement]: Hermes adapter: API server, browser dashboard and chat #540 made runtime-bound.
• 2026-10-30: two specification reviews added the single settings rule (S1 to S9), the artifact root, startup failure and timeout (L2, L3), token cleanup on stop (L5), sandbox exec --tty for terminals (A3), and Hermes's dashboard without sign-in (A4); optional removed from P0.
• 2026-10-30: an adversarial review and a lifecycle model raised Q1 to Q9.
• 2026-10-30: decisions, clarifications and research consolidated into this description and the sub-issues' descriptions; the comments they replace are hidden as outdated.
• 2026-10-30: the epic's author settled Q1 to Q9; S2, S5, L2, L3, L5, P4, T1, A4 and C1 changed, and L7 was added.
• 2026-10-30: building [Enhancement]: OpenClaw adapter: browser dashboard and chat #541's reference implementation settled two gaps: S2's ownership check is Linux-only, and L3's maximum applies to existing startup timeouts such as OpenClaw's (default 30).
• 2026-10-30: building [Enhancement]: Hermes adapter: API server, browser dashboard and chat #540's reference implementation settled how Q9 works, confirmed A4 on Hermes v0.22.5, and recorded Hermes's packaging needs; [Enhancement]: Hermes adapter: API server, browser dashboard and chat #540 lists them.
• 2026-10-30: [Enhancement]: Deep Agents Code adapter: new adapter with terminal UI #546's investigation found that dcode can't attach to another process's agent; the epic's author chose one dcode --acp process per runtime, with the terminal UI as a separate session on the shared store. [Enhancement]: Deep Agents Code adapter: new adapter with terminal UI #546 records the outcome.
• 2026-10-31: NemoClaw's live Kubernetes tests showed OpenClaw's Gateway taking about 40 s to start when three agents start at once on four vCPUs, against the adapter's 30 s per-step timeout. OpenClaw's startup_timeout_seconds is now one deadline for all of start, defaulting to 60, as L3 says (reference implementation a7c5d024). [Bug]: Deep Agents Code's terminal UI can't resume the runtime's thread #567 recorded that Deep Agents Code's terminal can list but not open the runtime's thread; [Enhancement]: Deep Agents Code adapter: new adapter with terminal UI #546 and the docs now say so.
• 2026-11-02: closed; the GTC DC scope moved to [Enhancement]: Epic: GTC DC P0 for NemoClaw: OpenClaw and Hermes as stock harnesses #577, and the deferred sub-issues to [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566.

Duplicate check

• I searched the existing issues and did not find a duplicate.