Skip to content

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.py
index 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 StrEnum
from pathlib import Path
from typing import Literal, Protocol, TypedDict, runtime_checkable
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
from .host import Accelerator
@@ -588,6 +588,21 @@ class SandboxConfig(BaseModel):
disk_size: str | None = None
enable_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__.py
index 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 arch
from . import os_ as os
from .arch import Architecture
+from .host_memory import get_host_memory_bytes
from .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.py
new file mode 100644
index 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_size
diff --git a/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py b/packages/quicksand-core/quicksand_core/sandbox/_lifecycle.py
index 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 None
assert self._image is not None
diff --git a/packages/quicksand-core/quicksand_core/utils/__init__.py b/packages/quicksand-core/quicksand_core/utils/__init__.py
index 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_size
from .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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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)