drukbox-python-sdk 0.0.5__tar.gz → 0.0.7__tar.gz

drukbox_python_sdk-0.0.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Alvarado Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

drukbox_python_sdk-0.0.5/README.md → drukbox_python_sdk-0.0.7/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: drukbox-python-sdk
+Version: 0.0.7
+Summary: Async Python client for Drukbox.
+Project-URL: Homepage, https://github.com/clawhaven/drukbox-python-sdk
+Project-URL: Repository, https://github.com/clawhaven/drukbox-python-sdk
+Project-URL: Issues, https://github.com/clawhaven/drukbox-python-sdk/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
 # drukbox-python-sdk
 
 Async Python client for the [Drukbox] host API.
@@ -58,6 +71,7 @@ Public exports live in `drukbox_sdk`:
 - `SandboxAPI`
 - `SandboxHost`
 - `DoctorReport` and `DoctorCheck`
+- `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -67,12 +81,34 @@ Supported host operations:
 - `get_host`
 - `attach`
 - `list_hosts`
+- `renew_host`
 - `delete_host`
 - `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`provider`, and `Idempotency-Key` inputs.
+`provider`, `instance_type`, `disk_gb`, and `Idempotency-Key` inputs.
+`instance_type` (provider-native size, e.g. `t3.xlarge` / `cx33`) and `disk_gb`
+pin the VM shape; omit either for the provider default. `expires_at` mirrors the
+wire contract: omit it for the default lease, pass a datetime for an explicit
+expiry, or pass `None` for a never-reaped (permanent) host.
+
+`renew_host` extends a host's lease via `POST /hosts/{id}/renew`. Omit
+`expires_at` to extend by the service's default TTL; renewal never makes a host
+permanent.
+
+Supported HTTP-proxy operations:
+
+- `create_http_proxy`
+- `delete_http_proxy`
+- `attach_http_proxy`
+- `detach_http_proxy`
+
+HTTP proxies are account-bound exe.dev resources, not host state — deleting a
+host does not remove proxies fronting it. `create_http_proxy` takes an
+origin-only `target` (scheme + host, no path/query/fragment/credentials) and at
+least one `headers` entry; `attach_http_proxy` / `detach_http_proxy` point a
+proxy at a host's backing VM (the host must be `bootstrapping` or `active`).
 
 `doctor` fetches `GET /doctor` — read-only dependency health. The service
 runs one cheap, non-mutating probe per dependency (database, active VM

drukbox_python_sdk-0.0.5/PKG-INFO → drukbox_python_sdk-0.0.7/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.4
-Name: drukbox-python-sdk
-Version: 0.0.5
-Summary: Async Python client for Drukbox.
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.28
-Description-Content-Type: text/markdown
-
 # drukbox-python-sdk
 
 Async Python client for the [Drukbox] host API.
@@ -66,6 +58,7 @@ Public exports live in `drukbox_sdk`:
 - `SandboxAPI`
 - `SandboxHost`
 - `DoctorReport` and `DoctorCheck`
+- `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -75,12 +68,34 @@ Supported host operations:
 - `get_host`
 - `attach`
 - `list_hosts`
+- `renew_host`
 - `delete_host`
 - `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`provider`, and `Idempotency-Key` inputs.
+`provider`, `instance_type`, `disk_gb`, and `Idempotency-Key` inputs.
+`instance_type` (provider-native size, e.g. `t3.xlarge` / `cx33`) and `disk_gb`
+pin the VM shape; omit either for the provider default. `expires_at` mirrors the
+wire contract: omit it for the default lease, pass a datetime for an explicit
+expiry, or pass `None` for a never-reaped (permanent) host.
+
+`renew_host` extends a host's lease via `POST /hosts/{id}/renew`. Omit
+`expires_at` to extend by the service's default TTL; renewal never makes a host
+permanent.
+
+Supported HTTP-proxy operations:
+
+- `create_http_proxy`
+- `delete_http_proxy`
+- `attach_http_proxy`
+- `detach_http_proxy`
+
+HTTP proxies are account-bound exe.dev resources, not host state — deleting a
+host does not remove proxies fronting it. `create_http_proxy` takes an
+origin-only `target` (scheme + host, no path/query/fragment/credentials) and at
+least one `headers` entry; `attach_http_proxy` / `detach_http_proxy` point a
+proxy at a host's backing VM (the host must be `bootstrapping` or `active`).
 
 `doctor` fetches `GET /doctor` — read-only dependency health. The service
 runs one cheap, non-mutating probe per dependency (database, active VM

{drukbox_python_sdk-0.0.5 → drukbox_python_sdk-0.0.7}/pyproject.toml

@@ -4,9 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drukbox-python-sdk"
-version = "0.0.5"
+version = "0.0.7"
 description = "Async Python client for Drukbox."
 readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 # Tracks the lowest Python any current consumer supports. Bump only
 # when a real consumer needs a 3.12+ feature.
 requires-python = ">=3.11"
@@ -14,6 +16,11 @@ dependencies = [
     "httpx>=0.28",
 ]
 
+[project.urls]
+Homepage = "https://github.com/clawhaven/drukbox-python-sdk"
+Repository = "https://github.com/clawhaven/drukbox-python-sdk"
+Issues = "https://github.com/clawhaven/drukbox-python-sdk/issues"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/drukbox_sdk"]
 

{drukbox_python_sdk-0.0.5 → drukbox_python_sdk-0.0.7}/src/drukbox_sdk/__init__.py

@@ -7,6 +7,8 @@ detail and may change without notice.
 from .api import (
     DoctorCheck,
     DoctorReport,
+    HTTPProxy,
+    HTTPProxyAttachment,
     SandboxAPI,
     SandboxHost,
 )
@@ -18,11 +20,14 @@ from .exceptions import (
     SandboxProvisioningError,
     SandboxResponseError,
     SandboxUnavailableError,
+    SandboxValidationError,
 )
 
 __all__ = [
     "DoctorCheck",
     "DoctorReport",
+    "HTTPProxy",
+    "HTTPProxyAttachment",
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
@@ -32,4 +37,5 @@ __all__ = [
     "SandboxProvisioningError",
     "SandboxResponseError",
     "SandboxUnavailableError",
+    "SandboxValidationError",
 ]

{drukbox_python_sdk-0.0.5 → drukbox_python_sdk-0.0.7}/src/drukbox_sdk/api.py

@@ -32,7 +32,7 @@ For env-backed config use :meth:`SandboxAPI.from_env`.
 import asyncio
 import os
 import uuid
-from dataclasses import dataclass, fields
+from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Self
 
@@ -45,6 +45,7 @@ from .exceptions import (
     SandboxProvisioningError,
     SandboxResponseError,
     SandboxUnavailableError,
+    SandboxValidationError,
 )
 
 # Explicit pool budget. The httpx defaults (100 / 20) are plenty for
@@ -57,6 +58,22 @@ _SANDBOX_HTTP_LIMITS = httpx.Limits(
 )
 
 
+class _Unset:
+    """Sentinel distinguishing an omitted argument from an explicit ``None``.
+
+    ``create_host`` mirrors the service's tri-state ``expires_at``: an
+    omitted field means "default lease", an explicit ``null`` means
+    "permanent". A plain ``datetime | None`` default can't tell those two
+    apart, so the omitted case uses this sentinel.
+    """
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+_UNSET = _Unset()
+
+
 @dataclass(frozen=True)
 class SandboxHost:
     """Snapshot of a provisioned host as returned by the service.
@@ -84,6 +101,8 @@ class SandboxHost:
     status: str
     provider: str
     image: str
+    instance_type: str | None
+    disk_gb: int | None
     external_ssh_host: str
     external_ssh_port: int
     ssh_username: str
@@ -98,20 +117,6 @@ class SandboxHost:
     expires_at: str | None
 
 
-_SANDBOX_HOST_FIELDS = {field.name for field in fields(SandboxHost)}
-
-
-def _parse_sandbox_host(data: dict[str, Any]) -> SandboxHost:
-    """Build a :class:`SandboxHost` picking only known fields.
-
-    Defensive against the service adding new fields — those flow
-    through harmlessly without breaking the SDK on the unsuspecting
-    caller's side.
-    """
-
-    return SandboxHost(**{key: data[key] for key in _SANDBOX_HOST_FIELDS})
-
-
 @dataclass(frozen=True)
 class DoctorCheck:
     """One dependency probe. ``hint`` is a remediation slug, set only on failures."""
@@ -133,23 +138,30 @@ class DoctorReport:
     checks: list[DoctorCheck]
 
 
-def _parse_doctor_check(data: dict[str, Any]) -> DoctorCheck:
-    return DoctorCheck(
-        name=data["name"],
-        status=data["status"],
-        detail=data["detail"],
-        latency_ms=data["latency_ms"],
-        hint=data["hint"],
-    )
+@dataclass(frozen=True)
+class HTTPProxy:
+    """An account-bound HTTP proxy as returned by the service.
 
+    ``status`` echoes the lifecycle step the call reached
+    (``"created"``). Proxies are account resources, not host state:
+    deleting a host they front does not remove them.
+    """
 
-def _parse_doctor_report(data: dict[str, Any]) -> DoctorReport:
-    return DoctorReport(
-        ok=data["ok"],
-        active_provider=data["active_provider"],
-        tailscale_enabled=data["tailscale_enabled"],
-        checks=[_parse_doctor_check(check) for check in data["checks"]],
-    )
+    name: str
+    status: str
+
+
+@dataclass(frozen=True)
+class HTTPProxyAttachment:
+    """The result of pointing an HTTP proxy at a host's backing VM.
+
+    ``host_id`` is the string UUID of the attached host; ``status``
+    echoes the step reached (``"attached"``).
+    """
+
+    name: str
+    host_id: str
+    status: str
 
 
 class SandboxAPI:
@@ -210,10 +222,12 @@ class SandboxAPI:
     async def create_host(
         self,
         *,
+        disk_gb: int | None = None,
         env: dict[str, str] | None = None,
-        expires_at: datetime | None = None,
+        expires_at: datetime | None | _Unset = _UNSET,
         idempotency_key: str | None = None,
         image: str | None = None,
+        instance_type: str | None = None,
         provider: str | None = None,
     ) -> SandboxHost:
         """Provision a new host.
@@ -233,15 +247,32 @@ class SandboxAPI:
         ``provider`` pins which VM provider serves the request; omit it to
         use the service default. An unknown provider raises
         :class:`SandboxResponseError` (the service rejects it with 400).
+
+        ``instance_type`` (provider-native size, e.g. ``t3.xlarge`` /
+        ``cx33``) and ``disk_gb`` (root disk size) pin the VM shape; omit
+        either to use the provider's configured default. A size the active
+        provider can't serve raises :class:`SandboxResponseError` (400).
+
+        Lease (mirrors the wire contract's tri-state ``expires_at``): omit
+        it for the service's default lease, pass a ``datetime`` for an
+        explicit expiry, or pass ``None`` for a never-reaped (permanent)
+        host — exactly as an omitted field vs. an explicit ``null`` behave
+        on the API.
         """
 
         payload: dict[str, Any] = {}
+        if disk_gb is not None:
+            payload["disk_gb"] = disk_gb
         if env is not None:
             payload["env"] = env
-        if expires_at is not None:
-            payload["expires_at"] = expires_at.isoformat()
+        # Sentinel default lets us tell "caller omitted expires_at" (default
+        # lease) from "caller passed None" (explicit null → permanent host).
+        if not isinstance(expires_at, _Unset):
+            payload["expires_at"] = None if expires_at is None else expires_at.isoformat()
         if image is not None:
             payload["image"] = image
+        if instance_type is not None:
+            payload["instance_type"] = instance_type
         if provider is not None:
             payload["provider"] = provider
 
@@ -251,12 +282,12 @@ class SandboxAPI:
 
         data = await self._request("POST", "/hosts", json=payload, headers=headers)
         assert isinstance(data, dict)
-        return _parse_sandbox_host(data)
+        return SandboxHost(**data)
 
     async def get_host(self, host_id: uuid.UUID | str) -> SandboxHost:
         data = await self._request("GET", f"/hosts/{host_id}")
         assert isinstance(data, dict)
-        return _parse_sandbox_host(data)
+        return SandboxHost(**data)
 
     async def attach(self, host_id: uuid.UUID | str) -> SandboxHost:
         """Alias for :meth:`get_host` that reads better at call sites
@@ -273,7 +304,31 @@ class SandboxAPI:
     async def list_hosts(self) -> list[SandboxHost]:
         data = await self._request("GET", "/hosts")
         assert isinstance(data, list)
-        return [_parse_sandbox_host(item) for item in data]
+        return [SandboxHost(**item) for item in data]
+
+    async def renew_host(
+        self,
+        host_id: uuid.UUID | str,
+        *,
+        expires_at: datetime | None = None,
+    ) -> SandboxHost:
+        """Extend a host's lease and return the updated record.
+
+        Omit ``expires_at`` to extend by the service's default TTL from
+        now; pass one to set an explicit future expiry. Renewal never
+        makes a host permanent — that is a create-time choice.
+
+        Raises :class:`SandboxNotFoundError` for an unknown host and
+        :class:`SandboxConflictError` when the host is in a non-renewable
+        state (still provisioning, errored, or an unclaimed pool host).
+        """
+
+        payload: dict[str, Any] = {}
+        if expires_at is not None:
+            payload["expires_at"] = expires_at.isoformat()
+        data = await self._request("POST", f"/hosts/{host_id}/renew", json=payload)
+        assert isinstance(data, dict)
+        return SandboxHost(**data)
 
     async def delete_host(self, host_id: uuid.UUID | str) -> None:
         await self._request("DELETE", f"/hosts/{host_id}")
@@ -287,7 +342,65 @@ class SandboxAPI:
 
         data = await self._request("GET", "/doctor")
         assert isinstance(data, dict)
-        return _parse_doctor_report(data)
+        return DoctorReport(
+            ok=data["ok"],
+            active_provider=data["active_provider"],
+            tailscale_enabled=data["tailscale_enabled"],
+            checks=[DoctorCheck(**check) for check in data["checks"]],
+        )
+
+    # ------------------------------------------------------------------
+    # HTTP proxies
+    # ------------------------------------------------------------------
+
+    async def create_http_proxy(
+        self,
+        *,
+        name: str,
+        target: str,
+        headers: dict[str, str],
+    ) -> HTTPProxy:
+        """Create an account-bound HTTP proxy in front of ``target``.
+
+        ``target`` must be an origin-only URL (scheme + host, no path,
+        query, fragment, or credentials); ``headers`` must carry at least
+        one entry. The service rejects a malformed target or empty headers
+        with :class:`SandboxValidationError`; a name that already exists
+        raises :class:`SandboxConflictError`.
+        """
+
+        payload: dict[str, Any] = {"name": name, "target": target, "headers": headers}
+        data = await self._request("POST", "/http-proxies", json=payload)
+        assert isinstance(data, dict)
+        return HTTPProxy(**data)
+
+    async def delete_http_proxy(self, name: str) -> None:
+        """Delete an HTTP proxy by name. Unknown name raises
+        :class:`SandboxNotFoundError`."""
+
+        await self._request("DELETE", f"/http-proxies/{name}")
+
+    async def attach_http_proxy(
+        self,
+        name: str,
+        host_id: uuid.UUID | str,
+    ) -> HTTPProxyAttachment:
+        """Point proxy ``name`` at ``host_id``'s backing VM.
+
+        The host must have a backing VM (``bootstrapping`` or ``active``);
+        otherwise the service raises :class:`SandboxConflictError`. An
+        unknown host or proxy raises :class:`SandboxNotFoundError`.
+        """
+
+        data = await self._request("POST", f"/http-proxies/{name}/hosts/{host_id}")
+        assert isinstance(data, dict)
+        return HTTPProxyAttachment(**data)
+
+    async def detach_http_proxy(self, name: str, host_id: uuid.UUID | str) -> None:
+        """Detach proxy ``name`` from ``host_id``. Unknown host or proxy
+        raises :class:`SandboxNotFoundError`."""
+
+        await self._request("DELETE", f"/http-proxies/{name}/hosts/{host_id}")
 
     async def aclose(self) -> None:
         if self._client is None:
@@ -350,6 +463,14 @@ class SandboxAPI:
         if response.status_code == 503:
             raise SandboxUnavailableError(json_response.get("detail", "service unavailable"))
 
+        if response.status_code == 422:
+            # FastAPI's 422 detail is a list of error dicts; join the messages
+            # so it reads as a line, not a raw list repr.
+            detail = json_response.get("detail", "validation error")
+            if isinstance(detail, list):
+                detail = "; ".join(item.get("msg", "") for item in detail) or "validation error"
+            raise SandboxValidationError(detail)
+
         if response.status_code >= 400:
             raise SandboxResponseError(json_response.get("detail", "error"))
         return json_response

{drukbox_python_sdk-0.0.5 → drukbox_python_sdk-0.0.7}/src/drukbox_sdk/exceptions.py

@@ -50,5 +50,14 @@ class SandboxProvisioningError(SandboxAPIError):
     """
 
 
+class SandboxValidationError(SandboxAPIError):
+    """422 — the service rejected the request payload as invalid.
+
+    e.g. an env key that isn't a valid environment-variable name, or a
+    proxy target URL carrying a path or credentials. The request is
+    malformed, so retrying it unchanged won't help — fix the input.
+    """
+
+
 class SandboxResponseError(SandboxAPIError):
     """Everything else the service returned that the SDK doesn't classify."""

{drukbox_python_sdk-0.0.5 → drukbox_python_sdk-0.0.7}/tests/test_api.py

@@ -23,6 +23,8 @@ import respx
 
 from drukbox_sdk import (
     DoctorReport,
+    HTTPProxy,
+    HTTPProxyAttachment,
     SandboxAPI,
     SandboxAuthError,
     SandboxConflictError,
@@ -31,6 +33,7 @@ from drukbox_sdk import (
     SandboxProvisioningError,
     SandboxResponseError,
     SandboxUnavailableError,
+    SandboxValidationError,
 )
 
 BASE_URL = "https://sandbox.test"
@@ -80,6 +83,8 @@ def _host_payload(**overrides: Any) -> dict[str, Any]:
         "status": "provisioning",
         "provider": "exe",
         "image": "ghcr.io/drukbox/sandbox:test",
+        "instance_type": None,
+        "disk_gb": None,
         "external_ssh_host": "203.0.113.42",
         "external_ssh_port": 22,
         "ssh_username": "exedev",
@@ -165,9 +170,44 @@ async def test_create_host_omits_image_and_env_when_unset(api: SandboxAPI):
     assert "env" not in body
     assert "expires_at" not in body
     assert "provider" not in body
+    assert "instance_type" not in body
+    assert "disk_gb" not in body
     assert "Idempotency-Key" not in route.calls.last.request.headers
 
 
+@respx.mock
+async def test_create_host_none_expires_at_sends_explicit_null(api: SandboxAPI):
+    """Mirroring the wire contract: an explicit ``expires_at=None`` asks for
+    a permanent (never-reaped) host and must serialize as
+    ``"expires_at":null`` — distinct from omitting it (default lease),
+    covered by test_create_host_omits_image_and_env_when_unset."""
+
+    payload = _host_payload(expires_at=None)
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    await api.create_host(expires_at=None)
+
+    assert '"expires_at":null' in route.calls.last.request.content.decode()
+
+
+@respx.mock
+async def test_create_host_sends_sizing_when_set(api: SandboxAPI):
+    payload = _host_payload(instance_type="t3.xlarge", disk_gb=100)
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    host = await api.create_host(instance_type="t3.xlarge", disk_gb=100)
+
+    body = route.calls.last.request.content.decode()
+    assert '"instance_type":"t3.xlarge"' in body
+    assert '"disk_gb":100' in body
+    assert host.instance_type == "t3.xlarge"
+    assert host.disk_gb == 100
+
+
 @respx.mock
 async def test_create_host_sends_provider_when_set(api: SandboxAPI):
     payload = _host_payload(provider="hetzner")
@@ -231,25 +271,55 @@ async def test_delete_host_swallows_204(api: SandboxAPI):
     await api.delete_host(host_id)
 
 
-# ---------------------------------------------------------------------------
-# Forwards compatibility — service adds fields
-# ---------------------------------------------------------------------------
+@respx.mock
+async def test_renew_host_posts_expires_at_and_returns_host(api: SandboxAPI):
+    expires_at = datetime(2026, 7, 1, 12, 0, tzinfo=UTC)
+    payload = _host_payload(status="active", expires_at=expires_at.isoformat())
+    route = respx.post(f"{BASE_URL}/hosts/{payload['id']}/renew").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    host = await api.renew_host(payload["id"], expires_at=expires_at)
+
+    assert f'"expires_at":"{expires_at.isoformat()}"' in route.calls.last.request.content.decode()
+    assert host.expires_at == payload["expires_at"]
 
 
 @respx.mock
-async def test_unknown_fields_in_host_payload_are_ignored(api: SandboxAPI):
-    """If the service ships a new field tomorrow, today's SDK must not
-    break. The host parser picks known fields only."""
+async def test_renew_host_omits_expires_at_when_unset(api: SandboxAPI):
+    """Omitted expires_at means "extend by the default TTL"; the SDK must
+    send an empty body, not an explicit null."""
 
-    payload = _host_payload(future_field="surprise", another_one=42)
-    respx.get(f"{BASE_URL}/hosts/{payload['id']}").mock(
+    payload = _host_payload(status="active")
+    route = respx.post(f"{BASE_URL}/hosts/{payload['id']}/renew").mock(
         return_value=httpx.Response(200, json=payload),
     )
 
-    host = await api.get_host(payload["id"])
+    await api.renew_host(payload["id"])
 
-    assert host.id == payload["id"]  # Old fields still parsed.
-    assert not hasattr(host, "future_field")  # New field silently dropped.
+    assert "expires_at" not in route.calls.last.request.content.decode()
+
+
+@respx.mock
+async def test_renew_host_404_raises_not_found(api: SandboxAPI):
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/hosts/{host_id}/renew").mock(
+        return_value=httpx.Response(404, json={"detail": "host not found"}),
+    )
+
+    with pytest.raises(SandboxNotFoundError, match="host not found"):
+        await api.renew_host(host_id)
+
+
+@respx.mock
+async def test_renew_host_409_when_not_renewable(api: SandboxAPI):
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/hosts/{host_id}/renew").mock(
+        return_value=httpx.Response(409, json={"detail": "cannot renew a host in status error"}),
+    )
+
+    with pytest.raises(SandboxConflictError, match="cannot renew"):
+        await api.renew_host(host_id)
 
 
 @respx.mock
@@ -333,6 +403,28 @@ async def test_409_raises_sandbox_conflict_error(api: SandboxAPI):
         await api.delete_host(host_id)
 
 
+@respx.mock
+async def test_422_raises_sandbox_validation_error(api: SandboxAPI):
+    # FastAPI's 422 detail is a list of error dicts; the SDK flattens it to a
+    # readable line and raises the dedicated validation error (don't-retry).
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            422,
+            json={
+                "detail": [
+                    {
+                        "loc": ["body", "env"],
+                        "msg": "env keys must be valid environment variable names: FOO BAR",
+                    }
+                ]
+            },
+        ),
+    )
+
+    with pytest.raises(SandboxValidationError, match="env keys must be valid"):
+        await api.create_host(env={"FOO BAR": "x"})
+
+
 @respx.mock
 async def test_500_raises_sandbox_response_error(api: SandboxAPI):
     respx.get(f"{BASE_URL}/hosts").mock(
@@ -560,36 +652,121 @@ async def test_doctor_surfaces_failure_with_hint(api: SandboxAPI):
 
 
 @respx.mock
-async def test_doctor_ignores_unknown_check_fields(api: SandboxAPI):
-    """A future service adding a field to a check must not break today's SDK."""
+async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
+    """Doctor is service-token only; a bad token raises like every other call."""
 
-    payload = _doctor_payload(
-        checks=[
-            {
-                "name": "db",
-                "status": "ok",
-                "detail": "select 1 -> 1",
-                "latency_ms": 2,
-                "hint": None,
-                "future_field": "surprise",
-            },
-        ],
+    respx.get(f"{BASE_URL}/doctor").mock(
+        return_value=httpx.Response(401, json={"detail": "service token required"}),
     )
-    respx.get(f"{BASE_URL}/doctor").mock(return_value=httpx.Response(200, json=payload))
 
-    report = await api.doctor()
+    with pytest.raises(SandboxAuthError, match="service token required"):
+        await api.doctor()
+
 
-    assert report.checks[0].name == "db"
-    assert not hasattr(report.checks[0], "future_field")
+# ---------------------------------------------------------------------------
+# HTTP proxies
+# ---------------------------------------------------------------------------
 
 
 @respx.mock
-async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
-    """Doctor is service-token only; a bad token raises like every other call."""
+async def test_create_http_proxy_posts_payload_and_returns_record(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(201, json={"name": "gh", "status": "created"}),
+    )
 
-    respx.get(f"{BASE_URL}/doctor").mock(
-        return_value=httpx.Response(401, json={"detail": "service token required"}),
+    proxy = await api.create_http_proxy(
+        name="gh",
+        target="https://api.github.com",
+        headers={"Authorization": "Bearer x"},
     )
 
-    with pytest.raises(SandboxAuthError, match="service token required"):
-        await api.doctor()
+    body = route.calls.last.request.content.decode()
+    assert route.calls.last.request.headers["Authorization"] == "Bearer t-test"
+    assert '"name":"gh"' in body
+    assert '"target":"https://api.github.com"' in body
+    assert '"headers":{"Authorization":"Bearer x"}' in body
+    assert proxy == HTTPProxy(name="gh", status="created")
+
+
+@respx.mock
+async def test_create_http_proxy_409_raises_conflict(api: SandboxAPI):
+    respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(409, json={"detail": "http proxy already exists"}),
+    )
+
+    with pytest.raises(SandboxConflictError, match="already exists"):
+        await api.create_http_proxy(name="gh", target="https://api.github.com", headers={"X": "y"})
+
+
+@respx.mock
+async def test_create_http_proxy_422_raises_validation(api: SandboxAPI):
+    """A target carrying a path is rejected server-side; the SDK surfaces
+    it as the don't-retry validation error."""
+
+    respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(
+            422,
+            json={"detail": [{"msg": "target URL must not contain a path"}]},
+        ),
+    )
+
+    with pytest.raises(SandboxValidationError, match="must not contain a path"):
+        await api.create_http_proxy(
+            name="gh", target="https://api.github.com/v3", headers={"X": "y"}
+        )
+
+
+@respx.mock
+async def test_delete_http_proxy_swallows_204(api: SandboxAPI):
+    respx.delete(f"{BASE_URL}/http-proxies/gh").mock(return_value=httpx.Response(204))
+
+    await api.delete_http_proxy("gh")
+
+
+@respx.mock
+async def test_delete_http_proxy_404_raises_not_found(api: SandboxAPI):
+    respx.delete(f"{BASE_URL}/http-proxies/gh").mock(
+        return_value=httpx.Response(404, json={"detail": "http proxy not found"}),
+    )
+
+    with pytest.raises(SandboxNotFoundError, match="not found"):
+        await api.delete_http_proxy("gh")
+
+
+@respx.mock
+async def test_attach_http_proxy_returns_attachment(api: SandboxAPI):
+    host_id = uuid4()
+    route = respx.post(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(
+            200, json={"name": "gh", "host_id": str(host_id), "status": "attached"}
+        ),
+    )
+
+    attachment = await api.attach_http_proxy("gh", host_id)
+
+    assert route.called
+    assert attachment == HTTPProxyAttachment(name="gh", host_id=str(host_id), status="attached")
+
+
+@respx.mock
+async def test_attach_http_proxy_409_when_host_has_no_vm(api: SandboxAPI):
+    """Attaching to a host that isn't bootstrapping/active is a state
+    conflict, not a validation error."""
+
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(409, json={"detail": "host does not have a backing VM"}),
+    )
+
+    with pytest.raises(SandboxConflictError, match="backing VM"):
+        await api.attach_http_proxy("gh", host_id)
+
+
+@respx.mock
+async def test_detach_http_proxy_swallows_204(api: SandboxAPI):
+    host_id = uuid4()
+    respx.delete(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(204),
+    )
+
+    await api.detach_http_proxy("gh", host_id)