Skip to content

feat(sandbox): add canonical main process - #2726

Merged
sjenning merged 15 commits into
mainfrom
codex/2710-canonical-main-process
Aug 20, 2026
Merged

feat(sandbox): add canonical main process#2726
sjenning merged 15 commits into
mainfrom
codex/2710-canonical-main-process

Conversation

@drew

@drewdrew commented Aug 12, 2026•
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Add one canonical main process to every sandbox and make it the process observed by sandbox connect. The supervisor retains and multiplexes its session across reconnects, while sandbox exec remains an independent process path. Any unexpected canonical-process exit, including exit code 0, is persisted on the sandbox and transitions it to Error; intentional stop/start teardown is exempt.

Related Issue

Closes#2710

Changes

  • Add command and tty directly to the public and compute-driver sandbox specs, with sandbox-owned main instance and exit status.
  • Normalize omitted and pre-upgrade persisted driver specs to the default /bin/bash -l TTY main process.
  • Launch the canonical process in Docker, Podman, Kubernetes, and VM runtimes with exact argv transport and native runtime restart disabled.
  • Add a supervisor-owned PTY/pipe session multiplexer with bounded replay, live fanout, one stdin owner, read-only readers, resize, signals, and disconnect-safe process ownership.
  • Route sandbox connect through the retained main session while preserving independent exec, SFTP, editor, and forwarding behavior.
  • Make trailing sandbox create argv the persisted main process, attach interactively by default, and add --detach.
  • Record unexpected main-process exits as terminal sandbox errors and preserve intentional stop/start lifecycle transitions.
  • Update SDKs, architecture and published docs, driver references, CLI agent guidance, and E2E coverage.

Testing

  • mise run pre-commit
  • mise run test with an isolated system-gateway directory
  • Focused core, server, supervisor, VM driver, SDK, and CLI lifecycle tests
  • Docker sandbox lifecycle E2E, including competing attachments, disconnect/reconnect, same PID, PTY history replay, exit status, and --no-keep
  • Pre-upgrade VM driver-spec compatibility regression coverage

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • User-facing and architecture documentation updated
  • Related agent skill updated

@copy-pr-bot

copy-pr-botBot commented Aug 12, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions

github-actionsBot commented Aug 12, 2026

Copy link
Copy Markdown

🌿 Preview your docs:https://nvidia-preview-pr-2726.docs.buildwithfern.com/openshell

@drewdrew mentioned this pull request Aug 12, 2026
Closed
@drew

This comment was marked as resolved.

Sign in to view
@drew
drewforce-pushed the codex/2710-canonical-main-process branch from f192d21 to 05983c0CompareAugust 13, 2026 19:58
@drew

This comment was marked as resolved.

