boxd 0.2.19.dev910__tar.gz → 0.2.20.dev929__tar.gz

{boxd-0.2.19.dev910/src/boxd.egg-info → boxd-0.2.20.dev929}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.19.dev910
+Version: 0.2.20.dev929
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT
@@ -119,6 +119,12 @@ The first of these that is present wins:
 If your key is revoked mid-session, the SDK fails fast with
 `AuthenticationError` rather than retrying.
 
+`AuthenticationError` means only that no credential was found or boxd refused
+it; its `.reason` says which (`"missing_credentials"`, `"invalid_api_key"`,
+`"invalid_token"`). Failing to reach boxd is an `APIConnectionError`, an
+account that can't use the API a `PermissionDeniedError`, and an error answer
+from the key exchange an `APIStatusError` with its `.http_status`.
+
 The exchange endpoint is **rate-limited per source IP** (30 requests / 60s). A
 session token is valid for one hour, so a fleet of workers behind one NAT
 should **mint one token and share it** (`Boxd(token=...)`) rather than each
@@ -142,6 +148,9 @@ One limit: inside a **shared** machine the automatic credential can manage the
 organization's shared machines, but cannot read environment variables or
 secrets, and cannot reach private machines. Pass an API key for those.
 
+An **isolated** machine has no automatic credential: `Boxd()` raises
+`AuthenticationError` there, so pass an API key.
+
 ## Sync and async
 
 `Boxd` and `AsyncBoxd` are the same surface — same namespaces, same method
@@ -205,7 +214,7 @@ boxd.machines.create(
     disk="100G",
     auto_suspend_timeout=300,     # seconds; 0 disables
     auto_destroy_timeout=0,
-    ssh=True,                     # give the machine an SSH port
+    ssh=True,                     # False: SSH off, nothing answers on its port
     proxies=[ProxyEntry(name="api", port=3000)],
     volumes=[VolumeMount(disk_id="d_...", mount_path="/data", read_only=False)],
 )
@@ -239,6 +248,7 @@ boxd.machines.unshare(id)
 boxd.machines.set_auto_suspend_timeout(id, 300) # seconds idle; 0 disables
 boxd.machines.set_auto_hibernate_timeout(id, 0)
 boxd.machines.set_idle_ignore_outbound(id, True) # only inbound connections keep it awake
+boxd.machines.set_ssh(id, False)                # nothing answers SSH; exec still works
 boxd.machines.wait_until_ready(id)
 boxd.machines.wait_until_ready(id, timeout=180.0, poll_interval=1.0)   # seconds
 boxd.machines.suggest_name()
@@ -247,6 +257,14 @@ boxd.machines.suggest_name()
 A fork inherits the source's sizing for anything you leave unset, and is
 private to you unless you pass `shared=True`.
 
+With SSH off (`ssh=False` on create, or `set_ssh(id, False)`), nothing
+answers SSH on the machine's port, on the public address or the org's
+network, and SSH sessions already open to it are closed. The port stays
+allocated, so turning SSH back on keeps the address. `exec`, `boxd connect`
+and the console terminal don't use SSH and keep working. A fork or a restore
+keeps its source's setting unless you pass `ssh`. `set_ssh` can't be called
+from inside the machine itself.
+
 `create` and `fork` return once the machine is scheduled, not once it is
 usable. Call `wait_until_ready` before doing anything that depends on it
 running — especially before forking it again.
@@ -536,6 +554,7 @@ A machine can be limited to what it may reach on the internet:
 ```python
 boxd.machines.set_egress_allow("alpha", ["api.stripe.com", "*.github.com", "203.0.113.0/24"])
 boxd.machines.get("alpha").egress_allow
+boxd.machines.set_egress_allow("alpha", ["none"])   # nothing is reachable
 boxd.machines.set_egress_allow("alpha", [])   # clear: unrestricted again
 ```
 
