refactor(sandbox): host URLs, local grants and the trust CA read ON_THIS_MACHINE, so a VM provider on this machine needs no core edits

[earakely-scale]

A sandbox provider whose sandboxes run on this machine, but in VMs rather than on this machine's Docker, currently needs four edits outside its own module to work with the local stores: host_url_for and the local object store's grants_reach are keyed on the provider's type name, start_trusting copies the local CA into the agent container with docker cp on this machine, and the local grant server listens only where this machine's containers reach it. #157 (the SmolVM provider) had to make all four. This lets such a provider keep its changes in its module, by having core read what the provider declares.

What changes

• SandboxProvider.REACHES_HOST_AT, a declaration beside ON_THIS_MACHINE: for a provider on this machine, where a request from its sandboxes to this machine's names arrives. None for containers on this machine's Docker (the address host.docker.internal maps to); a loopback address for a VM here whose networking forwards this machine's names to it.
• on_this_machine_provider(sandbox_type), next to reachable_url: the registered class for a type when its sandboxes run on this machine, else None, including for an unknown type or one whose extra isn't installed here.
• host_url_for rewrites loopback to host.docker.internal for any provider on this machine, not only local; a type it can't resolve leaves the URL as it is, as before.
• LocalFilesystemObjectStore.grants_reach reads the declaration instead of a type-name constant: grants reach a sandbox on this machine when the server listens where its requests arrive and the grant URL names this machine by a name the sandbox resolves. A loopback literal or localhost in the URL reaches nothing, since inside any sandbox that is the sandbox itself; a VM here reaches only its declared loopback address, served by default or when bound there, and no address by number. Containers on this machine's Docker keep today's behaviour.
• VmSandbox.copy_trust_dir_into_container: start_trusting installs the local CA through the sandbox, writing the files into the VM and docker cp-ing there, where the container is. LocalSandbox keeps the direct copy, since its shell would rewrite the path.
• The local grant server also binds loopback, on the same port, when it binds the platform default (the Docker bridge gateway on Linux), where a VM on this machine arrives; an explicit grant_bind_host is served as given. Five attempts cover losing the port to another process between the two binds.

The last two are lifted from #157 with their author's credit; the SmolVM PR can then drop its host_url_for and grants_reach cases, its LOCAL_NAMES and SAN-list additions, and its core hook, and declare REACHES_HOST_AT = "127.0.0.1".

Verified

Unit suite 7627 passed / 16 skipped (a gateway time-trigger test, untouched here, failed once under parallel load and passes alone); plugin API check vs main: no break (REACHES_HOST_AT is an addition); uv lock --check clean. The declaration-driven paths are pinned with config-registered test providers: a VM-here provider gets the host rewrite and reaches grants at the default and loopback bind hosts but not at a bridge address or by an address in the URL; built-in providers all declare no REACHES_HOST_AT; start_trusting on a VM sandbox never runs Docker on this machine. The loopback-bind test binds a second loopback address and so runs on Linux only. The VM-side behaviour was also exercised live on a SmolVM on an Apple Silicon Mac against this tree's predecessor: the CA files landed in the container through the sandbox and the container fetched a grant as issued.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issue remains.

Summary

The PR lets providers declare how sandboxes on this machine reach local services.

• On-machine sandbox providers use the host URL rewrite without type-name cases.
• Local grants reach VMs through the host address they declare.
• VM sandboxes copy local CA files into containers through the VM.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Provider["Provider declarations"] --> Rewrite["Rewrite host URLs"]
  Provider --> Reach["Check whether grants reach the sandbox"]
  Reach --> Server["Grant server on configured addresses"]
  CA["Local CA files"] --> Sandbox["Sandbox copies trust files"]
  Sandbox --> Docker["Docker on the sandbox's host"]

Loading

_{Reviews (4) · Last reviewed commit: "refactor(store): the grant server takes ..." · Reviewed by Greptile}