Sign in to view
@drew
drewforce-pushed the codex/2710-canonical-main-process branch 3 times, most recently from 5040f5c to 3416111CompareAugust 18, 2026 23:44
@drewdrew mentioned this pull request Aug 18, 2026
Open
9 tasks
@drew
drewforce-pushed the codex/2710-canonical-main-process branch from 3416111 to d52f50eCompareAugust 19, 2026 00:28
@drew
drew marked this pull request as ready for review August 19, 2026 00:30
@drew
drewforce-pushed the codex/2710-canonical-main-process branch from 37dfc68 to a209b62CompareAugust 19, 2026 15:43
sjenning
sjenning reviewed Aug 19, 2026
View reviewed changes
Comment threadcrates/openshell-supervisor-process/src/process.rs Outdated
rhuss
rhuss reviewed Aug 19, 2026
View reviewed changes
Comment thread.agents/skills/openshell-cli/cli-reference.md
@drew
drewforce-pushed the codex/2710-canonical-main-process branch from 24b1d4a to 08120b5CompareAugust 20, 2026 01:46
@elezarelezar mentioned this pull request Aug 20, 2026
Open
@drew
drewforce-pushed the codex/2710-canonical-main-process branch 4 times, most recently from 5560945 to 5133e9fCompareAugust 20, 2026 20:56
@drewdrew mentioned this pull request Aug 20, 2026
Merged
9 tasks
drew added 4 commits August 20, 2026 15:01
@drew
feat(sandbox): add canonical main process
f3635ea
Closes#2710
Persist and supervise one canonical workload per sandbox, attach sandbox connect to its retained session, and make every unexpected main-process exit terminal.
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
feat(sandbox): simplify canonical main process contract
c5b430c
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(sandbox): preserve legacy VM main compatibility
e9256ac
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(sandbox): preserve main status across driver updates
07e15cd
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
drew added 11 commits August 20, 2026 15:01
@drew
fix(sandbox): satisfy macOS process lint
463e0d4
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(sandbox): gate Linux exit acknowledgement publisher
365659f
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
refactor(sandbox): simplify main process plumbing
65d1d59
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(supervisor): make controlling tty ioctl portable
fdc14ed
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(supervisor): initialize canonical process environment
dd8d9ad
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
perf(supervisor): optimize retained main session
3f225e0
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
feat(sandbox): detach main session on ctrl-c
b7e2325
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(sandbox): use explicit main detach keys
5a1229e
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(dev): atomically stage Docker supervisor
3439936
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
fix(test): align Docker main environment assertion
4da80a6
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
feat(sdk): expose canonical main process fields
4a7a6a0
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@drew
drewforce-pushed the codex/2710-canonical-main-process branch from ef7f6e7 to 4a7a6a0CompareAugust 20, 2026 22:01
@sjenning
sjenning added this pull request to the merge queueAug 20, 2026
Merged via the queue into main with commit ef29680Aug 20, 2026
38 checks passed
@sjenning
sjenning deleted the codex/2710-canonical-main-process branch August 20, 2026 22:32
This was referenced Aug 20, 2026
Merged
Open
russellb added a commit to russellb/OpenShell that referenced this pull request Aug 21, 2026
@russellb
fix(kubernetes): strip MAIN_PROCESS_SPEC from proxy-pod workloads
575a447
Main renamed the canonical-command transport from OPENSHELL_SANDBOX_COMMAND to
the versioned OPENSHELL_MAIN_PROCESS_SPEC (NVIDIA#2726), which the supervisor decodes
and launches. proxy-pod runs the sandbox image directly with no supervisor, so
that env var is not only useless in the workload container but leaks the
intended command into it. Strip MAIN_PROCESS_SPEC alongside the other
supervisor-oriented variables, replacing the now-removed SANDBOX_COMMAND entry.
Rebase adaptation: proxy-pod's workload command continues to flow through the
containers.agent.command driver_config, since the canonical main process
requires an in-sandbox supervisor this topology does not run.
Signed-off-by: Russell Bryant <rbryant@redhat.com>
@johntmyersjohntmyers mentioned this pull request Aug 23, 2026
Open
14 tasks
russellb added a commit to russellb/OpenShell that referenced this pull request Aug 24, 2026
@russellb
fix(kubernetes): strip MAIN_PROCESS_SPEC from proxy-pod workloads
a2ea65e
Main renamed the canonical-command transport from OPENSHELL_SANDBOX_COMMAND to
the versioned OPENSHELL_MAIN_PROCESS_SPEC (NVIDIA#2726), which the supervisor decodes
and launches. proxy-pod runs the sandbox image directly with no supervisor, so
that env var is not only useless in the workload container but leaks the
intended command into it. Strip MAIN_PROCESS_SPEC alongside the other
supervisor-oriented variables, replacing the now-removed SANDBOX_COMMAND entry.
Rebase adaptation: proxy-pod's workload command continues to flow through the
containers.agent.command driver_config, since the canonical main process
requires an in-sandbox supervisor this topology does not run.
Signed-off-by: Russell Bryant <rbryant@redhat.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pimlockpimlockpimlock left review comments
@sjenningsjenningsjenning approved these changes
@mrunalpmrunalpAwaiting requested review from mrunalpmrunalp is a code owner
@derekwaynecarrderekwaynecarrAwaiting requested review from derekwaynecarrderekwaynecarr is a code owner
+1 more reviewer
@rhussrhussrhuss left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat: define a canonical sandbox main process and reconnectable session

4 participants

@drew@rhuss@sjenning@pimlock