@multiplayer-app/builder-worker

Worker agent that runs micro-VMs and connects to a Multiplayer sandbox control plane. It auto-detects which micro-VM engines the host can run and advertises them to the sandbox; the sandbox schedules VMs onto it and proxies traffic through a single outbound WebSocket, so the worker needs no inbound ports — it works behind NAT, on a laptop, or in your own cluster.

Supported engines (auto-detected): qemu, firecracker, lambda-microvm, fargate, remote, and mock.

Install

npm i -g @multiplayer-app/builder-worker

Requires Node.js >= 20. For the qemu engine, install QEMU (qemu-system-*); for firecracker, a Linux host with /dev/kvm.

Usage

# See which engines this host can run (and why others can't)
builder-worker detect

# Download the per-stack base images (kernel + initramfs) the local engines need
builder-worker images pull --from s3://<bucket>            # or an https:// mirror

# Start the worker and connect to your sandbox
builder-worker start \
  --worker-id my-worker-1 \
  --token <worker-token> \
  --sandbox-url https://sandbox.example.com

Every start flag has an env-var equivalent (WORKER_ID, WORKER_TOKEN, SANDBOX_URL, PORT, MAX_VMS, WORKER_REGION). Engine configuration is entirely env-driven and auto-detected — e.g. QEMU_IMAGES_DIR, MICROVM_IMAGE_ARN, FARGATE_CLUSTER, AGENT_URL. Run builder-worker <command> --help for the full list.

Docker

A prebuilt image is published for deployment; or run the CLI directly:

FROM node:20-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      qemu-system-arm qemu-system-x86 qemu-utils && rm -rf /var/lib/apt/lists/*
RUN npm i -g @multiplayer-app/builder-worker
CMD ["builder-worker", "start"]

Expose /dev/kvm (--device /dev/kvm) and set QEMU_ACCEL=kvm for hardware acceleration; otherwise it falls back to software emulation (tcg).