[Voice gateway] Set up and rotate one local VoiceClaw deployment identity
- 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
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