The public installer looks up Apple silicon (aarch64-darwin) releases. This
runbook is the source-home staging path for local Mac verification, Browser VM
artifacts, and .dmg packaging work.
Install the host tools first:
xcode-select --install
brew install node e2fsprogs coturn ffmpeg
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup target add wasm32-unknown-unknownSource-home requires an owner-only directory containing regular, owner-only
ffmpeg and ffprobe executables. The build/setup wrapper copies the selected
host tools into a private temporary directory inside the selected home and
checks that the copies run. It preserves Homebrew permissions and removes the
temporary copies on exit. Homebrew libraries remain dependencies of these tools.
Ordinary Home setup fetches the signed media-tools package and imports its
managed executable pair. The host tool instructions above apply to source-home
development.
Then get the repo and build/install the source-home runtime into an isolated
Mac test home. Replace upstream/RELEASE-dev below with the development ref
named in the owning GitHub issue:
mkdir -p "$HOME/Code"
git clone --branch upstream/RELEASE-dev https://github.com/elastos/elastos-runtime.git "$HOME/Code/elastos-runtime"
cd "$HOME/Code/elastos-runtime"
export MAC_TEST_HOME="$HOME/elastos-mac-test-home"
export USER_HOME="$HOME"
export SETUP_SOURCE_HOME_MEDIA_TOOLS_DIR="$(dirname "$(command -v ffmpeg)")"
export ELASTOS_NODE_BIN="$(command -v node)"
export ELASTOS_BROWSER_VM_TURNSERVER_BIN="$(command -v turnserver)"
HOME="$MAC_TEST_HOME" \
CARGO_HOME="$USER_HOME/.cargo" \
RUSTUP_HOME="$USER_HOME/.rustup" \
PATH="$USER_HOME/.cargo/bin:/opt/homebrew/bin:$PATH" \
ELASTOS_COLLABORATION_STARTUP_MODE=isolated \
scripts/build-and-setup-source-home.shsetup-source-home.sh builds the runtime server, native providers,
WASM Components, runtime-projection browser assets, Browser helper
scripts, Browser source-home provider config, the macOS Browser VZ supervisor,
and the local Kubo backend used by Library and Documents publish. It installs
the stable Runtime under the source-home data root at bin/elastos, writes the
owner-only receipts/source-home-installation.json receipt, and signs the
installed VZ supervisor on macOS.
The wrapper defaults to isolated collaboration and leaves Runtime startup as
a separate step. It disables Browser TURN startup during setup. To check only
the media tools before a build, run
scripts/build-and-setup-source-home.sh --check-tools.
For Home/passkey use without Browser VM proof artifacts, start the stable installed gateway through the restart helper:
scripts/mac-source-home-restart.sh \
--test-home "$MAC_TEST_HOME" \
--addr localhost:61180
curl -fsS http://localhost:61180/api/health
open http://localhost:61180/apps/home/On first launch, Home shows Set up Home. Enter a passkey name, choose
Create admin passkey, and complete the macOS passkey prompt. The first
passkey becomes the Home admin. Later launches show Sign in / Use passkey.
Use http://localhost:61180/apps/home/; do not switch the visible origin to
127.0.0.1, because passkey RP/origin state is bound to the browser origin.
The Browser capsule is VM-backed on Mac. A clean Browser setup needs these artifacts in the source-home data dir before Browser VM proof can be claimed:
$MAC_TEST_HOME/Library/Application Support/elastos/bin/vmlinux
$MAC_TEST_HOME/Library/Application Support/elastos/bin/initrd
$MAC_TEST_HOME/Library/Application Support/elastos/browser-vm/rootfs.ext4
$MAC_TEST_HOME/Library/Application Support/elastos/browser-vm/browser-vm-rootfs-manifest.json
These are Linux guest artifacts. Build them on a Linux/CI/operator machine with
scripts/build/build-browser-vm-rootfs.sh, or install a reviewed prebuilt
artifact set. After copying them into the paths above, rerun:
HOME="$MAC_TEST_HOME" \
CARGO_HOME="$USER_HOME/.cargo" \
RUSTUP_HOME="$USER_HOME/.rustup" \
PATH="$USER_HOME/.cargo/bin:/opt/homebrew/bin:$PATH" \
ELASTOS_COLLABORATION_STARTUP_MODE=isolated \
scripts/build-and-setup-source-home.sh
HOME="$MAC_TEST_HOME" scripts/browser-vm-artifact-preflight.shok=true or local_substrate_artifacts_ready=true is the artifact gate for
local Browser VM launch readiness. If the rootfs sidecar manifest is missing or
its SHA-256 does not match the rootfs image, the Browser setup is not clean.
With Browser artifacts installed, use the restart helper for normal Mac staging instead of hand-starting the gateway:
scripts/mac-source-home-restart.sh \
--test-home "$MAC_TEST_HOME" \
--addr localhost:61180Do not set HOME="$MAC_TEST_HOME" when calling
scripts/mac-source-home-restart.sh; pass --test-home or MAC_TEST_HOME
instead. The restart helper verifies Home hash parity and Browser helper
freshness across source, installed scripts, initrd, and rootfs before it starts
the gateway. By default, it writes the owner-only active receipt to the stable
data-root receipts/mac-source-home-restart.json path.
Mac Browser staging uses Apple Virtualization.framework for the Browser VM
substrate. The installed browser-vz-engine-supervisor binary must be signed
with the com.apple.security.virtualization entitlement before it can validate
or start a VM.
scripts/setup-source-home.sh signs the installed helper automatically on
macOS. To sign a rebuilt helper manually:
scripts/dev/sign-elastos-vz/sign.sh \
"$MAC_TEST_HOME/Library/Application Support/elastos/bin/browser-vz-engine-supervisor"Restart the Mac source-home gateway and verify Home hash parity plus Browser VM helper freshness with:
scripts/mac-source-home-restart.sh \
--test-home "$MAC_TEST_HOME" \
--addr localhost:61180Then collect a machine proof with:
scripts/browser-mac-vm-proof.sh --artifact-out /tmp/elastos-browser-mac-vm-proof.jsonThe handoff wrapper can do both steps for a fresh local proof:
MAC_TEST_HOME="$MAC_TEST_HOME" \
scripts/browser-mac-vm-acceptance-handoff.sh \
--restart-source-home \
--proof-out /tmp/elastos-browser-mac-vm-proof.jsonThe proof checks local Home HTTP, installed/source Home hash parity, Browser VM
control status, embedded WebRTC video/input/navigation, ela.city page
diagnostics, image loading, clean VM page shutdown, and explicit
quality_gates for remote-video readiness, navigation timing, decoded/dropped
frames, device pixel ratio, viewport size, and panel/video geometry. It
produces elastos.browser.mac-vm-proof/v1 and intentionally records
manual_acceptance.status=not_recorded; it does not replace hash-bound manual UX,
product audio, or authenticated ela.city edit-profile acceptance.
To prove a non-default Browser viewport/zoom geometry, set the expected viewport
on the proof command; the wrapper passes those dimensions through to the
virtual-auth Browser open request unless the lower-level
HOME_VIRTUAL_AUTH_BROWSER_OPEN_VIEWPORT_WIDTH/HEIGHT variables are explicitly
set:
ELASTOS_BROWSER_MAC_VM_EXPECT_VIEWPORT_WIDTH=1000 \
ELASTOS_BROWSER_MAC_VM_EXPECT_VIEWPORT_HEIGHT=700 \
scripts/browser-mac-vm-proof.sh --artifact-out /tmp/elastos-browser-mac-vm-proof-resize.jsonWhen the installed Browser VM control service has the current status contract,
the proof also records vm_control.before.started_at /
vm_control.after.started_at and uptime_ms so reviewers can bind the Browser
VM media proof to a concrete control-service run after restart. Final Mac VM
acceptance requires vm_control.restart.fresh_after_restart=true,
vm_control.after.started_at, and a positive bounded
vm_control.after.uptime_ms; older or stale machine artifacts without that
status contract remain diagnostics, not acceptance proof.
To prove cookie/localStorage/profile reset for the virtual test principal after the proof pages have closed, opt in explicitly:
ELASTOS_BROWSER_MAC_VM_PROFILE_RESET_PROOF=1 \
scripts/browser-mac-vm-proof.sh --artifact-out /tmp/elastos-browser-mac-vm-proof-reset.jsonThe reset proof uses /api/apps/browser/profile/reset, removes only the active
principal's Browser VM profile disk under the principal-owned localhost root,
refuses live Browser pages,
and returns a receipt that does not expose the profile key, principal id, or
disk path. Mac VM acceptance requires removed_profile_disk=true; a reset that
finds no principal-owned profile disk is diagnostic, not proof that cookies and
localStorage were cleared.
After logging into ela.city inside the Mac Browser VM profile, an operator can ask the proof to click sanitized authenticated controls and collect post-click diagnostics before the page is closed:
ELASTOS_BROWSER_MAC_VM_PROOF_AUTH_PROFILE="$HOME/.local/share/elastos/mac-browser-vm-proof-auth" \
HOME_VIRTUAL_AUTH_BROWSER_DIAGNOSTIC_CLICK_TEXT_RE='Profile=>Edit Profile' \
HOME_VIRTUAL_AUTH_BROWSER_DIAGNOSTIC_CLICK_EXPECT_TEXT_RE='Edit Profile' \
scripts/browser-mac-vm-proof.sh --artifact-out /tmp/elastos-browser-mac-vm-proof.jsonThe default proof uses a disposable virtual passkey principal and removes it at
the end, so it will not see ela.city cookies from a human's normal Home profile.
Set ELASTOS_BROWSER_MAC_VM_PROOF_AUTH_PROFILE to reuse one virtual-auth browser
profile and preserve the same Browser VM principal across setup and proof runs;
the profile also carries an owner-only virtual authenticator credential store so
the same passkey can sign back in after a fresh proof process. The wrapper
defaults HOME_VIRTUAL_AUTH_CLEANUP=0 in that mode unless the operator
overrides it. For first-time ela.city login setup, open a headed setup run with
the same persistent virtual-auth profile:
scripts/browser-mac-vm-auth-profile-setup.sh \
--auth-profile "$HOME/.local/share/elastos/mac-browser-vm-proof-auth" \
--receipt-out /tmp/elastos-browser-mac-vm-auth-setup.jsonSign into ela.city inside the Browser VM, let the setup close cleanly, then
rerun the proof or handoff headless with the same --auth-profile path and
pass the setup receipt with --auth-setup-receipt. The setup receipt is a
local operator artifact that records the profile path, setup URL, hold time, and
exact follow-up handoff command; the Browser machine proof still records only
whether a persistent virtual-auth profile was used, not the local profile path.
The final acceptance audit recomputes the receipt SHA-256 from that receipt path
before accepting the handoff chain, and requires the setup receipt timestamp to
be no later than the machine proof timestamp.
The click sequence matches only sanitized diagnostics such as visible text,
ARIA labels, titles, and test ids, sends Runtime-mediated Browser input, and
records post-click diagnostics for the acceptance audit. In this Mac proof, a
missing diagnostic click target is recorded in the artifact instead of aborting
the machine proof; set HOME_VIRTUAL_AUTH_BROWSER_DIAGNOSTIC_CLICK_OPTIONAL=0
when you want the authenticated click sequence itself to be strict. It is
evidence for the authenticated modal path, not a substitute for the hash-bound
manual report.
To bind Mac manual acceptance to that exact machine artifact:
scripts/browser-mac-vm-acceptance-handoff.sh \
--machine-proof /tmp/elastos-browser-mac-vm-proof.json \
--source-home-restart-receipt /tmp/elastos-mac-source-home-restart.json \
--manual-out /tmp/elastos-browser-mac-vm-manual-ux.jsonThe handoff writes a hash-bound manual UX template, an expected failing
acceptance audit without manual evidence, and a short summary of the exact gaps
left before Mac Browser acceptance. It exits non-zero until a headed auth setup receipt
and persistent proof profile are hash-bound, even when the machine proof itself
is ready. If the handoff should collect a fresh authenticated machine
proof first, omit --machine-proof, optionally add --restart-source-home so
the source-home restart receipt is generated and hash-bound automatically, and
pass --auth-profile "$HOME/.local/share/elastos/mac-browser-vm-proof-auth"
plus --auth-setup-receipt /tmp/elastos-browser-mac-vm-auth-setup.json. To
prepare a redacted operator checklist and an ok=false manual draft for review:
node scripts/browser-mac-vm-manual-review-packet.mjs \
--machine-proof /tmp/elastos-browser-mac-vm-proof.json \
--handoff-summary /tmp/elastos-browser-mac-vm-proof-handoff-summary.json \
--out-dir /tmp/elastos-browser-mac-vm-reviewThe review packet is not acceptance; the reviewer must still fill evidence and add at least one separate redacted screen recording, screenshot, or screenshot set to the manual report. To generate and validate the template manually instead:
node scripts/browser-manual-ux-report.mjs \
--template \
--machine-artifact /tmp/elastos-browser-mac-vm-proof.json \
> /tmp/elastos-browser-mac-vm-manual-ux.json
node scripts/browser-manual-ux-report.mjs \
--input /tmp/elastos-browser-mac-vm-manual-ux.jsonSet the manual report to ok=true only after reviewing the restarted Mac
gateway, visible remote video, typing/input latency, address bar stability,
scroll/click fidelity, performance and zoom gates, ela.city URL sync, visible
image settling, authenticated edit-profile modal behavior, no raw authority
exposure, and session cleanup. Add at least one redacted review_artifacts
entry for a screen recording, screenshot, or screenshot set, with
redacted=true, its local path, and SHA-256 digest, so the manual review
evidence is hash-bound.
The validator rejects shallow Mac artifacts, local review artifacts that contain
obvious raw authority text, and reports without evidence text for every Mac VM
manual check. The contract smoke is:
scripts/browser-mac-vm-manual-ux-smoke.shBefore claiming Mac Browser acceptance, run the acceptance audit against the machine proof, the completed manual report, and the handoff summary:
node scripts/browser-mac-vm-acceptance-audit.mjs \
--machine-proof /tmp/elastos-browser-mac-vm-proof.json \
--manual-ux /tmp/elastos-browser-mac-vm-manual-ux.json \
--handoff-summary /tmp/elastos-browser-mac-vm-proof-handoff-summary.jsonThe audit intentionally exits non-zero when the machine proof is good but the manual report is missing, when ela.city diagnostics still look logged out, when the in-page URL-sync click does not move to a changed URL matching the recorded expected URL regex, when there is no authenticated profile/edit-profile signal, when authenticated evidence was collected from a disposable virtual-auth profile, when the handoff summary is missing or not bound to the same machine proof, source-home restart receipt, and auth setup receipt, when either receipt digest does not match its path, when source-home Browser helper hashes do not match source/installed/initrd/rootfs, when setup/restart/proof/handoff timestamps are out of order, or when the machine proof contains raw DOM HTML or CDP event dumps. Browser page diagnostics include sanitized visible text samples and visible dialog/modal candidates so the audit does not rely on raw HTML dumps for profile or edit-profile evidence. Its contract smoke is:
scripts/browser-mac-vm-acceptance-audit-smoke.sh