Skip to content

feat(gateway-interceptors): intercept sandbox start, stop, suspend, and resume - #5173

Merged
TaylorMutch merged 2 commits into
ai-openshell:mainfrom
ericcurtin:fix/5100-intercept-start-stop/ericcurtin
Nov 10, 2026
Merged

TaylorMutch merged 2 commits into
ai-openshell:mainfrom
ericcurtin:fix/5100-intercept-start-stop/ericcurtin

Conversation

@ericcurtin

@ericcurtin ericcurtin commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Allow gateway interceptors to target StartSandbox, StopSandbox, SuspendSandbox, and ResumeSandbox. Operators can validate public sandbox activation requests and observe successful stop and suspend requests through the existing interceptor framework.

Related Issue

Closes #5100

Changes

  • Add all four lifecycle methods to INTERCEPTABLE_METHODS and assert their route eligibility.
  • Document lifecycle RPC bindings for activation validation and stop/suspend observation.
  • Preserve existing handler and replay behavior. Suspend/Resume do not gain request-ID replay support.

Release Notes

After a gateway upgrade and restart, dynamic interceptor registrations advertising these RPCs can begin intercepting them. Strict allowlist/exact registrations require matching operator configuration. Gateway-internal lifecycle actions remain outside public RPC interception.

Testing

  • Checks appropriate to the affected code and behavior pass
  • Unit tests added/updated (if applicable)
  • E2E tests added/updated (if applicable)

All 60 openshell-gateway-interceptors library tests passed. Rust formatting and git diff --check passed. mise run docs passed with zero errors and three Fern warnings. No lifecycle-specific integration tests were added.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

Signed-off-by: Eric Curtin <eric.curtin@docker.com>
@copy-pr-bot

copy-pr-bot Bot commented Nov 2, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@ericcurtin

Copy link
Copy Markdown
Contributor Author

@TaylorMutch @shailendra-nv PTAL when you get a chance, and /ok to test 6c58acafe4cd5d1ad28015aa4d08c3ebefb7f73c if it looks good. Thank you!

@ericcurtin

Copy link
Copy Markdown
Contributor Author

@sjenning @grs PTAL when you get a chance, and /ok to test 6c58acafe4cd5d1ad28015aa4d08c3ebefb7f73c if it looks good. Thank you!

@TaylorMutch

Copy link
Copy Markdown
Contributor

/ok to test 6c58aca

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
@TaylorMutch TaylorMutch changed the title feat(gateway-interceptors): intercept StartSandbox and StopSandbox feat(gateway-interceptors): intercept sandbox start, stop, suspend, and resume Nov 10, 2026
@TaylorMutch

Copy link
Copy Markdown
Contributor

/ok to test 62a5a6e

@TaylorMutch

Copy link
Copy Markdown
Contributor

Added SuspendSandbox and ResumeSandbox in the separate follow-up commit 62a5a6e57e44ae6368f43ab2451f3c25906f18df, addressing the issue author's request to include them.

ResumeSandbox brings a workload back into execution, so leaving it outside interception would preserve an admission-control gap even after making StartSandbox interceptable. Including SuspendSandbox also lets interceptors validate that transition or observe successful suspend requests through post_commit.

Both are existing unary lifecycle mutations supported by the shared interceptor middleware, so the addition only extends the route allowlist and its assertions, with accompanying documentation. It does not change their handlers or add request-ID replay support. All 60 gateway-interceptor unit tests passed, along with formatting and documentation validation.

@TaylorMutch TaylorMutch left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The lifecycle allowlist additions address #5100 and the issue author's Suspend/Resume follow-up using the existing interceptor middleware. Handler and replay semantics are preserved, and the documentation explains lifecycle bindings. All checks on this commit have completed successfully, with non-applicable jobs skipped. Local validation also passed all 60 gateway-interceptor unit tests, formatting, and docs checks.

@TaylorMutch
TaylorMutch added this pull request to the merge queue Nov 10, 2026
Merged via the queue into ai-openshell:main with commit f62fa13 Nov 10, 2026
85 checks passed
cv added a commit to NVIDIA/NemoClaw that referenced this pull request Nov 16, 2026
Moves NemoClaw's OpenShell pins from v0.1.7 to v0.1.8: the native CLI,
the gateway, supervisor and sandbox images, the gateway chart, the
OpenShell crates, and the vendored SDK. Deployments built from this
revision run OpenShell v0.1.8, which no longer waits out a Kubernetes
sandbox pod's termination grace period on delete and renews
client-credentials tokens in the CLI.

