Skip to content

macOS Installation

Install Gremia Shell on macOS using the .dmg disk image.

System Requirements

Requirement Minimum
OS macOS 12 Monterey or later
Architecture Apple Silicon (arm64) or Intel (x86_64) — universal binary
RAM 4 GB
Disk Space 200 MB
Runtime WebKit (bundled with macOS)
Network HTTPS outbound to api.gremia.io

Download

Download the latest .dmg from the Releases page.

Two variants are available:

File Architecture
Gremia-Shell_x.y.z_aarch64.dmg Apple Silicon (M1/M2/M3)
Gremia-Shell_x.y.z_x64.dmg Intel

Which file do I need?

Click the Apple menu > About This Mac. If the chip says "Apple M1" or similar, use the aarch64 build. If it says "Intel", use the x64 build.

Installation Steps

1. Open the disk image

Double-click the .dmg file to mount it. A Finder window appears with the Gremia Shell icon and an Applications folder alias.

2. Drag to Applications

Drag the Gremia Shell icon onto the Applications folder. This copies the app to /Applications/Gremia Shell.app.

3. First launch

On first launch, macOS Gatekeeper may display a warning:

"Gremia Shell" is an app downloaded from the internet. Are you sure you want to open it?

Click Open to proceed. This only appears once.

If blocked by Gatekeeper

If macOS prevents the app from opening entirely, go to System Settings > Privacy & Security and click Open Anyway next to the Gremia Shell entry.

4. Sign in and connect

  1. Sign in with your Gremia account
  2. Select or load a manifest from the cloud
  3. The Shell establishes the encrypted WebSocket tunnel

Auto-Updater

The built-in updater checks for new versions every 6 hours:

  • Background check runs automatically while the app is open
  • A notification banner appears when an update is available
  • Click Update Now to download, install, and restart

Manual check: Gremia Shell > Check for Updates (menu bar).

The updater downloads a signed .tar.gz bundle and replaces the app in place. Code signing ensures authenticity.

Permissions

Gremia Shell may request the following macOS permissions:

Permission Reason
Network Connect to Gremia Cloud API and WebSocket tunnel
Notifications Alert when tasks complete or updates are available
File Access MCP servers may read/write files on your behalf

Grant permissions as prompted. You can manage them later in System Settings > Privacy & Security.

Uninstallation

  1. Quit Gremia Shell if running
  2. Drag Gremia Shell.app from /Applications to the Trash
  3. Optionally remove user data:
rm -rf ~/Library/Application\ Support/io.gremia.shell
rm -rf ~/Library/Caches/io.gremia.shell

Troubleshooting

App crashes on launch

Check the system log for details:

log show --predicate 'process == "Gremia Shell"' --last 5m

Common causes:

  • Outdated macOS: Update to macOS 12 or later
  • Corrupted download: Re-download the .dmg and verify the checksum

WebSocket connection fails

Test connectivity:

curl -I https://api.gremia.io/health

If using a corporate proxy, configure it in System Settings > Network > Proxies or set the environment variable:

export HTTPS_PROXY=http://proxy.example.com:8080

Certificate renewal fails

Force a certificate renewal by restarting the Shell. The cert rotation loop runs every 5 minutes and renews certificates 1 hour before expiry. If it continues to fail, check your auth token is still valid by signing out and back in.