NVIDIA / NVIDIA/NemoClaw

[Voice gateway] Set up and rotate one local VoiceClaw deployment identity

Open
#8,403 0 comments 0 reactions 0 assignees View on GitHub
area: integrations area: sandbox platform: brev
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Status in the R0 roadmap

This reusable local deployment-identity plan remains outside R0 and is not a prerequisite of [#11746](https://github.com/NVIDIA/NemoClaw/issues/11746).

The user-selected first experiment in #11749 uses one short-lived, operator-issued credential scoped to one agent. It is neither this reusable broker identity nor the full contract's offer/redemption/attachment-lease mechanism.

NemoClaw deployment/integration ownership remains in #11751. After disconnect, expiry or restart, the operator begins another experiment with a fresh credential. Reusable identity and unattended reconnect remain deferred.

The original specification below is retained as historical work. This issue remains open; no implementation or completion is claimed.

Original experimental identity specification

## Follows

- #8378

## Capability

Set up and maintain the deployment identity used by one local VoiceClaw runtime on a Brev instance.

After #8378, the one-turn demo works only after an operator manually creates matching credential files, chooses their ownership and permissions, and places both processes in a topology where the loopback gateway is reachable.

After this issue, the operator can ask NemoClaw to provision the identity, rotate it between sessions, recover it after a process restart, and remove it. Old or removed credentials fail before NemoClaw invokes OpenClaw.

This is an operator capability. It does not change the voice user's one-question, one-answer experience from #8378.

## Brev user journey

1. The operator creates a Brev instance from the pinned NemoClaw image.
2. The operator provisions one VoiceClaw deployment identity through NemoClaw.
3. The operator manually starts the feature-gated NemoClaw gateway and the pinned VoiceClaw runtime.
4. The user completes the #8378 repository-question demo.
5. The operator closes the session and rotates the deployment identity.
6. The old credential is rejected, while a new session using the delivered credential completes another turn.
7. The operator manually restarts both processes; another new session succeeds without recreating the identity by hand.
8. The operator removes the identity; admission fails and runtime-readable credential material is gone.

## Target Brev topology

This issue proves one topology rather than defining a general topology system:

- The NemoClaw gateway and operator commands run as the Brev `ubuntu` account.
- VoiceClaw's Talker and NemoClaw gateway driver run as a dedicated, non-login `voiceclaw` user.
- Both processes use the host network namespace and communicate over loopback.
- `voiceclaw` has neither sudo nor Docker-group membership.
- The credential handoff directory is outside `/home/ubuntu`, which Brev may replace during provisioning.
- NemoClaw owns and can atomically replace the credential.
- VoiceClaw can read the credential but cannot replace the file or its containing directory.
- VoiceClaw remains manually started.

Running both processes as `ubuntu` would allow the demo to prove rotation, but same-user file permissions would not isolate the OpenClaw credential from a compromised VoiceClaw process. That narrower topology is not the target of this issue.

## NemoClaw work

- Provide operator operations to provision, rotate, recover, and remove one deployment identity.
- Store and replace the credential atomically using owner-controlled, no-follow filesystem operations.
- Keep the deployment credential, expiring voice-session grant, and OpenClaw credential separate.
- Make a rotated, revoked, or removed credential fail admission before any OpenClaw invocation.
- Recover the current lifecycle state safely across manual gateway restart and partial rotation failure.
- Emit content-free diagnostics without credential values, fingerprints, conversation content, or OpenClaw frames.
- Keep the runtime, sandbox, agent, upstream, and credential path under trusted operator configuration.

## Required companion work

### VoiceClaw

The #8378 `NemoClawVoiceGatewayDriver` must receive only the fixed loopback endpoint and an absolute deployment-identity file path. For this issue it must:

- Open and validate the managed credential at each new session admission instead of caching it across sessions.
- Discard the deployment credential after it receives the expiring session grant.
- Fail closed when the file is missing, malformed, oversized, substituted, or has unexpected ownership or mode.
- Run manually as the unprivileged `voiceclaw` user with a separate writable state directory.
- Keep the credential out of `.env`, resolved configuration, process arguments, logs, API output, and package artifacts.
- Ensure teardown cannot delete NemoClaw-owned identity state.
- Remove the existing direct OpenClaw-token injection from this driver path.

If #8378 implements this late-read contract initially, this issue needs lifecycle and topology tests rather than a new VoiceClaw protocol.

### `brevdev/nemoclaw-image`

The pinned image, or an equivalent pinned host-provisioning artifact, must establish the secret-free topology:

- Create the `voiceclaw` system user and group without privileged memberships.
- Create a stable credential-delivery root outside `/home/ubuntu` that the operator controls and the runtime can read but not replace.
- Provide a separate runtime-writable state location when required.
- Record the topology revision in immutable image provenance.
- Test permissions, path substitution, absence of baked credentials, loopback-only gateway exposure, and denial of `voiceclaw` access to NemoClaw and OpenShell state.

The image must not create or contain the deployment credential. NemoClaw owns credential creation and lifecycle.

### Gabby scenario

Gabby owns the composed Brev qualification. The #8378 scenario scaffold is a prerequisite; this issue adds:

- A versioned Brev topology contract for the two operating-system principals, shared host network namespace, loopback route, credential boundary, and manual runtime start.
- A versioned managed-identity lifecycle contract.
- Immutable pins for NemoClaw, VoiceClaw, `nemoclaw-image`, the exact Brev image identity, the repository fixture, and both contracts.
- A qualification mode that exercises provision, rotation, restart recovery, and removal through the actual VoiceClaw driver and existing output callbacks.
- A content-free receipt containing revisions, contract versions, named assertions, and pass/fail results.

## Acceptance criteria

- [ ] NemoClaw provisions one deployment identity into the accepted Brev topology without exposing the OpenClaw credential.
- [ ] The unprivileged VoiceClaw process can read the delivered credential but cannot replace it, its parent directory, or NemoClaw-owned state.
- [ ] A manually started VoiceClaw runtime completes the #8378 fixture turn.
- [ ] Rotation occurs only after the active session is closed.
- [ ] A stale credential is rejected before OpenClaw invocation, and a new session using the delivered credential succeeds.
- [ ] Manual restart of VoiceClaw and the foreground gateway recovers the current identity and permits a new session.
- [ ] Removal deletes runtime-readable credential material and makes both stale and previously current credentials fail admission.
- [ ] Deterministic NemoClaw tests cover atomic replacement, no-follow behavior, revocation, restart, and partial-failure recovery.
- [ ] VoiceClaw tests cover late reads, file validation, between-session rotation, missing or substituted files, redaction, and non-destructive teardown.
- [ ] Image evidence proves the two-user topology, permissions, loopback-only exposure, absence of baked secrets, and immutable provenance.
- [ ] Gabby produces a pinned, content-free Brev qualification receipt for the complete lifecycle.

## Non-goals

- Installing, starting, supervising, or automatically restarting VoiceClaw.
- Resuming a voice session across rotation or process restart.
- Zero-downtime or active-session credential rotation.
- Multiple runtime deployments or identities.
- Human-user authentication.
- A generalized runtime-profile registry or topology matrix.
- Public ingress, TLS, TURN, or media configuration.
- Global `nemoclaw status`, health endpoints, or readiness supervision.
- VoiceClaw, ElevenLabs, or general voice product support.

## Category

Feature

Contributor guide

Open the contributing guide

Research direction

Start with the #8378 NemoClawVoiceGatewayDriver contract and the NemoClaw operator operations described here; no implementation files are named. Review the acceptance criteria across NemoClaw, VoiceClaw, brevdev/nemoclaw-image, and Gabby. Done requires lifecycle, topology, security, restart, and qualification evidence for provision, rotation, and removal.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
devops, infrastructure, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.