macOS installer
Install Sophon on a Mac with Apple Silicon. What the package installs, how the Gateway starts at login, and how to upgrade or remove it.
The macOS package installs the Gateway (which also serves the Dashboard) and the sophon CLI. There is no desktop app for macOS yet: you use Sophon in your browser and from the terminal. Nothing else needs to be installed first. The .NET runtime is bundled.
Requirements
- A Mac with Apple Silicon (M1 or later). Intel Macs can't install the package; use Docker instead.
- macOS 14 Sonoma or later.
- An administrator password. The program installs for the whole Mac, in
/Library/Sophon. - Port 8470 free on this Mac. The Gateway listens there.
Install
1. Download and check the file
Download Sophon-<version>-osx-arm64.pkg from Download Sophon, then check its SHA-256 against the one shown next to the download button:
shasum -a 256 ~/Downloads/Sophon-2.2.2-osx-arm64.pkgThe two values must match exactly. If they don't, delete the file and download it again.
2. Open the package
Double-click the package. Because it is not code-signed yet, macOS may refuse to open it. If it does: on macOS 14, Control-click the package in Finder and choose Open; on macOS 15 and later, open System Settings → Privacy & Security and choose Open Anyway.
You can also skip the dialog and install from Terminal:
sudo installer -pkg ~/Downloads/Sophon-2.2.2-osx-arm64.pkg -target /3. Follow the installer
Read the welcome page, accept the license, and enter your administrator password when asked.
4. Open the Dashboard
When the install finishes, the Gateway is already running. If you used the Installer app, it waits up to 30 seconds for the Gateway to answer and opens http://localhost:8470 in your browser. After a Terminal install, or if the page doesn't open, open that address yourself.
The Dashboard's Setup Wizard asks for your first model provider: continue with Configuration.
What the package sets up
| What | Where |
|---|---|
| Gateway and Dashboard | /Library/Sophon/gateway/ |
sophon CLI | /usr/local/bin/sophon (a link into /Library/Sophon/gateway/cli/) |
| Uninstaller | /usr/local/bin/sophon-uninstall |
| Login item for the Gateway | ~/Library/LaunchAgents/ai.sophon.gateway.plist |
| Your data: settings, conversations, memory, credentials | ~/.sophon/ |
| Gateway logs | ~/.sophon/logs/gateway.out.log, gateway.err.log, and sophon-YYYYMMDD.log (one per day, 14 kept) |
How the Gateway runs
The Gateway runs as a launchd agent (ai.sophon.gateway) in your own account, not as root. It starts when you log in, was started right after the install, and launchd starts it again if it crashes. It listens on http://localhost:8470 and is reachable only from this Mac.
Only the user who was logged in during the install gets the agent. Another user on the same Mac runs sophon service install once after logging in to get a Gateway of their own, with their own ~/.sophon.
Start, stop and check the Gateway
sophon service status # is it registered and running?
launchctl kickstart -k gui/$(id -u)/ai.sophon.gateway # restart it
launchctl bootout gui/$(id -u)/ai.sophon.gateway # stop it until your next login
sophon service install # start it again after a stop, or register it if it's missing
sophon service uninstall # stop it and stop starting it at login
curl http://localhost:8470/api/health # is it answering?The installed sophon finds this Gateway on port 8470 by itself; run sophon in a terminal to start the full-screen chat. See CLI.
Upgrade
Download the newer package and install it the same way. The installer stops the Gateway, replaces everything in /Library/Sophon/gateway, and starts the new version. Your data in ~/.sophon is kept. Don't keep your own files in /Library/Sophon: an upgrade replaces /Library/Sophon/gateway, and uninstalling deletes the whole folder.
Uninstall
sudo sophon-uninstallThis stops the Gateway for every user who has it, removes the login items, /Library/Sophon and the two commands in /usr/local/bin. Your data in ~/.sophon is kept. To delete your data too, add --purge; it asks before deleting anything:
sudo sophon-uninstall --purge--purge deletes only your own ~/.sophon. Other users' data stays until they remove it with rm -rf ~/.sophon.
Troubleshooting
The browser didn't open, or the page doesn't load. Run sophon service status. If the agent isn't there (for example, because nobody was logged in at the screen during a remote install), run sophon service install. Then look at ~/.sophon/logs/gateway.err.log.
Port 8470 is already in use. The Gateway writes could not start: ... is already in use to ~/.sophon/logs/gateway.err.log and exits, and launchd retries it every 10 seconds. Stop the other program using the port; the next retry then succeeds.
The install finished but the Gateway never started. For safety, the installer doesn't set up the login item when ~/.sophon or ~/Library/LaunchAgents is a symbolic link. Run sophon service install yourself after the install.
More in Common Issues and Diagnostic Logs.
Windows installer
Install Sophon on Windows 10 or 11 with the setup program or the MSI. What it installs, how the Gateway starts, and how to upgrade or remove it.
Linux package
Install Sophon on Debian or Ubuntu with the .deb package. What it installs, how the systemd user service runs, and how to upgrade or remove it.