## Problem

NemoClaw pins OpenShell v0.1.7 (`5d25211`). v0.1.8 (`f3d9765`, 80
commits later) is the latest release. Among its fixes:

- deleting a sandbox on Kubernetes no longer waits out the pod's
30-second termination grace period (ai-openshell/OpenShell#5279), which every
Kubernetes destroy and sandbox replacement paid (ai-openshell/OpenShell#5025);
- the CLI renews an expired client-credentials token by repeating the
grant (ai-openshell/OpenShell#4389, closing ai-openshell/OpenShell#4287), a limit
our Kubernetes guide and GPU autoscaling example documented;
- deleted sandboxes no longer leave memory behind on the gateway
(ai-openshell/OpenShell#5428).

## Change

- **Pins:** the Cargo revision of `openshell-core`, `openshell-sdk` and
`openshell-policy`, and of the vendored SDK's `openshell-core` and
`openshell-crypto`; in `versions.json`, the version, revision, Linux CLI
archives, gateway, supervisor and sandbox images, and gateway chart; the
managed-gateway reference, a contract test and the gateway contract
module, which carry the gateway digest. The CLI checksums come from the
release's `openshell-checksums-sha256.txt` and match the downloaded
archives; the image and chart digests come from GHCR's `0.1.8` tags, and
GHCR's `0.1.7` tags match the previous pins.
- **Vendored SDK:** upstream changed only `src/client.rs` (a new
`auth_interceptor()` accessor), copied unchanged. The SDK manifest still
enables core telemetry, so the manifest patch stays; `NOTICE.md` records
the refresh. `Cargo.lock` changes only the five OpenShell crates'
revision.
- **SDK integration limits:** the table in
`internal-docs/design/architecture.md` still holds at v0.1.8 and now
cites that revision.
- **`websocket_credential_rewrite`:** OpenShell now rejects it on a
`rest` endpoint (ai-openshell/OpenShell#5336), through the `openshell-policy`
validation NemoClaw already runs on explicit policies. The field's
description says it needs `protocol: websocket`; the JSON Schema,
configuration reference and provider schema snapshot are regenerated.
- **Live / Kind budgets:** with v0.1.8 the two kind cases take about
35-40 s less each: 98-108 s and 62-70 s on this pull request's runs,
against 138-143 s and 94-100 s on recent `v1` runs. The per-test budget
and the `live-kind` slow-timeout drop from 180 s to 140 s, and the
step's wall budget from 300 s to 240 s.
- **Limits removed:** the Kubernetes guide and the GPU autoscaling
example no longer tell readers to sign in again when a
client-credentials token expires; they say to keep
`OPENSHELL_OIDC_CLIENT_SECRET` set.
- **Release notes** list the new pin, the fixes above, and the policy
changes that can stop an existing explicit policy:
`websocket_credential_rewrite` on `rest`, filesystem paths through a
symlink in a writable workspace (ai-openshell/OpenShell#5278), and IPv4-mapped
IPv6 endpoint hosts (ai-openshell/OpenShell#5101).

Resolves #13959.

## Upgrade notes checked

- **Static credential placement** (ai-openshell/OpenShell#4886): every profile
NemoClaw registers (inference, `api` integrations, Brave and Tavily
search) already declares `auth_style` and `header_name`, including
Anthropic's `x-api-key` and Brave's `X-Subscription-Token`, so their
credentials keep resolving.
- **OCSF attribution** (ai-openshell/OpenShell#5048): NemoClaw reads no OCSF
records.
- **SDK moves:** the Python and Go SDK changes don't apply; NemoClaw
uses the Rust SDK.
- **Gateway interceptors** (ai-openshell/OpenShell#5173): NemoClaw registers
none.
- **Chart:** v0.1.8 adds optional `metrics.tls`, `priorityClassName` and
`topologySpreadConstraints`; NemoClaw sets none of them.
ai-openshell/OpenShell#5478, which would replace the `metricsPort: 0` setting,
isn't in v0.1.8, so that setting stays.
- **User guide:** apart from the lines above, `docs/` still describes
NemoClaw `637bdb6` and its OpenShell 0.1.7 links; moving them belongs to
the next guide refresh.

---------

Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(gateway-interceptors): make StopSandbox and StartSandbox interceptable

2 participants