Linux package

The Linux package installs the Gateway (which also serves the Dashboard) and the sophon CLI, and runs the Gateway as a systemd user service under your own account. There is no desktop app for Linux yet: you use Sophon in your browser and from the terminal. The .NET runtime is bundled.

RequirementsCopy Anchor Link

• Debian 12, or Ubuntu 22.04 or later. Other distributions with glibc 2.34 or newer and the same libraries may work, but only Debian and Ubuntu are packaged.
• A 64-bit Intel or AMD machine (amd64) or a 64-bit Arm machine (arm64). Check with dpkg --print-architecture.
• systemd, which runs the Gateway. On WSL 2, turn it on first: add systemd=true under [boot] in /etc/wsl.conf, then run wsl --shutdown from Windows.
• sudo rights to install the package.
• Port 8470 free on this machine. The Gateway listens there.

No .rpm package exists yet. On Fedora, RHEL, openSUSE, Arch, Alpine or NixOS, use Docker.

InstallCopy Anchor Link

sha256sum ~/Downloads/sophon_2.2.2_amd64.deb

sudo apt install ./sophon_2.2.2_amd64.deb

systemctl --user start sophon-gateway

The Dashboard's Setup Wizard asks for your first model provider: continue with Configuration.

What the package sets upCopy Anchor Link

How the Gateway runsCopy Anchor Link

The Gateway is a systemd user service, sophon-gateway. It runs as you, not as root, with your data in your own ~/.sophon. It listens on http://localhost:8470, is reachable only from this machine, and systemd restarts it if it fails.

The package enables the service for every user, so it starts each time you log in. If it doesn't, enable it for yourself with systemctl --user enable sophon-gateway. A user service stops when you log out; to keep it running without a login session (for example on a server you reach over SSH), turn on lingering:

loginctl enable-linger "$USER"

Every user's Gateway listens on the same port, 8470, so only one user's Gateway can run on a machine at a time.

Start, stop and check the GatewayCopy Anchor Link

systemctl --user status  sophon-gateway
systemctl --user start   sophon-gateway
systemctl --user stop    sophon-gateway
systemctl --user restart sophon-gateway
journalctl --user -u sophon-gateway -n 50     # recent log lines
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.

UpgradeCopy Anchor Link

Download the newer package, install it the same way, then restart the service:

sudo apt install ./sophon_<new-version>_amd64.deb
systemctl --user restart sophon-gateway

Your data in ~/.sophon is kept. apt upgrade won't find new versions until an apt repository exists.

UninstallCopy Anchor Link

sudo apt remove sophon

This tries to stop your Gateway, then removes everything under /opt/sophon, the sophon command and the service. If a Gateway is still running afterwards (for example another user's), stop it with systemctl --user stop sophon-gateway in that user's session. sudo apt purge sophon does the same. Neither one deletes your data. To remove it as well:

rm -rf ~/.sophon

TroubleshootingCopy Anchor Link

The page doesn't load. Run systemctl --user status sophon-gateway, then journalctl --user -u sophon-gateway -n 50. If systemctl --user reports that it can't connect to the bus, you are in a session without a user manager (for example sudo su); log in as yourself, or over SSH, and try again.

Port 8470 is already in use. The Gateway logs could not bind ... the port is already in use and exits, and systemd retries it every few seconds. Stop the other program using the port (it may be another user's Gateway); the next retry then succeeds, or run systemctl --user restart sophon-gateway.

You used the install.sh script before. A unit it left in ~/.config/systemd/user/ takes precedence over the packaged one. Run install.sh --uninstall from that earlier install first, then reload:

systemctl --user daemon-reload
systemctl --user enable --now sophon-gateway

More in Common Issues and Diagnostic Logs.