@multiplayer-app/sandbox 7.0.0 → 7.0.2

package/README.md

@@ -21,10 +21,12 @@ for the public worker endpoint. Create one with the control plane's
 defaults to the machine hostname; set it explicitly when multiple workers could
 report the same hostname.
 `SANDBOX_URL` is optional and defaults to
-`https://api.sandbox.filingramp.com/v0`; set it explicitly for local or
-self-hosted control planes. Its pathname selects the API base: `/v0` uses the
-public authenticated worker endpoint, while `/internal/v0` uses the private
-tokenless endpoint.
+`https://api.sandbox.filingramp.com/v0/gapi`; set it explicitly for local or
+self-hosted control planes. Its pathname is the sole source of the worker
+socket path — `/workers/ws` is appended to it verbatim, so the full base
+(including the `/gapi` segment) must be included: `/v0/gapi` selects the
+public authenticated worker endpoint, while `/internal/v0/gapi` selects the
+private tokenless endpoint.
 
 The sandbox worker exposes probes on `SANDBOX_HEALTH_PORT` (default `3000`)
 under `API_PREFIX` (default `/v0/api`): `GET /v0/api/healthz` is its
@@ -42,23 +44,24 @@ WORKER_TOKEN=<token> sandbox start
 
 For a trusted deployment on the same Kubernetes cluster or private Docker
 Compose network, leave `WORKER_TOKEN` unset and set
-`SANDBOX_URL=http://builder-api-service:3000/internal/v0`. This resolves to
-`/internal/v0/sapi/workers/ws`, which does not require a token and must not be
-exposed by the public ingress. A client URL such as
-`https://api.sandbox.filingramp.com/v0` resolves to `/v0/sapi/workers/ws`, which
-requires a valid, user-created API key as `WORKER_TOKEN`.
+`SANDBOX_URL=http://builder-gateway-service:3000/internal/v0/gapi`. This
+resolves to `/internal/v0/gapi/workers/ws`, which does not require a token and
+must not be exposed by the public ingress. A client URL such as
+`https://api.sandbox.filingramp.com/v0/gapi` resolves to
+`/v0/gapi/workers/ws`, which requires a valid, user-created API key as
+`WORKER_TOKEN`.
 
 The published runtime bundles the repository's internal `builder-types` and
 `logger` libraries, so installing the CLI does not require those workspace
 packages to be published separately.
 
 The worker ID defaults to the hostname and the control-plane URL defaults to
-`https://api.sandbox.filingramp.com/v0`. Both can be overridden with environment
+`https://api.sandbox.filingramp.com/v0/gapi`. Both can be overridden with environment
 variables or flags:
 
 ```sh
 sandbox start --token <token> --worker-id worker-eu-01 \
-  --sandbox-url http://localhost:3011/v0 --max-vms 5
+  --sandbox-url http://localhost:3011/v0/gapi --max-vms 5
 ```
 
 ## Run as a Docker container
@@ -123,6 +126,13 @@ Firecracker requires a compatible Linux host, `/dev/kvm`, and the Firecracker
 binary. Cloud runners use the normal AWS environment variables or workload
 credentials.
 
+Lambda MicroVMs automatically receive the AWS-managed `SHELL_INGRESS` connector so
+`/vm-console` can open a terminal. The worker role therefore needs
+`lambda:CreateMicrovmShellAuthToken` and permission to pass that connector. Any
+`MICROVM_INGRESS_CONNECTORS` configured for application traffic are preserved. Release
+artifacts and custom per-VM environment variables travel in the unique run-hook payload;
+the guest exposes the presigned release URL to the launched app as `APP_URL`.
+
 For the `qemu` engine, the host needs QEMU (`qemu-system-*`) installed; for
 `firecracker`, a Linux host with `/dev/kvm`; for `docker`, just a running Docker
 daemon (Docker Desktop/OrbStack) plus local images from