diff --git a/.github/workflows/demo-multiarch-build.yml b/.github/workflows/demo-multiarch-build.yml
new file mode 100644
index 000000000..4e1fac3ee
--- /dev/null
+++ b/.github/workflows/demo-multiarch-build.yml
@@ -0,0 +1,83 @@
+name: Demo multi-arch images
+
+# Standalone workflow: triggered by demo directory changes or manual dispatch, builds and pushes
+# linux/amd64 and linux/arm64 multi-arch images for the docker/demo compose setup.
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'docker/demo/**'
+      - '.github/workflows/demo-multiarch-build.yml'
+
+jobs:
+  build-and-push:
+    # Run only in upstream repository, skip on forks without credentials
+    if: ${{ github.repository == 'web3infra-foundation/mega' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        include:
+          # mono backend
+          - name: mono-engine
+            dockerfile: docker/mono-engine-dockerfile
+            image_tag: mono-0.1.0-pre-release
+          # mega UI
+          - name: mega-ui
+            dockerfile: docker/mono-ui-dockerfile
+            image_tag: mega-ui-demo-0.1.0-pre-release
+          # orion server
+          - name: orion-server
+            dockerfile: orion-server/Dockerfile
+            image_tag: orion-server-0.1.0-pre-release
+          # orion client image (build worker)
+          - name: orion-client-image
+            dockerfile: docker/dev-image/Dockerfile
+            image_tag: orion-client-0.1.0-pre-release
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU (multi-arch emulation)
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          install: true
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Login to Amazon ECR Public
+        id: login-ecr-public
+        uses: aws-actions/amazon-ecr-login@v2
+        with:
+          registry-type: public
+
+      - name: Build & push ${{ matrix.name }} (amd64+arm64)
+        env:
+          REGISTRY: ${{ steps.login-ecr-public.outputs.registry }}
+          REGISTRY_ALIAS: m8q5m4u3
+          REPOSITORY: mega
+          IMAGE_TAG: ${{ matrix.image_tag }}
+          DOCKERFILE_PATH: ${{ matrix.dockerfile }}
+        run: |
+          IMAGE_BASE="$REGISTRY/$REGISTRY_ALIAS/$REPOSITORY"
+
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --builder default \
+            --file "$DOCKERFILE_PATH" \
+            --tag "$IMAGE_BASE:$IMAGE_TAG" \
+            --push \
+            --build-arg BUILDKIT_INLINE_CACHE=1 \
+            --cache-from type=gha,scope=mega-demo \
+            --cache-to type=gha,scope=mega-demo,mode=max \
+            .
+
diff --git a/docker/demo/.env.example b/docker/demo/.env.example
index 0b49b0cb6..9bb753327 100644
--- a/docker/demo/.env.example
+++ b/docker/demo/.env.example
@@ -54,7 +54,7 @@ S3_REGION=us-east-1
 MEGA_ENGINE_IMAGE=public.ecr.aws/m8q5m4u3/mega:mono-0.1.0-pre-release
 MEGA_UI_IMAGE=public.ecr.aws/m8q5m4u3/mega:mega-ui-demo-0.1.0-pre-release
 ORION_SERVER_IMAGE=public.ecr.aws/m8q5m4u3/mega:orion-server-0.1.0-pre-release
-MEGA_DEV_IMAGE=public.ecr.aws/m8q5m4u3/mega:mega-dev-0.1.0-pre-release
+MEGA_DEV_IMAGE=public.ecr.aws/m8q5m4u3/mega:orion-client-0.1.0-pre-release
 CAMPSITE_API_IMAGE=public.ecr.aws/m8q5m4u3/mega:campsite-0.1.0-pre-release
 
 # ----------------------------------------------------------------------------
diff --git a/docker/demo/docker-compose.demo.yml b/docker/demo/docker-compose.demo.yml
index 6500d32e4..baae3eeaa 100644
--- a/docker/demo/docker-compose.demo.yml
+++ b/docker/demo/docker-compose.demo.yml
@@ -236,10 +236,10 @@ services:
     restart: unless-stopped
 
   # ---------------------------------------------------------------------------
-  # Orion Build Client / Worker (based on mega-dev image)
+  # Orion Build Client / Worker (based on orion-client image)
   # ---------------------------------------------------------------------------
   orion_build_client:
-    image: ${MEGA_DEV_IMAGE:-public.ecr.aws/m8q5m4u3/mega:mega-dev-0.1.0-pre-release}
+    image: ${ORION_CLIENT_IMAGE:-public.ecr.aws/m8q5m4u3/mega:orion-client-0.1.0-pre-release}
     container_name: mega-demo-orion-worker
     command: orion
     # privileged mode allows nested container builds (Scorpio) inside the worker.
diff --git a/docker/dev-image/docker-compose.yml b/docker/dev-image/docker-compose.yml
index 42708a9bf..b4dfd6920 100644
--- a/docker/dev-image/docker-compose.yml
+++ b/docker/dev-image/docker-compose.yml
@@ -21,7 +21,7 @@ services:
   # Scorpio - FUSE Filesystem Service (daemon)
   # ---------------------------------------------------------------------------
   scorpio:
-    image: ${MEGA_DEV_IMAGE:-mega-dev:latest}
+    image: ${ORION_CLIENT_IMAGE:-orion-client:latest}
     container_name: mega-scorpio
     command: scorpio
     profiles:
@@ -52,7 +52,7 @@ services:
   # The worker can run without an Orion Server, but it will keep retrying the
   # WebSocket connection and won't execute builds until tasks are assigned.
   orion-worker:
-    image: ${MEGA_DEV_IMAGE:-mega-dev:latest}
+    image: ${ORION_CLIENT_IMAGE:-orion-client:latest}
     container_name: mega-orion-worker
     command: orion
     profiles:
@@ -83,7 +83,7 @@ services:
   # Development Shell - Tooling Only
   # ---------------------------------------------------------------------------
   dev:
-    image: ${MEGA_DEV_IMAGE:-mega-dev:dev}
+    image: ${ORION_CLIENT_IMAGE:-orion-client:dev}
     container_name: mega-dev-shell
     profiles:
       - dev
diff --git a/docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md b/docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md
index 8bbb50ae1..decfc087f 100644
--- a/docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md
+++ b/docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md
@@ -13,6 +13,17 @@
 
 ---
 
+## Apple Silicon (macOS M1/M2) Quick note
+
+This demo ships **multi-architecture Docker images** (linux/amd64 + linux/arm64). If you are on an Apple Silicon machine:
+
+1. Ensure you are running **Docker Desktop ≥ 4.22** (includes Compose v2 and built-in Rosetta/QEMU).
+2. Simply follow the normal steps—Docker will automatically pull the arm64 layers from the public registry.
+3. If the arm64 variant is not yet available (e.g. you are on a fresh fork), trigger the GitHub workflow **“Demo multi-arch images”**: `Actions → Demo multi-arch images → Run workflow`.
+4. As a fall-back you can force emulation by adding `--platform linux/amd64` after every `docker compose` command, but native arm64 images are strongly recommended.
+
+---
+
 ## Prerequisites
 
 ### System Requirements
@@ -82,7 +93,7 @@ The main configurable environment variables include:
 - **Service Images**:
   - `MEGA_ENGINE_IMAGE`: Mega backend image (default: `public.ecr.aws/m8q5m4u3/mega:mono-0.1.0-pre-release`)
   - `MEGA_UI_IMAGE`: Mega UI image (default: `public.ecr.aws/m8q5m4u3/mega:mega-ui-demo-0.1.0-pre-release`)
-  - `MEGA_DEV_IMAGE`: Orion Build Client image (default: `public.ecr.aws/m8q5m4u3/mega:mega-dev-0.1.0-pre-release`)
+  - `ORION_CLIENT_IMAGE`: Orion Build Client image (default: `public.ecr.aws/m8q5m4u3/mega:orion-client-0.1.0-pre-release`)
   - `CAMPSITE_API_IMAGE`: Campsite API image (default: `public.ecr.aws/m8q5m4u3/mega:campsite-0.1.0-pre-release`)
   - `CAMPSITE_RUN_MIGRATIONS`: Whether to run database migrations when the container starts; `1` (default) to run, can be changed to `0` after the first successful migration to skip and speed up subsequent starts.
 
@@ -494,7 +505,7 @@ The demo environment includes the following services:
   - `mega`: Mega backend (Rust)
   - `mega_ui`: Mega Web UI (Next.js)
   - `orion_server`: Orion build server (Rust)
-  - `orion_build_client`: Orion build client (based on the mega-dev image)
+  - `orion_build_client`: Orion build client (based on the orion-client image)
   - `campsite_api`: Campsite API (Ruby/Rails, built locally by default; if you have the encrypted development credentials configured you can pull the pre-built image directly via `CAMPSITE_API_IMAGE=public.ecr.aws/m8q5m4u3/mega:campsite-0.1.0-pre-release`)
 
 For a detailed architecture diagram and dependency list, see the [Mega / Orion Demo architecture design document](./mega-orion-demo-compose-arch.md).