Expose sandbox nested-virt capability and pre-check create on the host - #375
Expose sandbox nested-virt capability and pre-check create on the host#375AprilNEA wants to merge 1 commit into
Conversation
Add SystemService.GetSandboxCapability so clients learn whether sandboxes can run (nested-virt microVMs) without booting one into an opaque KVM failure. The host computes it from the System VM backend plus a static host nested-virt probe (arcbox_hypervisor::host_supports_nested_virt), so arcbox sandbox create fails fast with an actionable message on unsupported hardware/backends — no round-trip into the guest. Refactor the Linux nested-virt detection out of KvmHypervisor into a reusable module function backing the new cross-platform helper. Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>
f5b1835 to
e64d7e3
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e64d7e3575
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| .to_string(), | ||
| ); | ||
| } | ||
| if backend == arcbox_vmm::VmBackend::Hv { |
There was a problem hiding this comment.
On a Linux x86_64 host with KVM nesting enabled and vm.backend = "hv" (also accepted through ARCBOX_VM_BACKEND=hv), this rejects sandbox creation even though the Linux VMM always executes initialize_linux() and ignores the macOS-only VmBackend selector. The new Linux host probe therefore returns true for a usable nested-KVM setup, but this branch reports it unsupported and makes arcbox sandbox create bail before reaching the guest; apply the HV/VZ restriction only on macOS.
Useful? React with 👍 / 👎.
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
ℹ️ No critical issues — two minor points, both inline.
Reviewed changes — a host-side sandbox nested-virt capability query plus a fast-fail pre-check on arcbox sandbox create, with the Linux nested-virt probe refactored into a reusable helper.
- New
GetSandboxCapabilityRPC —SystemServicegains an RPC returningSandboxCapability { supported, reason, backend }; proto message committed in the prost-generatedarcbox.v1.rs, tonic service code regenerates via arcbox-grpcOUT_DIR. Runtime::sandbox_capability()+ pureevaluate_sandbox_capability— host nested-virt is the hard gate (checked first), then the HV backend becomes the actionable "switch to vz" blocker; split out for the unit test.arcbox_hypervisor::host_supports_nested_virt()— cheap cross-platform probe (macOS VZ class-property, Linux x86_64 KVMnestedmodule params) that constructs no hypervisor; Linux detection lifted out ofKvmHypervisor::check_nested_virt(removed) intolinux::host_supports_nested_virt.- CLI
ensure_sandbox_supportedpre-check — runs beforeSandboxServiceClientcreate; transport/RPC errors fall through so older/not-ready daemons still proceed, with the guest agent as backstop. - Unit test —
sandbox_capability_gates_on_nested_virt_and_backendcovers the three gate outcomes.
ℹ️ Nitpicks
SandboxCapabilityis not added to the flatpub use v1::{...}block or theapisubmodule inrpc/arcbox-protocol/src/lib.rs, unlike sibling System types (ResolveImageFsResponse, etc.). It compiles because callers use thev1::SandboxCapabilitypath, but rpc/AGENTS.md's extending checklist calls for the hand-written re-export so the flatarcbox_protocol::SandboxCapabilitypath resolves for future consumers.
Claude Opus ｜ 𝕏
| if !host_nested_virt { | ||
| return ( | ||
| false, | ||
| "sandbox requires nested virtualization: the VZ backend on Apple \ |
There was a problem hiding this comment.
The reason strings here are macOS-specific ("the VZ backend on Apple Silicon M3 or newer with macOS 15+" and, below, "arcbox system backend vz"), but evaluate_sandbox_capability and the host_supports_nested_virt() probe both have real Linux paths (KVM nested module params). A Linux host with KVM nesting disabled would surface the Apple-Silicon message. Minor, and sandboxes are macOS-oriented, but the text is misleading off macOS.
Technical details
# macOS-centric reason strings on a cross-platform helper
## Affected sites
- `app/arcbox-core/src/runtime.rs:172-186` — both `reason` strings name Apple Silicon / macOS 15+ / `arcbox system backend vz`, yet the function is reached on Linux via `Runtime::sandbox_capability` → `arcbox_hypervisor::host_supports_nested_virt` (Linux KVM probe in `virt/arcbox-hypervisor/src/linux/mod.rs`).
## Required outcome
- On Linux, an unsupported result should read as a KVM-nesting message rather than an Apple-Silicon one — or the reason should be platform-conditional.
## Open questions for the human
- Is `arcbox sandbox create` a supported surface on Linux at all? If the System VM / sandbox architecture is macOS-only in practice, this is cosmetic and can be left as-is; if Linux is a real target, the strings should branch per platform.
Greptile SummaryThis PR exposes sandbox nested-virtualization capability on the host. The main changes are:
Confidence Score: 4/5The Linux ARM64 capability result and runtime readiness gate need fixes before merging. Nested-KVM-capable ARM64 hosts can be rejected before creation. The host-only RPC remains unavailable until the System VM is ready. Unexpected RPC failures are hidden and creation continues. virt/arcbox-hypervisor/src/linux/mod.rs, app/arcbox-api/src/system.rs, and app/arcbox-cli/src/commands/sandbox.rs
 T-Rex LogsWhat T-Rex did
Important Files Changed
Sequence Diagram%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant CLI
participant SystemService
participant Runtime
participant HostProbe
participant SandboxService
CLI->>SystemService: GetSandboxCapability
SystemService->>Runtime: sandbox_capability()
Runtime->>HostProbe: host_supports_nested_virt()
HostProbe-->>Runtime: supported
Runtime-->>SystemService: supported, reason, backend
SystemService-->>CLI: SandboxCapability
alt Supported or RPC unavailable
CLI->>SandboxService: Create
else Unsupported
CLI-->>CLI: Fail with reason
end
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant CLI
participant SystemService
participant Runtime
participant HostProbe
participant SandboxService
CLI->>SystemService: GetSandboxCapability
SystemService->>Runtime: sandbox_capability()
Runtime->>HostProbe: host_supports_nested_virt()
HostProbe-->>Runtime: supported
Runtime-->>SystemService: supported, reason, backend
SystemService-->>CLI: SandboxCapability
alt Supported or RPC unavailable
CLI->>SandboxService: Create
else Unsupported
CLI-->>CLI: Fail with reason
end
Reviews (1): Last reviewed commit: "feat(sandbox): expose nested-virt capabi..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| #[cfg(not(target_arch = "x86_64"))] | ||
| { | ||
| false | ||
| } |
There was a problem hiding this comment.
On Linux ARM64, this branch always reports false. A host with nested KVM enabled is therefore exposed as unsupported, so the new CLI pre-check blocks a sandbox that could run and shows an unrelated M3/macOS message.
Artifacts
- Contains supporting evidence from the run (text/x-shellscript; charset=utf-8).
- Contains supporting evidence from the run (text/x-rust; charset=utf-8).
- Keeps the command output available without making the summary code-heavy.
| &self, | ||
| _request: Request<Empty>, | ||
| ) -> Result<Response<SandboxCapability>, Status> { | ||
| let runtime = self.runtime.ready()?; |
There was a problem hiding this comment.
This host-only query uses shared_runtime, which is unavailable until full runtime initialization and System VM readiness. During daemon startup, clients receive UNAVAILABLE even after early_runtime contains the configured backend, so they cannot discover the capability without first booting the VM.
Context Used: AGENTS.md (source)
| } | ||
| // The capability RPC is unavailable (older daemon, not ready); let the | ||
| // create proceed rather than blocking on a missing pre-check. | ||
| Err(_) => Ok(()), |
There was a problem hiding this comment.
This arm treats every gRPC status as an unavailable capability RPC. A permission, data-loss, or internal server error therefore starts sandbox creation instead of reporting the failed pre-check; only compatibility and temporary-availability statuses should fall through.
| Err(_) => Ok(()), | |
| Err(status) | |
| if matches!( | |
| status.code(), | |
| tonic::Code::Unimplemented | tonic::Code::Unavailable | |
| ) => | |
| { | |
| Ok(()) | |
| } | |
| Err(status) => Err(status.into()), |
1 participant
Sandboxes need nested virtualization (
/dev/kvminside the System VM), available only on the VZ backend with M3+/macOS 15+. The guest already probes/dev/kvmat init and rejects sandbox RPCs withFAILED_PRECONDITION— but that's a round-trip into the guest, and clients have no way to know the surface is dead before aCreate.This surfaces the capability on the host so
arcbox sandbox createfails immediately with an actionable message, and clients (CLI/Desktop) can grey out sandbox features without booting a microVM.SystemService.GetSandboxCapabilityRPC returning{ supported, reason, backend }, computed from the System VM backend plus a static host nested-virt probe.arcbox_hypervisor::host_supports_nested_virt()— a cheap cross-platform probe (VZ on macOS, KVM module params on Linux x86_64) that doesn't construct a hypervisor. The Linux detection is refactored out ofKvmHypervisorto back it.arcbox sandbox createpre-checks and bails with the reason on unsupported hosts/backends; a missing/unavailable RPC falls through to the create (guest agent remains the backstop).On supported setups behavior is unchanged.
Closes CORE-13.