Skip to content

Support modifying vsock routes on existing sandboxes #1540

Description

@mogul

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" IMAGE

This 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.sock

However, the route is currently create-time only. That leaves two common recovery cases with no non-destructive fix:

  1. The host reboots, and the host ssh-agent comes back at a different SSH_AUTH_SOCK path. The persisted sandbox route still points at the old host socket path.
  2. Local msb state 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 --vsock route.

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 --restart

For 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" --restart

Then 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 modify plan/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#1290 requested exposing host Unix socket forwarding for ssh-agent use.
  • superradcompany/microsandbox#1297 added create-time --vsock routes.
  • superradcompany/microsandbox#1099 added msb modify with live / restart / next-start planning.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions