Export explicit external gateway ownership for an existing sandbox
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 43m
- Merged PRs (30d)
- 718
Description
Parent: #10904. Implementation target: **main**.
## Problem and outcome
Main's gateway schema has only `management: nemoclaw`. [Gateway observation](https://github.com/NVIDIA/NemoClaw/blob/f5c05a0e6a59bd5133c50e31becbff25af274c33/src/lib/adapters/config/live-export-source.ts) classifies an unowned state root as unknown, and [verification](https://github.com/NVIDIA/NemoClaw/blob/f5c05a0e6a59bd5133c50e31becbff25af274c33/src/lib/domain/config/verify-export-source.ts) refuses it. A verified externally supervised gateway must be representable without claiming NemoClaw owns its lifecycle.
Source baseline: `f5c05a0e6a59bd5133c50e31becbff25af274c33`.
This differs from #11453: that issue preserves a registered policy component required by a gateway. This issue represents ownership of the gateway process/service itself.
## Before / after
### Before
A ready OpenClaw sandbox named `external-gw-demo` uses supported hosted inference and a local OpenShell gateway whose process/service is supervised outside NemoClaw.
```bash
nemoclaw config export external-gw-demo --output external-gw-demo.yaml
```
Main cannot represent external gateway ownership: its schema accepts only `management: nemoclaw`, its reader reports an unowned state root as unknown, and its verifier refuses the source. The gateway check reports `Gateway lifecycle or state-root ownership is not NemoClaw-managed.` Export exits nonzero without publishing YAML. These are source-level findings at the revision above.
### After
When explicit lifecycle/connection provenance and current gateway/sandbox identity agree, the same command exits zero and writes a complete configuration containing an external gateway connection.
For an illustrative local test gateway using mutual TLS, the gateway fragment is:
```yaml
spec:
gateway:
management: external
endpoint: https://127.0.0.1:17681
tls:
ca:
env: GATEWAY_CA_FILE
certificate:
env: GATEWAY_CLIENT_CERT_FILE
key:
env: GATEWAY_CLIENT_KEY_FILE
```
The endpoint must come from verified connection evidence. Each environment-variable name must come from an established credential/file-source reference; the example names must not be synthesized for a source that lacks them. The full document still includes the sandbox's immutable image, agent, hosted inference route and effective policy. This branch describes connection requirements and grants NemoClaw no authority to create, stop, replace or delete the gateway. It contains no managed gateway image, engine, storage or state-directory settings.
An ordinary managed gateway continues to export its existing `management: nemoclaw`, name and port shape. A source whose ownership is merely unknown still refuses; absence of a marker does not become proof of external management. Missing credential-reference provenance, mismatched endpoints and changed gateway/sandbox identities also refuse without publication.
The acceptance test verifies successful export against an explicitly external fixture and confirms the supervisor, gateway process, configuration and sandbox identity remain unchanged. This issue does not adopt the gateway or add config-driven apply.
## Scope
One existing supported native-Linux OpenClaw deployment with hosted inference, an immutable managed sandbox image and an explicitly externally supervised local gateway. Reuse current gateway connection and lifecycle authorities. Add an external schema branch with a verified endpoint and portable credential/TLS source references when required. Keep the existing managed shape valid.
## Acceptance
- Export the selected gateway as external only when explicit lifecycle/connection evidence and current sandbox/gateway binding agree.
- Do not interpret absence of an ownership marker, directory location or process reachability alone as external ownership. Legacy unknown state continues to refuse with a useful diagnostic.
- Export only connection intent and secret references; do not copy private keys, credentials, machine-specific state directories or managed lifecycle fields.
- Reject mismatched endpoints, replaced gateway/sandbox identities, missing credential-reference provenance and unstable reads without modifying the gateway.
- Prove an existing externally supervised gateway survives export unchanged and ordinary managed exports remain unchanged.
If existing lifecycle state lacks an explicit fact needed for this case, add only the minimal non-secret provenance through its current owner, with backward-compatible absence semantics and a focused persistence test. Do not create a second gateway registry or infer ownership. New remote topologies, gateway adoption/start/stop, external-component activation and config-driven apply remain separate work.
## Delivery boundary
Extend the existing observation → verification → document builder → schema → publication pipeline. Export remains read-only and emits credential references only. Preserve successful existing exports and refusals for unrelated unsupported state. Regenerate the checked-in schema when its source changes.
Use a failing behavioral test before implementation, focused schema/action tests, and an existing installed-CLI scenario for the real boundary. Reuse coverage work in #11485; branch-to-branch translation and deployment parity remain with #11810. This issue does not add config-driven apply, resource adoption, or change existing onboarding inputs.
Contributor guide
Research direction
Start with src/lib/adapters/config/live-export-source.ts and src/lib/domain/config/verify-export-source.ts, then trace the existing config export command through its observation, document-builder, schema, and publication stages. Add a failing behavioral test first, followed by focused schema/action tests and an installed-CLI scenario; done means external fixtures export with verified references, managed exports and refusals remain unchanged, and the gateway is not modified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100