Skip to content

[docs] sbx/gVisor: Sync sbx-integration.md main-action.ts wiring with SbxRuntimeBackend #7641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 2 commits into from
Aug 22, 2026
Merged

[docs] sbx/gVisor: Sync sbx-integration.md main-action.ts wiring with SbxRuntimeBackend #7641

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
06606a2
docs: sync sbx doc with SbxRuntimeBackend wiring
github-actions[bot] Aug 22, 2026
48ccdc7
Potential fix for pull request finding
lpcox Aug 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions docs/sbx-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,12 +274,19 @@ widen the mount set to include the libraries those tools need.

### Wiring into the main workflow (`src/commands/main-action.ts`)

`main-action.ts` decides `useSbx = !runtimeUsesComposeAgent(config.containerRuntime)`
and, when true, substitutes two functions into the shared workflow runner:

- **`sbxStartContainers`** wraps the normal `startContainers` (which brings up
`main-action.ts` calls `resolveExternalRuntimeBackend(config, startContainers)`
(`src/external-runtime-backend-resolver.ts`), which returns `undefined` for
compose runtimes (`runtimeUsesComposeAgent` is `true`) and otherwise looks up a
factory keyed by `config.containerRuntime`. For `sbx` the factory is
`createSbxRuntimeBackend`, which constructs a `SbxRuntimeBackend`
(`src/sbx-runtime-backend.ts`) implementing the `ExternalAgentRuntimeBackend`
contract (`src/external-runtime-backend.ts`). `adaptExternalRuntimeBackend()`
then maps the backend's `start`/`exec` methods onto the shared
`startContainers`/`runAgentCommand` workflow seam:

- **`backend.start`** wraps the normal `startContainers` (which brings up
the infra-only compose: Squid + api-proxy, no agent service), then:
1. Verifies `isSbxAvailable()`.
1. Verifies `isSbxAvailable()` via `preflight()`.
2. Builds the agent environment (`buildAgentEnvironment`) using microVM-specific
network targets (see below), merging credential env
(`buildAgentCredentialEnv`) when the api-proxy is enabled.
Expand All @@ -296,12 +303,14 @@ and, when true, substitutes two functions into the shared workflow runner:
unreachable after all retries, because an isolated runtime that cannot reach
`/reflect` cannot do model auto-resolution or credit accounting.
6. Runs a Squid connectivity diagnostic (`curl --proxy ... https://api.github.com`).
- **`sbxRunAgentCommand`** runs the actual agent command with `execInSandbox`,
- **`backend.exec`** runs the actual agent command with `execInSandbox`,
honoring the agent timeout, workdir, TTY, and computed environment, and dumps
api-proxy logs on non-zero exit for debugging.
api-proxy logs on non-zero exit for debugging (`collectDiagnostics()`).

Cleanup: when the runtime is microVM and `--keep-containers` is not set,
`removeSandbox(SBX_DEFAULT_NAME)` runs before compose teardown.
Cleanup: unless `--keep-containers` is set, `SbxRuntimeBackend.stop()` calls
`removeSandbox(SBX_DEFAULT_NAME)`; `main-action.ts` wires this into both signal
handling (`fastKillAgentContainer` substitution) and the normal cleanup path,
running before compose teardown.

### Networking: crossing the VM boundary

Expand Down
Loading