🚀 Installation Guide

AMBA is distributed as a self-contained desktop application for macOS, Windows, and Linux.

---

🍏 macOS Installation

1. Download the Disk Image (.dmg)

Download the latest macOS package from the Download Portal:

• Apple Silicon (M1/M2/M3/M4): Recommended for all modern Macs (MacBook Air/Pro 2020 and newer).
• Intel x64: For older Intel-based Macs.

2. Install to Applications

1. Double-click the downloaded .dmg file.
2. In the installer window, drag the AMBA icon into the Applications folder shortcut.
3. Eject the disk image from Finder.

3. First Launch & macOS Gatekeeper

Because AMBA is currently in pilot distribution, macOS Gatekeeper may show an alert on first open stating that the developer cannot be verified:

Bypassing macOS Gatekeeper for Pilot Builds

1. Open Finder and navigate to your Applications folder.
2. Right-click (or Control-click) on the AMBA icon and select Open.
3. In the dialog that appears, click Open again to confirm.
4. You only need to do this once. Subsequent launches can be done normally from Launchpad, Spotlight, or the Dock.

---

🪟 Windows Installation

1. Download the Installer

Download the latest 64-bit Windows installer (.exe or .msi) from the Download Portal.

2. Run the Setup Wizard

1. Double-click the installer file to run it.
2. If Windows SmartScreen displays "Windows protected your PC":
   • Click More info.
   • Click Run anyway.
3. Follow the installation steps to complete setup. A desktop shortcut will be created automatically.

---

🐧 Linux Installation

AMBA supports modern Linux distributions via native Debian packages (.deb) and standalone .AppImage bundles.

1. Debian / Ubuntu Installation (.deb)

1. Download the latest .deb package (AMBA_<version>_amd64.deb) from the Download Portal.
2. Install the package; apt pulls in the runtime libraries it depends on:

   sudo apt-get update
   sudo apt install ./AMBA_*_amd64.deb

   The package recommends gnome-keyring (or KWallet on KDE), which AMBA needs to save API keys. If you install with --no-install-recommends or run a minimal desktop, install one yourself: sudo apt install gnome-keyring.

2. Standalone AppImage (Fedora / Arch / RHEL / Any Distribution)

1. Download the .AppImage package (AMBA_<version>_amd64.AppImage) from the Download Portal.
2. Ensure runtime dependencies are installed:
   • Debian / Ubuntu: sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1 gnome-keyring
   • Fedora / RHEL: sudo dnf install webkit2gtk4.1 gnome-keyring
   • Arch Linux: sudo pacman -S webkit2gtk-4.1 gnome-keyring
3. Grant execution permission and launch:

   chmod +x AMBA_*_amd64.AppImage
   ./AMBA_*_amd64.AppImage

3. API Key Storage on Linux (Keyring Required)

AMBA saves API keys and connector credentials only in a Secret Service keyring over D-Bus. There is no plaintext or database fallback.

• GNOME, KDE Plasma, XFCE, Cinnamon: GNOME Keyring or KWallet (5.97 or later) normally runs already.
• Minimal window managers (i3, sway, bspwm, Hyprland) or KeePassXC: start a Secret Service provider in your session, for example gnome-keyring-daemon --start --components=secrets, or enable Secret Service integration in KeePassXC.
• No keyring running: AMBA still starts, but saving a key fails with "No system keychain is available…" and Settings → System Diagnostics shows the keychain as unavailable. Install or enable GNOME Keyring or KWallet, then restart AMBA.
• Upgrading from 0.5.8 or earlier: keys stored by older versions move into the keyring on first launch. Without a keyring they stay in the local database until one is available.

---

🔄 Automatic Updates

AMBA features a built-in, over-the-air auto-updater. When a new version is released:

• A non-intrusive notification badge appears in the bottom status bar.
• You can inspect the release notes and update in-place with a single click.
• Every release is verified using Minisign Ed25519 digital signatures before installation.