Repository navigation
Description
Summary
Please extend msb modify to support adding, removing, and replacing sandbox vsock routes, at least as a requires-restart / next-start configuration change.
The main use case is recovering host Unix socket forwarding, especially ssh-agent forwarding, when the host socket path changes after a host reboot or when a sandbox exists under a name but was created without the required --vsock route.
Motivation / use case
msb now supports host IPC routes at create time:
msb create --name devbox --vsock "$SSH_AUTH_SOCK:3552/stream" IMAGEThis works well for forwarding the host ssh-agent into the guest. A guest-side bridge can then expose it as a Unix socket and set:
SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sockHowever, the route is currently create-time only. That leaves two common recovery cases with no non-destructive fix:
- The host reboots, and the host ssh-agent comes back at a different
SSH_AUTH_SOCKpath. The persisted sandbox route still points at the old host socket path. - Local
msbstate is wiped or replaced, while higher-level tooling still reuses the same sandbox name. A sandbox with the expected name exists, but it was created without the ssh-agent--vsockroute.
In both cases, the guest filesystem and workspace state may still be valuable. The only current fix is to remove and recreate the sandbox, which is heavier than necessary and can discard useful guest-local state.
Proposed behavior
Add vsock route support to msb modify.
Example CLI shapes, open to your preferred syntax:
# Add or replace a stream route, applying on restart
msb modify devbox --vsock "$SSH_AUTH_SOCK:3552/stream" --restart
# Save the route for the next start without touching a running VM
msb modify devbox --vsock "$SSH_AUTH_SOCK:3552/stream" --next-start
# Remove a route by guest port/type
msb modify devbox --vsock-rm 3552/stream --restartFor running sandboxes, it would be fine for route changes to plan as requires restart rather than live, matching the existing msb modify model for boot-boundary changes.
For stopped sandboxes, route changes could be saved as next start.
For --restart, msb would update the persisted config, restart the sandbox, and boot it with the new route.
Desired planning semantics
| Sandbox state | Change | Disposition |
|---|---|---|
| Running | Add route | requires restart |
| Running | Remove route | requires restart |
| Running | Replace same port/type with new host path | requires restart |
| Stopped | Add/remove/replace route | next start |
| Running, if dynamic route registration is supported later | Add/remove/replace route | live |
A live implementation would be great if the runtime can safely register and unregister libkrun host socket routes after boot, but a restart-backed implementation is sufficient for the recovery use case.
Why this is useful
This lets callers recover without deleting and recreating the whole sandbox.
For example, after a host reboot:
msb modify devbox --vsock "$SSH_AUTH_SOCK:3552/stream" --restartThen higher-level tooling can restart its guest-side bridge and continue using the same sandbox state.
This is also useful when a sandbox exists under a reused name but lacks the route. Tooling can detect the mismatch with msb inspect, then repair by applying the route to the existing sandbox instead of forcing a full recreate.
Security considerations
Host socket forwarding widens the host/guest trust boundary. The existing --vsock security model should continue to apply:
- Explicit opt-in only.
- Local backend only.
- Not available for multi-tenant deployments.
- Validate host paths and reject duplicate route keys.
- Keep route changes visible in
msb inspect. - Preserve the all-or-nothing
msb modifyplan/apply model.
For ssh-agent forwarding specifically, callers should still warn users that guest code can ask the host agent to perform signing/auth operations for loaded keys.
Compatibility
This can build on the existing msb modify planning model introduced in superradcompany/microsandbox#1099 and the existing create-time route model from superradcompany/microsandbox#1297.
No need to promise live mutation initially. Treating vsock route changes as restart-required would still solve the major recovery problem while keeping the implementation aligned with the existing boot-boundary configuration model.
Related context
superradcompany/microsandbox#1290requested exposing host Unix socket forwarding for ssh-agent use.superradcompany/microsandbox#1297added create-time--vsockroutes.superradcompany/microsandbox#1099addedmsb modifywith live / restart / next-start planning.
Activity