@@ -545,7 +564,9 @@ becomes `xn--bcher-kva.de`), which is what the machine looks up. Web
 requests are admitted by hostname, everything else by address, with the
 addresses of allowlisted names learned as the machine resolves them. Nothing
 that is not named is reachable. The hosts of any bound secret the machine
-holds are always admitted. Takes effect within a second. From inside the
+holds are always admitted. `"none"` on its own leaves the allowlist on with
+nothing in it, so the machine reaches only those; next to other entries it is
+dropped. Takes effect within a second. From inside the
 machine it can be read (`boxd machine egress`) but not changed. A fork inherits its source's allowlist; a
 machine restored from a snapshot starts unrestricted, unless its machine spec
 lists `egress`.
@@ -613,6 +634,7 @@ machine.shared                  # shared with that org, or private to you
 machine.access.ssh_port         # int | None — None until allocated
 machine.access.domain
 machine.access.url              # https://<name>.<domain>
+machine.ssh                     # bool — False: SSH is off, nothing answers on ssh_port
 
 machine.idle.suspend_after      # seconds; 0 = that timer is disabled
 machine.idle.hibernate_after
@@ -763,6 +785,47 @@ relative to the VM user's home directory (`/home/boxd`) — a bare filename
 like `"notes.txt"` resolves to `/home/boxd/notes.txt`, same as `"./notes.txt"`
 or `"sub/notes.txt"` would.
 
