Skip to content

docs: document OPENSHELL_SSH_HANDSHAKE_SECRET in Getting Started#1287

Merged
maxamillion merged 1 commit intoNVIDIA:mainfrom
russellb:docs/ssh-handshake-secret-dev-setup
May 9, 2026
Merged

docs: document OPENSHELL_SSH_HANDSHAKE_SECRET in Getting Started#1287
maxamillion merged 1 commit intoNVIDIA:mainfrom
russellb:docs/ssh-handshake-secret-dev-setup

Conversation

@russellb
Copy link
Copy Markdown
Contributor

@russellb russellb commented May 9, 2026

Summary

Add OPENSHELL_SSH_HANDSHAKE_SECRET to the Getting Started section in CONTRIBUTING.md. The Podman and Kubernetes compute drivers require this variable, but it was never documented in the dev setup instructions. Developers using Podman (the default when it's installed) hit an opaque configuration error on first run.

Related Issue

Introduced by 2e0afea ("feat(vm): derive guest rootfs from sandbox images (#957)"), which added the requirement but exempted only Docker and VM drivers.

Changes

  • Added an export OPENSHELL_SSH_HANDSHAKE_SECRET=dev-secret step to the Getting Started code block in CONTRIBUTING.md
  • Included a comment explaining which drivers require the variable

Testing

  • mise run pre-commit passes (pre-existing python:proto failure on main, unrelated)
  • Unit tests added/updated (N/A — docs only)
  • E2E tests added/updated (N/A — docs only)

Checklist

The Podman and Kubernetes compute drivers require
OPENSHELL_SSH_HANDSHAKE_SECRET to be set. This was introduced in
2e0afea ("feat(vm): derive guest rootfs from sandbox images (NVIDIA#957)"),
which exempted only the Docker and VM drivers from the check.

The Getting Started instructions in CONTRIBUTING.md didn't mention
the variable, so developers using Podman (the default on systems
where it is installed) hit an opaque configuration error on first run.

Add the export as a separate setup step with a comment explaining
which drivers require it.

Signed-off-by: Russell Bryant <russell.bryant@gmail.com>
@copy-pr-bot
Copy link
Copy Markdown

copy-pr-bot Bot commented May 9, 2026

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.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 9, 2026

All contributors have signed the DCO ✍️ ✅
Posted by the DCO Assistant Lite bot.

@russellb
Copy link
Copy Markdown
Contributor Author

russellb commented May 9, 2026

I have read the DCO document and I hereby sign the DCO.

@TaylorMutch
Copy link
Copy Markdown
Collaborator

Hey @russellb - I was actually looking at removing the handshake altogether; we already have some auth guarantees with mTLS from the supervisor to gateways and we don't use it from the client to the gateways (I have a draft PR in flight for this, see #1274). It was originally needed when gateways initiated traffic to the supervisors, but as of 0.0.37 the traffic is switched (supervisors connect to the gateways) and we push the ssh traffic from the client to the sandbox over the grpc connection. So its original purpose is no longer needed.

So we may not need to document this going forward. Wdyt?

Copy link
Copy Markdown
Collaborator

@maxamillion maxamillion left a comment

Choose a reason for hiding this comment

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

+1 good catch, thank you!

@maxamillion maxamillion merged commit af60d4e into NVIDIA:main May 9, 2026
5 of 6 checks passed
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.

3 participants