@multiplayer-app/sandbox 7.0.1 → 7.0.3

package/README.md

@@ -126,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
@@ -198,6 +205,79 @@ 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.
 
+## Publishing your own AWS Lambda MicroVM images
+
+Unlike the ops commands above, this works from a plain `npm install
+@multiplayer-app/sandbox` — no monorepo checkout needed. It builds the guest
+agent for each stack (`node`/`python`/`static`) and zips it entirely in memory
+(see `src/microvm-guest-agents.ts`), then registers or updates it as an AWS
+Lambda MicroVM image in **your own AWS account**, using whatever credentials
+are already active (`AWS_PROFILE`, static env vars, an assumed role, ...).
+
+```sh
+# Discover a base OS image ARN to build on top of
+npx @multiplayer-app/sandbox images microvm-list-base --region us-east-1
+
+# Build and register/update sandbox-node, sandbox-python, sandbox-static
+npx @multiplayer-app/sandbox images microvm-create \
+  --region us-east-1 \
+  --bucket my-artifacts-bucket \
+  --base-image-arn arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1 \
+  --build-role-arn arn:aws:iam::123456789012:role/microvm-image-build
+```
+
+`--build-role-arn` is an IAM role the build assumes to read the uploaded code
+artifact from `--bucket` — trust policy allowing `lambda.amazonaws.com` to
+assume it, permissions limited to `s3:GetObject` on that bucket. It's a
+one-time setup step this command doesn't automate; see the "MicroVM base image
+build role" section below for the exact `aws iam` commands.
+
+The first run creates each image; every later run updates it in place — AWS
+records that as a new numbered version under the same stable ARN, so nothing
+else needs to change when you publish a new version. The command prints a
+ready-to-paste `MICROVM_STACK_IMAGE_ARNS` line for your worker's environment
+once every image finishes building.
+
+Lambda MicroVMs is ARM/Graviton-only today, so there's no architecture flag —
+run `--help` on either command for the rest of the options (`--stack`,
+`--min-memory-mib`, `--image-name-prefix`).
+
+### MicroVM base image build role
+
+One-time, per AWS account:
+
+```sh
+aws iam create-role --profile my-profile \
+  --role-name microvm-image-build \
+  --assume-role-policy-document '{
+    "Version": "2012-10-17",
+    "Statement": [{
+      "Effect": "Allow",
+      "Principal": { "Service": "lambda.amazonaws.com" },
+      "Action": ["sts:AssumeRole", "sts:TagSession"]
+    }]
+  }'
+
+aws iam put-role-policy --profile my-profile \
+  --role-name microvm-image-build \
+  --policy-name microvm-build-permissions \
+  --policy-document '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": "s3:GetObject",
+        "Resource": "arn:aws:s3:::my-artifacts-bucket/microvm-images/*"
+      },
+      {
+        "Effect": "Allow",
+        "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
+        "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda-microvms/sandbox-*:*"
+      }
+    ]
+  }'
+```
+
 If the build already succeeded and only the upload needs retrying, run:
 
 ```sh