Getting Started

Desktop App

The desktop app runs the same local server and studio as the npm package, in its own window with a menu bar or tray icon. It ships for macOS on Apple Silicon (signed and notarized by Apple), Windows and Linux. Every installer is attached to the newest ima2 Desktop release on the desktop releases page, and the site's download section picks the right one for your machine.

macOS

  1. Download ima2-<version>-mac-arm64.dmg.
  2. Open the DMG and drag ima2 into Applications.
  3. Launch ima2. The window shows the local server starting, then opens the studio.
Windows and Linux. These installers ship starting with the first desktop release that includes them. If the latest release only lists a DMG, they are not out yet; the download section shows them as Coming soon until then.

Windows

  1. Download ima2-<version>-win-x64.exe (or -win-arm64.exe on ARM devices).
  2. Run the installer. You can pick the install folder; administrator rights are not needed.
  3. If SmartScreen shows Windows protected your PC, choose More info → Run anyway for an installer downloaded from the release page.

Linux

  1. AppImage: download ima2-<version>-linux-x86_64.AppImage (or -linux-arm64.AppImage), then run chmod +x ima2-*.AppImage and start it.
  2. Debian / Ubuntu: download ima2-<version>-linux-amd64.deb (or -linux-arm64.deb) and run sudo apt install ./ima2-*.deb.

On first launch, pick a provider on the welcome screen. ChatGPT is the simplest: a browser sign-in, no API key.

Checksums. Each release attaches SHA256SUMS.txt. Compare it with shasum -a 256 <file> on macOS/Linux or Get-FileHash <file> in PowerShell.

Requirements

  • macOS on Apple Silicon, Windows 10/11 (x64 or ARM64), or a 64-bit Linux desktop (x64 or ARM64).
  • On an Intel Mac, use the install script or npm.
  • No separate Node.js install: the app runs the server on its bundled runtime.

Updates

The app checks for new desktop releases and asks before restarting to install one. You can also run Check for Updates… from the app menu or the menu bar / tray icon, or turn automatic downloads off in Settings. On Linux, in-app updates apply to the AppImage; a .deb install is updated by installing the newer .deb.

Settings

Settings (⌘, on macOS, Ctrl+, on Windows and Linux) cover the server port, opening at login, starting hidden, menu-bar-only mode, keeping the server running when the window closes, verbose server logging, the config directory, and what to do when another ima2 server is already running.

Shared with the CLI

The app uses the same config directory as an npm install (~/.ima2 by default), so history, sign-ins and settings are shared. The app never starts a second server beside one that already runs. If the running server is its own, it reconnects. If it was started from a terminal, by ima2 start or by the login service, the app asks whether to keep using it or replace it with the server inside the app; Settings → When another ima2 server is running makes the choice permanent, and Use Bundled Server in the tray menu switches later. Replacing a login-service server stops the service until your next login; run ima2 service uninstall to remove it for good.

The CLI can control the app's server too: ima2 status --runtime shows it as started by the desktop app, and ima2 stop stops it without the app restarting it.