Register an External Component During Onboarding

NemoClaw can register one external host component during fresh sandbox onboarding. The experimental version 1 contract lets the component intercept selected OpenShell operations and activate resources for one verified sandbox.

Check the Version 1 Limits

Use this contract only when all these conditions apply:

• The host runs a supported Linux installation with the Docker driver.
• NemoClaw is the OpenShell gateway lifecycle authority.
• Onboarding creates a new sandbox with an explicit name.
• The external component service and both Unix sockets are running before onboarding starts.

NemoClaw does not start, stop, supervise, or recover the external component. The component owner must operate its service, sockets, credentials, resources, and diagnostics.

Version 1 does not support these operations or configurations:

• Resume, reuse, repair, rebuild, recreation, or migration.
• Providerless component onboarding with NemoClaw-supplied initial policy.
• An externally supervised OpenShell gateway.
• More than one registered component.
• Generic shell commands, repository commands, vendor adapters, or a new OpenShell provider attachment API.

Onboarding without the declaration uses the existing onboarding behavior. Registration alone does not select providerless onboarding. Ordinary onboarding with a registered component keeps NemoClaw’s initial policy and provider setup.

Create the Declaration

Create ~/.config/nemoclaw/external-component.json before you start onboarding. Version 1 does not support another declaration path. The file must contain only these four fields:

1
{
2
  "schemaVersion": 1,
3
  "componentId": "policy-governance",
4
  "interceptorSocketPath": "/run/user/1000/policy-governance/interceptor.sock",
5
  "activationSocketPath": "/run/user/1000/policy-governance/activation.sock"
6
}

The fields have these requirements:

Apply mode 0600 to the declaration:

$
chmod 0600 ~/.config/nemoclaw/external-component.json

NemoClaw applies these filesystem requirements before gateway effects:

• The declaration must be a regular file with exactly one hard link that the current effective user owns.
• The declaration must contain at most 16 KiB of valid UTF-8 and strict JSON.
• The home directory and each declaration parent must belong to the current user.
• Declaration parents must not permit group or other users to write.
• Each endpoint must be a Unix socket that the current user owns.
• Each socket must permit owner read and write access and no group or other access.
• Socket parents must belong to the current user or root and must not permit group or other users to write.
• Neither the declaration, its parents, the sockets, nor their parents can be symbolic links.

NemoClaw rejects duplicate keys, missing or unknown fields, unsupported schema versions, and ambiguous filesystem state. It also rejects relative, non-normalized, empty, identical, or overlong socket paths.

The current effective Linux user is the version 1 trust principal. Version 1 does not isolate the component from another malicious process running as that user. NemoClaw transfers no authentication secret through either socket.

NemoClaw records each validated path’s device, inode, owner, type, and mode. It rechecks that identity before gateway configuration and before activation.

Review the Generated Interceptor

NemoClaw remains the only writer of its generated OpenShell gateway configuration. Do not edit the generated OpenShell files.

NemoClaw renders one interceptor with these fixed settings:

The declaration cannot change limits, failure behavior, gateway ownership, or other OpenShell settings. Version 1 does not permit post_commit, network endpoints, TLS fields, provider profiles, credentials, or arbitrary TOML.

Start Fresh Onboarding

Choose a name that has no sandbox registry entry and no live sandbox on the selected gateway. Start fresh onboarding with that explicit name:

$
nemohermes onboard --fresh --name component-sandbox

For non-interactive onboarding, NEMOCLAW_SANDBOX_NAME can supply the explicit name. NemoClaw verifies the name before it changes the gateway configuration or lifecycle.

After sandbox creation, NemoClaw verifies the durable OpenShell sandbox ID and effective sandbox policy. The policy must contain the NemoClaw policy requirements and have a valid hash and active version. The policy version must match the live sandbox observation.

NemoClaw sends identity to the component only after these checks pass.

Implement the Activation Endpoint

NemoClaw sends one HTTP/1.1 request over activationSocketPath. The request uses this start line and these headers:

1
POST /v1/activate HTTP/1.1
2
Host: localhost
3
Content-Type: application/json
4
Accept: application/json
5
Content-Length: <body-byte-count>
6
Connection: close

The request body uses strict JSON with this shape:

1
{
2
  "schemaVersion": 1,
3
  "activationId": "<random-version-4-UUID>",
4
  "componentId": "policy-governance",
5
  "gateway": {
6
    "name": "<selected-NemoClaw-gateway-name>"
7
  },
8
  "sandbox": {
9
    "id": "<durable-OpenShell-sandbox-ID>",
10
    "identityFingerprint": "sha256:<digest>",
11
    "lifecycleGeneration": "<generation>"
12
  },
13
  "policy": {
14
    "source": "sandbox",
15
    "hash": "sha256:<digest>",
16
    "activeVersion": 1
17
  }
18
}

For gateway port 8080, gateway.name is nemoclaw. For a non-default port, the name is nemoclaw-<port>. Use the value in the request as the selected gateway identity.

The component must return one HTTP/1.1 status 200 response. The response must include one valid Content-Length header and must not use Transfer-Encoding. The connection must end after the declared body.

Return a strict JSON body with only these fields:

1
{
2
  "schemaVersion": 1,
3
  "activationId": "<matching-version-4-UUID>",
4
  "componentId": "policy-governance",
5
  "sandboxId": "<matching-durable-OpenShell-sandbox-ID>",
6
  "policyHash": "sha256:<matching-digest>",
7
  "result": "activated"
8
}

Set result to activated or rejected. Do not add a message or another field. The response body cannot exceed 1,048,576 bytes.

The activationId, componentId, sandboxId, and policyHash must match the request. NemoClaw rejects duplicate keys, unknown fields, invalid values, extra response bytes, oversized bodies, and evidence mismatches.

The activation deadline is 30 seconds. Version 1 has no command, environment variable, or declaration setting for either timeout. NemoClaw does not retry activation automatically.

After an activated response, NemoClaw rechecks the declaration, sockets, sandbox identity, lifecycle generation, and policy evidence. Onboarding reports success only when the repeated evidence equals the pre-request evidence.

Handle an Incomplete Activation

NemoClaw classifies the activation result as follows:

For failed or ambiguous, onboarding does not report success. The selected state root keeps onboard-session.json with these secret-free activation fields:

• schemaVersion.
• activationId.
• componentId.
• lifecycleGeneration.
• sandboxIdentityFingerprint.
• resultClass.

Version 1 has no supported recovery operation for this state. Preserve the onboarding session, sandbox registry, sandbox, and component diagnostics for an identity-verified recovery decision. Do not delete or recover the sandbox from its mutable name alone. NemoClaw does not store a policy copy or durable policy authority in the incomplete state.

Keep Credentials Outside the Contract

Do not put component credentials in the declaration, activation request, activation response, command arguments, environment variables, events, logs, or artifacts. Keep component credentials in component-owned protected storage. NemoClaw does not read, persist, log, transfer, or remove those credentials.

NemoClaw diagnostics report bounded reason classes. They do not include request bodies, response bodies, socket paths, or component-provided text.

Related Topics

• Declare the OpenShell Gateway Lifecycle Authority for NemoClaw-managed and externally supervised gateway modes.
• Host Files and State before you change an onboarding session or sandbox registry file.
• NemoClaw CLI Commands Reference for onboarding flags and environment variables.