@multiplayer-app/sandbox 6.0.0-sandbox-docker-image.0 → 7.0.0

package/README.md

@@ -14,11 +14,22 @@ Supported engines (auto-detected): `qemu`, `firecracker`, `docker`, `docker-sand
 `WORKER_ID`, `WORKER_TOKEN`, `SANDBOX_URL`, `MAX_VMS`, `WORKER_REGION`, plus per-engine
 vars like `QEMU_IMAGES_DIR`, `DOCKER_STACK_IMAGES`, `MICROVM_IMAGE_ARN`,
 `FARGATE_CLUSTER`, `AGENT_URL` — see `src/config.ts` for the full list.
-`WORKER_TOKEN` is required. `WORKER_ID` is optional and defaults to the machine
-hostname; set it explicitly when multiple workers could report the same hostname.
+`WORKER_TOKEN` is optional for trusted self-hosted control planes and required
+for the public worker endpoint. Create one with the control plane's
+`POST /v0/sapi/api-keys` endpoint and use the returned key as `WORKER_TOKEN`.
+`WORKER_ID` is optional and
+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`; set it explicitly for local or self-hosted
-control planes.
+`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.
+
+The sandbox worker exposes probes on `SANDBOX_HEALTH_PORT` (default `3000`)
+under `API_PREFIX` (default `/v0/api`): `GET /v0/api/healthz` is its
+liveness endpoint, and `GET /v0/api/health` is its readiness endpoint.
+Readiness returns `503` until the worker connects to the control plane.
 
 ## Start a worker
 
@@ -29,17 +40,25 @@ npm install --global @multiplayer-app/sandbox
 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`.
+
 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`. Both can be overridden with environment
+`https://api.sandbox.filingramp.com/v0`. Both can be overridden with environment
 variables or flags:
 
 ```sh
 sandbox start --token <token> --worker-id worker-eu-01 \
-  --sandbox-url http://localhost:3011 --max-vms 5
+  --sandbox-url http://localhost:3011/v0 --max-vms 5
 ```
 
 ## Run as a Docker container
@@ -59,6 +78,20 @@ docker run --rm \
   multiplayer-sandbox-worker:local
 ```
 
+Published worker images default to the matching published Docker Hub guest
+images (`<repository>-node:<version>`, `-python`, and `-static`) and pull any
+that are missing before engine detection. Override `DOCKER_IMAGE_PREFIX` and
+`DOCKER_IMAGE_TAG` for another registry/version, use `DOCKER_STACK_IMAGES` for
+per-stack references, or set `DOCKER_PULL_IMAGES=false` to require local images.
+
+For QEMU and Firecracker, set `S3_BUCKET_ARTIFACTS` to the artifact bucket name
+only, for example `my-test-artifacts` (without `s3://`, a path, or a trailing
+slash). The worker derives `<version>/qemu` (`local/qemu` in development). On
+startup the worker downloads
+`<arch>/<stack>/{vmlinuz,initramfs.img}` into `VM_IMAGES_DIR` before detecting
+engines. AWS SDK workload credentials are used automatically. Set the optional
+`S3_ARTIFACTS_ENDPOINT` only for an S3-compatible service such as MinIO.
+
 To let the worker launch ordinary Docker executors, mount the host daemon:
 
 ```sh
@@ -144,6 +177,30 @@ RUNNERS="qemu docker" ARCH=x86_64 STACKS="node python" \
 
 The underlying script lives at `libs/sandbox/scripts/build-base-images.sh`.
 
+For local development, build only the non-Docker VM artifacts and upload them
+to the Compose MinIO bucket with:
+
+```sh
+npm run publish:base-images:local
+```
+
+This builds QEMU, Firecracker, and Lambda MicroVM artifacts for the host
+architecture under `libs/sandbox/dist-base-images`, then runs a short-lived
+MinIO client container to mirror them to `s3://builder-base-images/local/`.
+It connects to the already-running MinIO host port at
+`http://host.docker.internal:9000`, so it does not start another Compose stack.
+Override `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, or
+`MINIO_BUCKET` when needed. After a successful upload it restarts an active PM2
+sandbox worker, or otherwise restarts/starts the Compose sandbox service;
+`VM_IMAGES_REFRESH=true` makes that worker replace its cached QEMU/Firecracker
+images from MinIO before advertising its engines.
+
+If the build already succeeded and only the upload needs retrying, run:
+
+```sh
+npm run upload:base-images:local
+```
+
 The default output is `libs/sandbox/dist-base-images/<runner>/<arch>/<stack>/` with a
 root `SHA256SUMS` file. QEMU and Firecracker entries contain `vmlinuz` and
 `initramfs.img`, while Lambda MicroVM entries contain `app.zip`. Docker, Docker