+### Filesystem
+
+`machines.fs` works on a machine's files the way code works on local ones: as
+the machine's user, seeing the same files its commands do, with failures
+raised as the builtin `OSError`s.
+
+```python
+fs = boxd.machines.fs
+
+fs.write(id, "/app/config.json", '{"debug": true}')     # creates missing parents
+fs.write(id, "big.bin", chunks)                          # or stream an iterable of bytes
+data = fs.read(id, "/app/config.json")                   # bytes
+for chunk in fs.read_stream(id, "big.bin"): ...          # without holding it all
+
+entry = fs.stat(id, "/app")          # FsEntry: name, path, type, size, mode, mtime, ...
+entry.is_dir, entry.is_symlink
+fs.list(id, "/app")                  # one level, every entry
+fs.exists(id, "/app/missing")        # False
+fs.mkdir(id, "/app/a/b")             # mkdir -p
+fs.rename(id, "/app/a", "/app/c")
+fs.remove(id, "/app/c", recursive=True)
+fs.realpath(id, "/app/link")
+
+try:
+    fs.read(id, "/app/nope")
+except FileNotFoundError:
+    ...
+```
+
+A write replaces the file all at once, so readers see the old contents or the
+new, never a mix; only a file that can't be swapped by a rename (several hard
+links, another user's file, a mount point) is overwritten in place. It writes
+through a symlink to its target, and an existing file keeps its mode and owner
+(or takes `mode=`). Only regular files can be read. Paths are `str`, `bytes` or
+`os.PathLike`; a relative path starts in the user's home directory, and names
+that aren't valid UTF-8 round-trip. Errors are
+`MachineFilesystemError` subclasses that are also `FileNotFoundError`,
+`PermissionError`, `FileExistsError`, `IsADirectoryError` or
+`NotADirectoryError`, with `errno` and `filename` set. A machine started before
+`machines.fs` existed raises `MachineAgentOutdatedError` until it is rebooted.
+
 ### Ports and proxies
 
 ```python
@@ -1182,9 +1245,14 @@ except NotFoundError:
 
 Every error carries `.message`, `.code` (the canonical status name, e.g.
 `"not_found"`) and `.grpc_code`, the numeric
-[status code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html).
-
-Connection failures are retried with exponential backoff, `max_retries` times.
+[status code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html). Some
+also carry `.reason`, a name for the exact failure (`"invalid_api_key"`,
+`"is_a_directory"`, ...), and errors from the key exchange carry
+`.http_status`. `machines.fs` errors are also `OSError`s (see
+[Filesystem](#filesystem)).
+
+Connection failures are retried with exponential backoff, `max_retries` times,
+including failing to reach the key exchange or a machine's automatic credential.
 Timeouts are never retried — the server may already have applied the request —
 and neither is `AuthenticationError`.
 

{boxd-0.2.19.dev910 → boxd-0.2.20.dev929}/README.md

@@ -84,6 +84,12 @@ The first of these that is present wins:
 If your key is revoked mid-session, the SDK fails fast with
 `AuthenticationError` rather than retrying.
 
+`AuthenticationError` means only that no credential was found or boxd refused
+it; its `.reason` says which (`"missing_credentials"`, `"invalid_api_key"`,
+`"invalid_token"`). Failing to reach boxd is an `APIConnectionError`, an
+account that can't use the API a `PermissionDeniedError`, and an error answer
+from the key exchange an `APIStatusError` with its `.http_status`.
+
 The exchange endpoint is **rate-limited per source IP** (30 requests / 60s). A
 session token is valid for one hour, so a fleet of workers behind one NAT
 should **mint one token and share it** (`Boxd(token=...)`) rather than each
@@ -107,6 +113,9 @@ One limit: inside a **shared** machine the automatic credential can manage the
 organization's shared machines, but cannot read environment variables or
 secrets, and cannot reach private machines. Pass an API key for those.
 
+An **isolated** machine has no automatic credential: `Boxd()` raises
+`AuthenticationError` there, so pass an API key.
+
 ## Sync and async
 
 `Boxd` and `AsyncBoxd` are the same surface — same namespaces, same method
@@ -170,7 +179,7 @@ boxd.machines.create(
     disk="100G",
     auto_suspend_timeout=300,     # seconds; 0 disables
     auto_destroy_timeout=0,
-    ssh=True,                     # give the machine an SSH port
+    ssh=True,                     # False: SSH off, nothing answers on its port
     proxies=[ProxyEntry(name="api", port=3000)],
     volumes=[VolumeMount(disk_id="d_...", mount_path="/data", read_only=False)],
 )
@@ -204,6 +213,7 @@ boxd.machines.unshare(id)
 boxd.machines.set_auto_suspend_timeout(id, 300) # seconds idle; 0 disables
 boxd.machines.set_auto_hibernate_timeout(id, 0)
 boxd.machines.set_idle_ignore_outbound(id, True) # only inbound connections keep it awake
+boxd.machines.set_ssh(id, False)                # nothing answers SSH; exec still works
 boxd.machines.wait_until_ready(id)
 boxd.machines.wait_until_ready(id, timeout=180.0, poll_interval=1.0)   # seconds
 boxd.machines.suggest_name()
@@ -212,6 +222,14 @@ boxd.machines.suggest_name()
 A fork inherits the source's sizing for anything you leave unset, and is
 private to you unless you pass `shared=True`.
 
+With SSH off (`ssh=False` on create, or `set_ssh(id, False)`), nothing
+answers SSH on the machine's port, on the public address or the org's
+network, and SSH sessions already open to it are closed. The port stays
+allocated, so turning SSH back on keeps the address. `exec`, `boxd connect`
+and the console terminal don't use SSH and keep working. A fork or a restore
+keeps its source's setting unless you pass `ssh`. `set_ssh` can't be called
+from inside the machine itself.
+
 `create` and `fork` return once the machine is scheduled, not once it is
 usable. Call `wait_until_ready` before doing anything that depends on it
 running — especially before forking it again.
@@ -501,6 +519,7 @@ A machine can be limited to what it may reach on the internet:
 ```python
 boxd.machines.set_egress_allow("alpha", ["api.stripe.com", "*.github.com", "203.0.113.0/24"])
 boxd.machines.get("alpha").egress_allow
