Installation

Choose the right path

Most users should install the packaged app from the stable update channel. Developers working on Ambient Desktop itself should build from source when they need local code changes, debug symbols, or platform-specific packaging validation.

The current stable channel is version 0.1.96. Prefer versioned URLs when documenting a reproducible setup and latest aliases when a user simply wants the newest stable artifact.

Packaged install: macOS

macOS is the most straightforward packaged path today. The DMG is the recommended install artifact for Apple Silicon machines.

1. Download the DMG

   Use the latest DMG for normal use or the versioned 0.1.96 DMG when reproducing a specific release.

2. Open the disk image and drag Ambient Desktop into Applications

   Launch from Applications rather than directly from the mounted disk image so user data, updates, and OS permissions behave normally.

3. Approve normal macOS prompts

   The app may request access needed for local development workflows such as files, terminal sessions, browser automation, or notifications. Grant only the permissions required for the workflow you are testing.

4. Verify first launch

   Open Settings and confirm provider configuration, local runtime status, browser capability status, and plugin/capability health checks before running high-impact tasks.

Packaged install: Windows

Windows packaging is active and published on the stable channel. The important difference is trust UX: until Windows signing and reputation are fully established, users may see SmartScreen, Windows Defender Firewall, or installer reputation prompts.

Treat those prompts as part of the installation documentation, not as an unexpected failure. Developers validating Windows should record which prompt appeared, which artifact was used, and whether the installed app launched from a normal user path.

1. Download the x64 installer

   Use the latest or versioned NSIS installer from the stable channel. Keep the ZIP for artifact inspection or manual unpack testing.

2. Handle SmartScreen or reputation warnings deliberately

   If Windows reports that the app is unrecognized, verify the artifact URL and SHA-256 first. Only proceed when the artifact matches the published stable manifest.

3. Install for the current user

   Accept the installer prompts and launch Ambient Desktop from the Start Menu or desktop shortcut rather than directly from a temporary downloads directory.

4. Review firewall prompts

   Local runtime servers, browser bridges, or model hosting may trigger Windows Defender Firewall prompts. Allow only the network scopes required by the workflow; most local runtime flows should stay on localhost.

5. Run first-launch checks

   Confirm the app opens, Settings loads, terminal/runtime checks run, and any Windows-specific blocked capabilities are clearly labeled rather than silently failing.

Packaged install: Linux

Linux supports a portable AppImage and a Debian package. Use the AppImage when you want minimal system mutation; use the deb when you want a desktop-integrated install on Debian or Ubuntu style systems.

chmod +x 'Ambient Desktop-0.1.96-linux-x86_64.AppImage'
./'Ambient Desktop-0.1.96-linux-x86_64.AppImage'

sudo apt install ./Ambient\ Desktop-0.1.96-linux-amd64.deb

Build from source

Source builds are for Ambient contributors and platform validation. Install Git, Node.js, and pnpm first, then clone the repository and build. Build each platform's artifacts on that platform so Electron native modules and signing behave correctly. Builds are unsigned unless signing credentials exist in your environment.

Each block below is self-contained — copy it, paste it into your terminal, and you have the source cloned, dependencies installed, and either a dev session or a packaged build.

git clone https://github.com/ambient-xyz/AmbientDesktop.git
cd AmbientDesktop
pnpm install
pnpm run dev          # run in development
pnpm run dist:mac     # build the macOS app (DMG + ZIP)

git clone https://github.com/ambient-xyz/AmbientDesktop.git
cd AmbientDesktop
pnpm install
pnpm run dev          # run in development
pnpm run dist:win     # build the Windows installer (NSIS + ZIP)

git clone https://github.com/ambient-xyz/AmbientDesktop.git
cd AmbientDesktop
pnpm install
pnpm run dev          # run in development
pnpm run dist:linux   # build the AppImage + .deb

pnpm run test:packaged
pnpm run verify:packaged-native

Post-install verification

• Confirm the installed version and update channel.
• Open Settings and verify provider configuration, local runtime status, browser capability status, and plugin/capability diagnostics.
• Install curated defaults only after descriptor, runtime, permission profile, and source provenance are visible.
• Run a low-risk coding or documentation task first, then inspect the plan, artifacts, browser evidence, and Git summary before allowing broader automation.
• Use Ambient-managed secret flows for provider keys and account integrations. Do not paste credentials into chat or documentation artifacts.

Installation FAQ