Skip to content

Quickly sandbox your AI agent.

Python

Windows now uses virtio-serial chardev over a loopback TCP socket instead of a Unix path

Jace Medlin22ec9bf44f1d
diff --git a/packages/quicksand-core/quicksand_core/host/virtio_serial_agent_client.py b/packages/quicksand-core/quicksand_core/host/virtio_serial_agent_client.py
index b16c57d..cfc09e4 100644
--- a/packages/quicksand-core/quicksand_core/host/virtio_serial_agent_client.py
+++ b/packages/quicksand-core/quicksand_core/host/virtio_serial_agent_client.py
@@ -58,8 +58,22 @@ class VirtioSerialAgentClient:
are dropped at the reader.
"""
- def __init__(self, socket_path: str | Path, token: str):
- self._socket_path = str(socket_path)
+ def __init__(
+ self,
+ socket_path: str | Path | None,
+ token: str,
+ *,
+ socket_port: int | None = None,
+ ):
+ # The agent chardev is a Unix domain socket on Linux/macOS (addressed by
+ # filesystem path) and a TCP socket on Windows (addressed by loopback
+ # port), because asyncio has no open_unix_connection on Windows and QEMU
+ # for Windows cannot serve a path-based socket chardev. Exactly one of
+ # socket_path / socket_port is set by the caller.
+ if (socket_path is None) == (socket_port is None):
+ raise ValueError("Provide exactly one of socket_path or socket_port")
+ self._socket_path = str(socket_path) if socket_path is not None else None
+ self._socket_port = socket_port
self._token = token
self._reader: asyncio.StreamReader | None = None
self._writer: asyncio.StreamWriter | None = None
@@ -105,7 +119,10 @@ class VirtioSerialAgentClient:
# the successful one so the demux reader doesn't see them.
auth_writes_pending = 0
- logger.debug("Connecting to agent via virtio-serial: %s", self._socket_path)
+ target = (
+ self._socket_path if self._socket_path is not None else f"127.0.0.1:{self._socket_port}"
+ )
+ logger.debug("Connecting to agent via virtio-serial: %s", target)
while loop.time() < deadline:
attempt += 1
@@ -120,7 +137,12 @@ class VirtioSerialAgentClient:
# the virtio-serial device).
if self._writer is None:
try:
- reader, writer = await asyncio.open_unix_connection(self._socket_path)
+ if self._socket_port is not None:
+ reader, writer = await asyncio.open_connection(
+ "127.0.0.1", self._socket_port
+ )
+ else:
+ reader, writer = await asyncio.open_unix_connection(self._socket_path)
self._reader = reader
self._writer = writer
except (OSError, ConnectionRefusedError) as e:
diff --git a/packages/quicksand-core/quicksand_core/qemu/platform.py b/packages/quicksand-core/quicksand_core/qemu/platform.py
index 91b34d3..d997592 100644
--- a/packages/quicksand-core/quicksand_core/qemu/platform.py
+++ b/packages/quicksand-core/quicksand_core/qemu/platform.py
@@ -143,6 +143,7 @@ class PlatformConfig:
smb_port: int | None = None,
smb_server: SMBServer | None = None,
agent_socket_path: Path | None = None,
+ agent_socket_port: int | None = None,
) -> list[str]:
"""Build the complete QEMU command line."""
data_dir = runtime_info.data_dir
@@ -229,8 +230,13 @@ class PlatformConfig:
if qmp_port is not None:
cmd.extend(["-qmp", f"tcp:127.0.0.1:{qmp_port},server,nowait"])
- if agent_socket_path is not None:
- cmd.extend(self._build_virtio_serial_args(agent_socket_path))
+ if agent_socket_path is not None or agent_socket_port is not None:
+ cmd.extend(
+ self._build_virtio_serial_args(
+ socket_path=agent_socket_path,
+ socket_port=agent_socket_port,
+ )
+ )
cmd.extend(
self._build_kernel_args(config, kernel_path, initrd_path, agent_port, agent_token)
@@ -273,17 +279,33 @@ class PlatformConfig:
def _build_virtio_serial_args(
self,
- socket_path: Path,
+ socket_path: Path | None = None,
+ socket_port: int | None = None,
) -> list[str]:
- """Build QEMU args for virtio-serial agent channel."""
+ """Build QEMU args for virtio-serial agent channel.
+
+ The host end of the chardev is a Unix domain socket on Linux/macOS
+ (``path=``) and a TCP socket on Windows (``host=``/``port=``), since
+ QEMU for Windows does not support path-based socket chardevs and Python
+ has no ``asyncio.open_unix_connection`` there. Exactly one of
+ ``socket_path`` / ``socket_port`` is provided.
+ """
+ if (socket_path is None) == (socket_port is None):
+ raise ValueError("Provide exactly one of socket_path or socket_port")
+
use_mmio = self.arch.machine_type == MachineType.VIRT
serial_device = "virtio-serial-device" if use_mmio else "virtio-serial-pci"
+ if socket_port is not None:
+ chardev = f"socket,host=127.0.0.1,port={socket_port},server=on,wait=off,id=vserial0"
+ else:
+ chardev = f"socket,path={socket_path},server=on,wait=off,id=vserial0"
+
return [
"-device",
serial_device,
"-chardev",
- f"socket,path={socket_path},server=on,wait=off,id=vserial0",
+ chardev,
"-device",
"virtserialport,chardev=vserial0,name=quicksand.agent.0",
]
diff --git a/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py b/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py
index 2148139..a7f57b4 100644
--- a/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py
+++ b/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py
@@ -138,9 +138,17 @@ class _LifecycleMixin(_SandboxProtocol):
if self.config.enable_display:
self._vnc_port = find_free_vnc_port()
- # Create virtio-serial socket path for agent communication.
+ # Create the virtio-serial agent chardev endpoint. On Linux/macOS this
+ # is a Unix domain socket addressed by filesystem path. On Windows,
+ # QEMU cannot serve a path-based socket chardev and asyncio has no
+ # open_unix_connection, so we use a loopback TCP socket instead.
assert self._temp_dir is not None
- self._agent_socket_path = self._temp_dir / "agent.sock"
+ if sys.platform == "win32":
+ self._agent_socket_path = None
+ self._agent_socket_port = find_free_port()
+ else:
+ self._agent_socket_path = self._temp_dir / "agent.sock"
+ self._agent_socket_port = None
# Start the SMB server early so the guestfwd command can be embedded
# in the QEMU command line. QuicksandSMBServer uses guestfwd in all
@@ -330,6 +338,7 @@ class _LifecycleMixin(_SandboxProtocol):
smb_port=smb_port,
smb_server=self._smb_server,
agent_socket_path=self._agent_socket_path,
+ agent_socket_port=self._agent_socket_port,
)
async def _wait_for_guest_agent(self) -> None:
@@ -346,11 +355,15 @@ class _LifecycleMixin(_SandboxProtocol):
# Try virtio-serial first (faster: no guest networking dependency).
# Fall back to HTTP if the socket path doesn't exist or connection fails.
- if self._agent_socket_path is not None:
+ if self._agent_socket_path is not None or self._agent_socket_port is not None:
try:
from ..host.virtio_serial_agent_client import VirtioSerialAgentClient
- client = VirtioSerialAgentClient(self._agent_socket_path, self._agent_token)
+ client = VirtioSerialAgentClient(
+ self._agent_socket_path,
+ self._agent_token,
+ socket_port=self._agent_socket_port,
+ )
await client.connect(
timeout=self._accel.boot_timeout,
process_check=check_process,
@@ -358,7 +371,7 @@ class _LifecycleMixin(_SandboxProtocol):
self._agent_client = client
logger.debug("Connected to agent via virtio-serial")
return
- except (TimeoutError, RuntimeError, OSError) as e:
+ except (TimeoutError, RuntimeError, OSError, NotImplementedError) as e:
logger.debug("Virtio-serial connection failed, falling back to HTTP: %s", e)
# Fallback: HTTP via hostfwd
@@ -437,6 +450,7 @@ class _LifecycleMixin(_SandboxProtocol):
self._agent_port = None
self._agent_token = None
self._agent_socket_path = None
+ self._agent_socket_port = None
if cleanup_errors:
error_summary = "; ".join(f"{resource}: {err}" for resource, err in cleanup_errors)
diff --git a/packages/quicksand-core/quicksand_core/sandbox/_protocol.py b/packages/quicksand-core/quicksand_core/sandbox/_protocol.py
index 0ad665e..63ed8d6 100644
--- a/packages/quicksand-core/quicksand_core/sandbox/_protocol.py
+++ b/packages/quicksand-core/quicksand_core/sandbox/_protocol.py
@@ -54,6 +54,8 @@ class _SandboxProtocol(Protocol):
_agent_client: AgentClient | None
_agent_port: int | None
_agent_token: str | None
+ _agent_socket_path: Path | None
+ _agent_socket_port: int | None
_qmp_client: QMPClient | None
_qmp_port: int | None
_qmp_checkpoints: list[str]
diff --git a/packages/quicksand-core/quicksand_core/sandbox/_sandbox.py b/packages/quicksand-core/quicksand_core/sandbox/_sandbox.py
index 375b001..fc138cf 100644
--- a/packages/quicksand-core/quicksand_core/sandbox/_sandbox.py
+++ b/packages/quicksand-core/quicksand_core/sandbox/_sandbox.py
@@ -99,6 +99,7 @@ class Sandbox(
self._agent_port: int | None = None
self._agent_token: str | None = None
self._agent_socket_path: Path | None = None
+ self._agent_socket_port: int | None = None
self._qmp_client: QMPClient | None = None
self._qmp_port: int | None = None
self._qmp_checkpoints: list[str] = []