+boxd.machines.set_egress_allow("alpha", ["none"])   # nothing is reachable
 boxd.machines.set_egress_allow("alpha", [])   # clear: unrestricted again
 ```
 
@@ -510,7 +529,9 @@ becomes `xn--bcher-kva.de`), which is what the machine looks up. Web
 requests are admitted by hostname, everything else by address, with the
 addresses of allowlisted names learned as the machine resolves them. Nothing
 that is not named is reachable. The hosts of any bound secret the machine
-holds are always admitted. Takes effect within a second. From inside the
+holds are always admitted. `"none"` on its own leaves the allowlist on with
+nothing in it, so the machine reaches only those; next to other entries it is
+dropped. Takes effect within a second. From inside the
 machine it can be read (`boxd machine egress`) but not changed. A fork inherits its source's allowlist; a
 machine restored from a snapshot starts unrestricted, unless its machine spec
 lists `egress`.
@@ -578,6 +599,7 @@ machine.shared                  # shared with that org, or private to you
 machine.access.ssh_port         # int | None — None until allocated
 machine.access.domain
 machine.access.url              # https://<name>.<domain>
+machine.ssh                     # bool — False: SSH is off, nothing answers on ssh_port
 
 machine.idle.suspend_after      # seconds; 0 = that timer is disabled
 machine.idle.hibernate_after
@@ -728,6 +750,47 @@ relative to the VM user's home directory (`/home/boxd`) — a bare filename
 like `"notes.txt"` resolves to `/home/boxd/notes.txt`, same as `"./notes.txt"`
 or `"sub/notes.txt"` would.
 
+### Filesystem
+
+`machines.fs` works on a machine's files the way code works on local ones: as
+the machine's user, seeing the same files its commands do, with failures
+raised as the builtin `OSError`s.
+
+```python
+fs = boxd.machines.fs
+
+fs.write(id, "/app/config.json", '{"debug": true}')     # creates missing parents
+fs.write(id, "big.bin", chunks)                          # or stream an iterable of bytes
+data = fs.read(id, "/app/config.json")                   # bytes
+for chunk in fs.read_stream(id, "big.bin"): ...          # without holding it all
+
+entry = fs.stat(id, "/app")          # FsEntry: name, path, type, size, mode, mtime, ...
+entry.is_dir, entry.is_symlink
+fs.list(id, "/app")                  # one level, every entry
+fs.exists(id, "/app/missing")        # False
+fs.mkdir(id, "/app/a/b")             # mkdir -p
+fs.rename(id, "/app/a", "/app/c")
+fs.remove(id, "/app/c", recursive=True)
+fs.realpath(id, "/app/link")
+
+try:
+    fs.read(id, "/app/nope")
+except FileNotFoundError:
+    ...
+```
+
+A write replaces the file all at once, so readers see the old contents or the
+new, never a mix; only a file that can't be swapped by a rename (several hard
+links, another user's file, a mount point) is overwritten in place. It writes
+through a symlink to its target, and an existing file keeps its mode and owner
+(or takes `mode=`). Only regular files can be read. Paths are `str`, `bytes` or
+`os.PathLike`; a relative path starts in the user's home directory, and names
+that aren't valid UTF-8 round-trip. Errors are
+`MachineFilesystemError` subclasses that are also `FileNotFoundError`,
+`PermissionError`, `FileExistsError`, `IsADirectoryError` or
+`NotADirectoryError`, with `errno` and `filename` set. A machine started before
+`machines.fs` existed raises `MachineAgentOutdatedError` until it is rebooted.
+
 ### Ports and proxies
 
 ```python
@@ -1147,9 +1210,14 @@ except NotFoundError:
 
 Every error carries `.message`, `.code` (the canonical status name, e.g.
 `"not_found"`) and `.grpc_code`, the numeric
