Quickly sandbox your AI agent.
Python
feat(quicksand-core): validate sandbox memory and warn on host budget overrun
Tyler Payne8a85c4b3868c
diff --git a/packages/quicksand-core/quicksand_core/_types.py b/packages/quicksand-core/quicksand_core/_types.pyindex df26513..d609538 100644--- a/packages/quicksand-core/quicksand_core/_types.py+++ b/packages/quicksand-core/quicksand_core/_types.py@@ -17,7 +17,7 @@ from enum import StrEnumfrom pathlib import Pathfrom typing import Literal, Protocol, TypedDict, runtime_checkable-from pydantic import BaseModel, ConfigDict+from pydantic import BaseModel, ConfigDict, field_validatorfrom .host import Accelerator@@ -588,6 +588,21 @@ class SandboxConfig(BaseModel):disk_size: str | None = Noneenable_display: bool = False+ @field_validator("memory")+ @classmethod+ def _validate_memory(cls, v: str) -> str:+ from .utils.memory import parse_memory_size++ parse_memory_size(v)+ return v++ @property+ def memory_bytes(self) -> int:+ """Configured guest RAM in bytes."""+ from .utils.memory import parse_memory_size++ return parse_memory_size(self.memory)+class SandboxConfigParams(TypedDict, total=False):"""TypedDict mirror of :class:`SandboxConfig` for ``Unpack``-based kwargs.diff --git a/packages/quicksand-core/quicksand_core/host/__init__.py b/packages/quicksand-core/quicksand_core/host/__init__.pyindex a4c11bc..602f063 100644--- a/packages/quicksand-core/quicksand_core/host/__init__.py+++ b/packages/quicksand-core/quicksand_core/host/__init__.py@@ -9,6 +9,7 @@ This package provides host-specific configuration including:from . import archfrom . import os_ as osfrom .arch import Architecture+from .host_memory import get_host_memory_bytesfrom .os_ import (OS,Accelerator,@@ -31,5 +32,6 @@ __all__ = ["OSConfig","WindowsConfig","arch",+ "get_host_memory_bytes","os",]diff --git a/packages/quicksand-core/quicksand_core/host/host_memory.py b/packages/quicksand-core/quicksand_core/host/host_memory.pynew file mode 100644index 0000000..d8aa027--- /dev/null+++ b/packages/quicksand-core/quicksand_core/host/host_memory.py@@ -0,0 +1,28 @@+"""Cross-platform host physical RAM detection.++Best-effort: returns ``None`` on platforms where we can't determine the+value. Used by the sandbox lifecycle to emit a budget warning when a+sandbox is configured to use a large fraction of host RAM.+"""++from __future__ import annotations++import os++__all__ = ["get_host_memory_bytes"]+++def get_host_memory_bytes() -> int | None:+ """Return total physical RAM in bytes, or ``None`` if unavailable.++ Works on Linux and macOS via ``sysconf``. Returns ``None`` on Windows+ or any platform where the values can't be read.+ """+ try:+ pages = os.sysconf("SC_PHYS_PAGES")+ page_size = os.sysconf("SC_PAGE_SIZE")+ except (AttributeError, ValueError, OSError):+ return None+ if pages <= 0 or page_size <= 0:+ return None+ return pages * page_sizediff --git a/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py b/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.pyindex b95f082..504c7f2 100644--- a/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py+++ b/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py@@ -128,6 +128,8 @@ class _LifecycleMixin(_SandboxProtocol):"""Generate agent credentials, build the VM command, and start QEMU."""from ..utils import find_free_port, find_free_vnc_port+ self._check_memory_budget()+self._agent_token = secrets.token_hex(16)self._agent_port = find_free_port()self._qmp_port = find_free_port()@@ -207,6 +209,38 @@ class _LifecycleMixin(_SandboxProtocol):# start() helpers# ------------------------------------------------------------------+ def _check_memory_budget(self) -> None:+ """Warn if the configured guest RAM is large relative to host RAM.++ Best-effort: silent on platforms where host RAM can't be detected.+ """+ from ..host import get_host_memory_bytes+ from ..utils.memory import format_bytes++ host_total = get_host_memory_bytes()+ if host_total is None:+ return++ configured = self.config.memory_bytes+ ratio = configured / host_total++ if ratio > 1.0:+ logger.warning(+ "Sandbox memory %s exceeds host RAM %s (%.0f%%) — guest will "+ "likely be killed by the host OOM killer once it touches enough pages.",+ format_bytes(configured),+ format_bytes(host_total),+ ratio * 100,+ )+ elif ratio > 0.8:+ logger.warning(+ "Sandbox memory %s is %.0f%% of host RAM (%s) — concurrent "+ "sandboxes or other workloads may push the host into swap.",+ format_bytes(configured),+ ratio * 100,+ format_bytes(host_total),+ )+def _create_overlay(self) -> None:assert self._overlay_manager is not Noneassert self._image is not Nonediff --git a/packages/quicksand-core/quicksand_core/utils/__init__.py b/packages/quicksand-core/quicksand_core/utils/__init__.pyindex a7fc360..7e5bc73 100644--- a/packages/quicksand-core/quicksand_core/utils/__init__.py+++ b/packages/quicksand-core/quicksand_core/utils/__init__.py@@ -1,6 +1,7 @@"""Shared utilities for quicksand-core."""from .hashing import DEFAULT_CHUNK_SIZE, compute_file_sha256+from .memory import format_bytes, parse_memory_sizefrom .network import find_free_port, find_free_vnc_port__all__ = [@@ -8,4 +9,6 @@ __all__ = ["compute_file_sha256","find_free_port","find_free_vnc_port",+ "format_bytes",+ "parse_memory_size",]diff --git a/packages/quicksand-core/quicksand_core/utils/memory.py b/packages/quicksand-core/quicksand_core/utils/memory.pynew file mode 100644index 0000000..603cdcd--- /dev/null+++ b/packages/quicksand-core/quicksand_core/utils/memory.py@@ -0,0 +1,70 @@+"""Parse and validate QEMU-style memory size strings.++QEMU's ``-m`` flag accepts a bare integer (interpreted as MiB) or a number+with a unit suffix: ``K``, ``M``, ``G``, ``T`` (case-insensitive, binary+units — 1024-based). For ergonomics we also accept the ``KiB``/``MiB``/...+forms and a trailing ``B``, all of which mean the same as the bare suffix.+"""++from __future__ import annotations++import re++__all__ = ["format_bytes", "parse_memory_size"]+++_UNIT_MULTIPLIERS = {+ "": 1024**2, # bare number -> MiB (matches QEMU's -m default)+ "k": 1024,+ "m": 1024**2,+ "g": 1024**3,+ "t": 1024**4,+}++_PATTERN = re.compile(r"^(\d+(?:\.\d+)?)\s*([kmgtKMGT]?)(?:i?[bB]?)$")+++def parse_memory_size(value: str | int) -> int:+ """Parse a QEMU memory size into bytes.++ Accepts a bare int (interpreted as MiB, matching QEMU's default), or a+ string of the form ``"<number>[<unit>]"`` where unit is one of K/M/G/T+ (case-insensitive). Fractional values are allowed (``"1.5G"``). Optional+ ``i`` and/or trailing ``B`` are accepted (``"512MiB"``, ``"2GB"``).++ Raises ``ValueError`` for unparseable input or non-positive sizes.+ """+ if isinstance(value, int):+ if value <= 0:+ raise ValueError(f"memory must be positive, got {value}")+ return value * _UNIT_MULTIPLIERS["m"]++ s = value.strip()+ if not s:+ raise ValueError("memory must not be empty")++ m = _PATTERN.match(s)+ if not m:+ raise ValueError(+ f"invalid memory size {value!r}: expected forms like '512M', '2G', "+ f"'1.5G', '2048' (MiB), '512MiB', '4GB'"+ )++ number_str, unit = m.group(1), m.group(2).lower()+ number = float(number_str)+ if number <= 0:+ raise ValueError(f"memory must be positive, got {value!r}")++ bytes_ = int(number * _UNIT_MULTIPLIERS[unit])+ if bytes_ <= 0:+ raise ValueError(f"memory rounds to zero bytes: {value!r}")+ return bytes_+++def format_bytes(n: int) -> str:+ """Render a byte count as a short human-readable string (e.g. ``'1.5G'``)."""+ for unit, mult in (("T", 1024**4), ("G", 1024**3), ("M", 1024**2), ("K", 1024)):+ if n >= mult:+ value = n / mult+ return f"{value:.1f}{unit}" if value < 10 else f"{value:.0f}{unit}"+ return f"{n}B"diff --git a/tests/unit/test_host_memory_budget.py b/tests/unit/test_host_memory_budget.pynew file mode 100644index 0000000..02e278e--- /dev/null+++ b/tests/unit/test_host_memory_budget.py@@ -0,0 +1,83 @@+"""Tests for host RAM detection and the per-sandbox budget warning."""++from __future__ import annotations++import logging+from pathlib import Path+from unittest.mock import patch++from quicksand_core import Sandbox+from quicksand_core._types import ResolvedAccelerator, ResolvedImage+from quicksand_core.host import Accelerator, get_host_memory_bytes++_HOST_RAM = "quicksand_core.host.get_host_memory_bytes"+_LOGGER = "quicksand.sandbox"+++class TestGetHostMemoryBytes:+ def test_returns_positive_int_on_unix(self):+ # Linux + macOS both implement SC_PHYS_PAGES.+ result = get_host_memory_bytes()+ assert result is None or (isinstance(result, int) and result > 0)+++def _prep_sandbox(memory: str, fake_image_set, mock_runtime) -> Sandbox:+ sandbox = Sandbox(image="ubuntu", memory=memory)+ sandbox._runtime_info = mock_runtime+ sandbox._image = ResolvedImage(name="ubuntu", chain=[fake_image_set["qcow2"]])+ sandbox._accel = ResolvedAccelerator(accel=Accelerator.HVF)+ sandbox._overlay_path = Path("/tmp/overlay.qcow2")+ return sandbox+++class TestMemoryBudgetWarning:+ def test_silent_when_well_under_budget(self, fake_image_set, mock_runtime, caplog):+ sandbox = _prep_sandbox("256M", fake_image_set, mock_runtime)+ # Pretend host has 64G of RAM regardless of actual host.+ with (+ patch(_HOST_RAM, return_value=64 * 1024**3),+ caplog.at_level(logging.WARNING, logger=_LOGGER),+ ):+ sandbox._check_memory_budget()+ assert not [r for r in caplog.records if r.levelno >= logging.WARNING]++ def test_warns_above_80_percent(self, fake_image_set, mock_runtime, caplog):+ sandbox = _prep_sandbox("4G", fake_image_set, mock_runtime)+ # 100% — triggers the stronger branch.+ with (+ patch(_HOST_RAM, return_value=4 * 1024**3),+ caplog.at_level(logging.WARNING, logger=_LOGGER),+ ):+ sandbox._check_memory_budget()+ assert any(+ "100%" in r.getMessage() or "exceeds host RAM" in r.getMessage() for r in caplog.records+ )++ def test_warns_when_over_host_ram(self, fake_image_set, mock_runtime, caplog):+ sandbox = _prep_sandbox("16G", fake_image_set, mock_runtime)+ with (+ patch(_HOST_RAM, return_value=8 * 1024**3),+ caplog.at_level(logging.WARNING, logger=_LOGGER),+ ):+ sandbox._check_memory_budget()+ assert any("exceeds host RAM" in r.getMessage() for r in caplog.records)++ def test_warns_at_85_percent(self, fake_image_set, mock_runtime, caplog):+ sandbox = _prep_sandbox("3400M", fake_image_set, mock_runtime) # 85% of 4G+ with (+ patch(_HOST_RAM, return_value=4 * 1024**3),+ caplog.at_level(logging.WARNING, logger=_LOGGER),+ ):+ sandbox._check_memory_budget()+ msgs = [r.getMessage() for r in caplog.records]+ assert any("of host RAM" in m for m in msgs)+ assert not any("exceeds host RAM" in m for m in msgs)++ def test_silent_when_host_ram_unknown(self, fake_image_set, mock_runtime, caplog):+ sandbox = _prep_sandbox("64G", fake_image_set, mock_runtime)+ with (+ patch(_HOST_RAM, return_value=None),+ caplog.at_level(logging.WARNING, logger=_LOGGER),+ ):+ sandbox._check_memory_budget()+ assert not [r for r in caplog.records if r.levelno >= logging.WARNING]diff --git a/tests/unit/test_memory_parsing.py b/tests/unit/test_memory_parsing.pynew file mode 100644index 0000000..90372eb--- /dev/null+++ b/tests/unit/test_memory_parsing.py@@ -0,0 +1,85 @@+"""Tests for memory size parsing and SandboxConfig.memory validation."""++from __future__ import annotations++import pytest+from pydantic import ValidationError+from quicksand_core import SandboxConfig+from quicksand_core.utils.memory import format_bytes, parse_memory_size+++class TestParseMemorySize:+ @pytest.mark.parametrize(+ "value,expected",+ [+ ("512M", 512 * 1024**2),+ ("2G", 2 * 1024**3),+ ("1.5G", int(1.5 * 1024**3)),+ ("4K", 4 * 1024),+ ("1T", 1024**4),+ ("2048", 2048 * 1024**2), # bare number is MiB+ (2048, 2048 * 1024**2), # bare int is MiB+ ("512m", 512 * 1024**2), # case-insensitive+ ("512MiB", 512 * 1024**2), # KiB/MiB style accepted+ ("2GB", 2 * 1024**3),+ ("4GiB", 4 * 1024**3),+ (" 1G ", 1024**3), # whitespace tolerated+ ],+ )+ def test_valid(self, value, expected):+ assert parse_memory_size(value) == expected++ @pytest.mark.parametrize(+ "value",+ [+ "",+ " ",+ "abc",+ "1X",+ "1.5.5G",+ "-1G",+ "0",+ "0G",+ "0.0001K", # rounds to zero bytes+ "G",+ ],+ )+ def test_invalid(self, value):+ with pytest.raises(ValueError):+ parse_memory_size(value)++ def test_negative_int_rejected(self):+ with pytest.raises(ValueError):+ parse_memory_size(-1)+++class TestFormatBytes:+ @pytest.mark.parametrize(+ "n,expected",+ [+ (512 * 1024**2, "512M"),+ (1024**3, "1.0G"),+ (int(1.5 * 1024**3), "1.5G"),+ (16 * 1024**3, "16G"),+ (4 * 1024, "4.0K"),+ (500, "500B"),+ ],+ )+ def test_format(self, n, expected):+ assert format_bytes(n) == expected+++class TestSandboxConfigMemoryValidation:+ def test_default_parses(self):+ config = SandboxConfig(image="ubuntu")+ assert config.memory == "512M"+ assert config.memory_bytes == 512 * 1024**2++ def test_valid_memory(self):+ config = SandboxConfig(image="ubuntu", memory="2G")+ assert config.memory_bytes == 2 * 1024**3++ @pytest.mark.parametrize("bad", ["abc", "-2G", "0", "1XY", ""])+ def test_invalid_memory_rejected(self, bad):+ with pytest.raises(ValidationError):+ SandboxConfig(image="ubuntu", memory=bad)