-[status code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html).
-
-Connection failures are retried with exponential backoff, `max_retries` times.
+[status code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html). Some
+also carry `.reason`, a name for the exact failure (`"invalid_api_key"`,
+`"is_a_directory"`, ...), and errors from the key exchange carry
+`.http_status`. `machines.fs` errors are also `OSError`s (see
+[Filesystem](#filesystem)).
+
+Connection failures are retried with exponential backoff, `max_retries` times,
+including failing to reach the key exchange or a machine's automatic credential.
 Timeouts are never retried — the server may already have applied the request —
 and neither is `AuthenticationError`.
 

{boxd-0.2.19.dev910 → boxd-0.2.20.dev929}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.2.19.dev910"
+version = "0.2.20.dev929"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"
@@ -69,6 +69,10 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+# PEP 561: ship the marker so type checkers read the inline annotations.
+[tool.setuptools.package-data]
+boxd = ["py.typed"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"

{boxd-0.2.19.dev910 → boxd-0.2.20.dev929}/src/boxd/__init__.py

@@ -26,6 +26,13 @@ from .errors import (
     AuthenticationError,
     BoxdError,
     ConflictError,
+    MachineAgentOutdatedError,
+    MachineFileExistsError,
+    MachineFileNotFoundError,
+    MachineFilesystemError,
+    MachineIsADirectoryError,
+    MachineNotADirectoryError,
+    MachinePermissionError,
     NotFoundError,
     PermissionDeniedError,
     RateLimitError,
@@ -51,6 +58,8 @@ from .models import (
     DiskAttachment,
     DiskStatus,
     EnvVar,
+    FsEntry,
+    FsEntryType,
     ExecResult,
     SelfDeleteResult,
     ExposedPort,
@@ -161,6 +170,8 @@ __all__ = [
     "DiskStatus",
     "EnvVar",
     "ExecResult",
+    "FsEntry",
+    "FsEntryType",
     "SelfDeleteResult",
     "ExposedPort",
     "BillingActivityEntry",
@@ -235,6 +246,13 @@ __all__ = [
     "AuthenticationError",
     "BoxdError",
     "ConflictError",
+    "MachineAgentOutdatedError",
+    "MachineFileExistsError",
+    "MachineFileNotFoundError",
+    "MachineFilesystemError",
+    "MachineIsADirectoryError",
+    "MachineNotADirectoryError",
+    "MachinePermissionError",
     "NotFoundError",
     "PermissionDeniedError",
     "RateLimitError",

{boxd-0.2.19.dev910 → boxd-0.2.20.dev929}/src/boxd/_credentials.py

@@ -10,7 +10,7 @@ Resolution order, first match wins:
 2. explicit ``api_key``         — exchanged for a JWT
 3. ``BOXD_TOKEN``, then ``BOXD_API_KEY`` — same handling
 4. in-VM metadata adapter       — no credentials required
-5. otherwise :class:`AuthenticationError`
+5. otherwise :class:`AuthenticationError` (reason ``"missing_credentials"``)
 
 Steps 4 and 5 need I/O, so the decision lands on the first request rather than
 in ``__init__``: constructing a client never blocks on a network probe.
@@ -26,7 +26,13 @@ from typing import Any
 
 import httpx
 
-from .errors import AuthenticationError, RateLimitError
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    PermissionDeniedError,
+    RateLimitError,
+)
 
 # The in-VM metadata adapter listens on the VM's default gateway.
 METADATA_PORT = 9002
@@ -48,6 +54,15 @@ _NO_CREDENTIALS = (
     "no credentials: pass api_key= or token=, set BOXD_API_KEY / BOXD_TOKEN, "
     "or run inside a boxd VM"
 )
+# The environment says "machine" and there is a gateway, but nothing answered
+# on it. An isolated machine looks exactly like this (it keeps the hints but
+# has no metadata adapter), and so does an adapter outage: there is no telling
+# them apart from here, so this stays terminal and says what to do instead.
+_ADAPTER_SILENT = (
+    "no credentials: the machine's metadata adapter at {url} did not answer "
+    "(isolated machines have none); pass api_key= or token=, or set "
+    "BOXD_API_KEY / BOXD_TOKEN"
+)
 
 
 # ── In-VM detection ──────────────────────────────────────────────────
@@ -116,61 +131,123 @@ async def probe_async(host: str, port: int, timeout: float = _PROBE_TIMEOUT_SECS
     return True
 
 
-def metadata_base(not_inside: str = _NO_CREDENTIALS) -> str:
-    """The in-VM metadata adapter's base URL, or ``AuthenticationError(not_inside)``
-    when this code is not running inside a boxd machine. Detection needs BOTH
-    signals, the environment hint and a live probe — neither alone is
-    sufficient."""
+def _missing(message: str) -> AuthenticationError:
+    return AuthenticationError(
+        message, code="unauthenticated", reason="missing_credentials"
+    )
+
+
+def metadata_base(
+    not_inside: str = _NO_CREDENTIALS, silent: str = _ADAPTER_SILENT
+) -> str:
+    """The in-VM metadata adapter's base URL, or ``AuthenticationError``
+    (reason ``"missing_credentials"``) when there is none to use. Detection
+    needs BOTH signals, the environment hint and a live probe — neither alone
+    is sufficient.
+
+    The message is ``not_inside`` when this doesn't look like a machine, and
+    ``silent`` (formatted with ``url``) when it does but the adapter didn't
+    answer. Nothing is cached: the next call probes again."""
     if not looks_like_a_machine():
-        raise AuthenticationError(not_inside)
+        raise _missing(not_inside)
     gateway = detect_gateway()
-    if not gateway or not probe(gateway, METADATA_PORT):
-        raise AuthenticationError(not_inside)
-    return f"http://{gateway}:{METADATA_PORT}"
+    if not gateway:
+        raise _missing(not_inside)
+    base = f"http://{gateway}:{METADATA_PORT}"
+    if not probe(gateway, METADATA_PORT):
+        raise _missing(silent.format(url=base))
+    return base
 
 
-async def metadata_base_async(not_inside: str = _NO_CREDENTIALS) -> str:
+async def metadata_base_async(
+    not_inside: str = _NO_CREDENTIALS, silent: str = _ADAPTER_SILENT
+) -> str:
     """Async twin of :func:`metadata_base`."""
     if not looks_like_a_machine():
-        raise AuthenticationError(not_inside)
+        raise _missing(not_inside)
     gateway = detect_gateway()
-    if not gateway or not await probe_async(gateway, METADATA_PORT):
-        raise AuthenticationError(not_inside)
-    return f"http://{gateway}:{METADATA_PORT}"
+    if not gateway:
+        raise _missing(not_inside)
+    base = f"http://{gateway}:{METADATA_PORT}"
+    if not await probe_async(gateway, METADATA_PORT):
+        raise _missing(silent.format(url=base))
+    return base
 
 
 # ── Response parsing (shared by both clients) ────────────────────────
 
 
 def parse_exchange(status_code: int, body: str, json: Any) -> tuple[str, float]:
-    """Validate an API-key exchange response → ``(token, expires_at)``."""
+    """Validate an API-key exchange response → ``(token, expires_at)``.
+
+    Only a 401 means the key itself was refused. An account that can't use
+    the API is a 403; anything else the exchange answers is its own failure,
+    not the key's.
+    """
     if status_code == 401:
-        raise AuthenticationError("invalid or expired API key")
+        raise AuthenticationError(
+            "invalid or expired API key",
+            code="unauthenticated",
+            reason="invalid_api_key",
+            http_status=status_code,
+        )
     if status_code == 429:
         raise RateLimitError(
             "token exchange rate limit exceeded"
             + (f": {body}" if body else "")
-            + " — a token is valid for 1 hour; reuse one across your workers"
+            + " — a token is valid for 1 hour; reuse one across your workers",
+            code="resource_exhausted",
+            http_status=status_code,
+        )
+    if status_code == 403:
+        raise PermissionDeniedError(
+            f"API key refused: {body}" if body else "API key refused",
+            code="permission_denied",
+            http_status=status_code,
         )
     if status_code != 200:
-        raise AuthenticationError(f"exchange failed: {status_code} {body}")
+        raise APIStatusError(
+            f"exchange failed: {status_code} {body}", http_status=status_code
+        )
     try:
         return str(json["token"]), float(json["expires_at"])
     except (TypeError, KeyError, ValueError) as e:
-        raise AuthenticationError(f"malformed exchange response: {body}") from e
+        raise APIStatusError(
+            f"malformed exchange response: {body}", http_status=status_code
+        ) from e
 
 
 def parse_vm_token(status_code: int, body: str, json: Any) -> tuple[str, float, str | None]:
-    """Validate a metadata-adapter token response → ``(token, expires_at, api_url)``."""
+    """Validate a metadata-adapter token response → ``(token, expires_at, api_url)``.
+
+    The adapter authenticates the machine by where the request comes from, so
+    it has no "wrong credential" answer: a 403 is a refusal (e.g. a disabled
+    account), anything else is the adapter's own failure.
+    """
+    if status_code == 403:
+        raise PermissionDeniedError(
+            f"in-VM token request refused: {body}",
+            code="permission_denied",
+            http_status=status_code,
+        )
+    if status_code == 429:
+        raise RateLimitError(
+            f"in-VM token request rate limited: {body}",
+            code="resource_exhausted",
+            http_status=status_code,
+        )
     if status_code != 200:
-        raise AuthenticationError(
-            f"in-VM token request failed: {status_code} {body}"
+        raise APIStatusError(
+            f"in-VM token request failed: {status_code} {body}",
+            http_status=status_code,
         )
     try:
         token = str(json["token"])
         expires_at = float(json["expires_at"])
     except (TypeError, KeyError, ValueError) as e:
-        raise AuthenticationError(f"malformed in-VM token response: {body}") from e
+        raise APIStatusError(
+            f"malformed in-VM token response: {body}", http_status=status_code
+        ) from e
     # The VM reports its own cluster, which is what lets an unconfigured
     # `Boxd()` work identically on dev, staging, metal and prod.
     api_url = json.get("api_url") or None
@@ -250,7 +327,7 @@ class SyncCredentials(_CredentialsBase):
                         self._exchange_url, json={"api_key": self._api_key}
                     )
             except httpx.HTTPError as e:
-                raise AuthenticationError(
+                raise APIConnectionError(
                     f"could not reach {self._exchange_url}: {e}"
                 ) from e
             # The exchange endpoint is rate-limited per source IP; a NATed fleet
@@ -269,7 +346,9 @@ class SyncCredentials(_CredentialsBase):
             with httpx.Client(timeout=_HTTP_TIMEOUT_SECS) as client:
                 resp = client.get(base + METADATA_TOKEN_PATH)
         except httpx.HTTPError as e:
-            raise AuthenticationError(f"in-VM token request failed: {e}") from e
+            raise APIConnectionError(
+                f"could not reach the in-VM metadata adapter: {e}"
+            ) from e
         token, expires_at, api_url = parse_vm_token(
             resp.status_code, resp.text, _json_or_none(resp)
         )
@@ -307,7 +386,7 @@ class AsyncCredentials(_CredentialsBase):
                         self._exchange_url, json={"api_key": self._api_key}
                     )
             except httpx.HTTPError as e:
-                raise AuthenticationError(
+                raise APIConnectionError(
                     f"could not reach {self._exchange_url}: {e}"
                 ) from e
             # The exchange endpoint is rate-limited per source IP; a NATed fleet
@@ -328,7 +407,9 @@ class AsyncCredentials(_CredentialsBase):
                     base + METADATA_TOKEN_PATH
                 )
         except httpx.HTTPError as e:
-            raise AuthenticationError(f"in-VM token request failed: {e}") from e
+            raise APIConnectionError(
+                f"could not reach the in-VM metadata adapter: {e}"
+            ) from e
         token, expires_at, api_url = parse_vm_token(
             resp.status_code, resp.text, _json_or_none(resp)
         )