Skip to Content
Sophon Docs
Getting Started

Installation

Install Sophon with the native installer for Windows, macOS or Linux, or deploy it with Docker. Then add the CLI if you want a terminal client.

Sophon is one Gateway (the server that holds your assistant, its memory and its approval gates) plus the clients you use it from. The Gateway serves the Dashboard itself, so once it is running you open it in a browser. There are two ways to install the Gateway, and one optional client you can add.

Choose how to install

Native installerDocker Compose
Best forOne person, on the computer they useA server or a shared deployment for a team
PlatformsWindows 10/11 (x64), macOS 14+ (Apple Silicon), Debian and Ubuntu (x64, arm64)Any machine that runs Docker 24+
What you need firstNothing. The runtime is bundledDocker and Docker Compose
How it runsIn the background as your own user, started at sign-inAs containers, restarted by Docker
Open it athttp://localhost:8470http://localhost:8080
Your data~/.sophon in your home folderThe folder you mount as SOPHON_DATA

Installers are on the downloads page. Each one carries a SHA-256 checksum, and the platform guides show how to check it.

Native installer

Follow the guide for your platform:

  • Windows: Sophon-Setup-<version>-win-x64.exe installs the Gateway, the desktop app and the CLI. The .msi lets you choose the parts.
  • macOS: Sophon-<version>-osx-arm64.pkg installs the Gateway, the Dashboard and the sophon CLI.
  • Linux: sophon_<version>_amd64.deb or _arm64.deb installs the same, as a systemd user service.

Every installer puts the program files in a system location and keeps your data in ~/.sophon (%USERPROFILE%\.sophon on Windows). Upgrading or uninstalling keeps that folder unless you ask to delete it.

The installers are not code-signed yet, so Windows SmartScreen and macOS Gatekeeper warn the first time you run one. Each platform guide shows how to get past the warning, and how to check the SHA-256 first so you know the file is the one we built.

Docker Compose

Create a docker-compose.yml:

docker-compose.yml
services:
  sophon-gateway:
    image: buildersoftdev/sophon:latest
    ports:
      - "8081:8080"
    volumes:
      - ${SOPHON_DATA}:/home/sophon/.sophon
    environment:
      - SOPHON__Tier=Personal
      - SOPHON__DataDirectory=/home/sophon/.sophon
    restart: unless-stopped

  sophon-dashboard:
    image: buildersoftdev/sophon-dashboard:latest
    ports:
      - "8080:80"
    environment:
      - SOPHON_GATEWAY_URL=http://sophon-gateway:8080
    depends_on:
      - sophon-gateway
    restart: unless-stopped
# Set your data directory (absolute path, forward slashes on Windows)
export SOPHON_DATA=~/.sophon
docker compose up -d

Open http://localhost:8080. The Gateway API is on http://localhost:8081. For all three tiers, health checks and platform notes, see Docker Deployment and Platform Guides.

Add the CLI (optional)

The macOS and Linux installers already put sophon on your PATH, and the Windows installers include it too (see the Windows guide for the command name). On any other machine, or to use the CLI against a Gateway somewhere else, install it as a .NET global tool. It needs the .NET 10 runtime:

dotnet tool install -g sophon-cli
sophon onboard   # interactive setup wizard

The .NET tool is only the client and does not install a Gateway. On macOS and Linux it finds a Gateway installed by the .pkg or .deb and uses port 8470. On Windows, or with no installed Gateway, it assumes http://localhost:8080, so point it at port 8470:

sophon --gateway-url http://localhost:8470 status
# or for every command in this shell
export SOPHON_GATEWAY_URL=http://localhost:8470

See CLI for the full command set.

Before you start: system requirements

MinimumRecommended
CPU2 cores4+ cores
RAM2 GB8+ GB
Disk1 GB, plus your data10+ GB

The native installers bundle the .NET runtime. Docker 24+ is needed only for Docker Compose, or for the optional container sandbox that runs code; without Docker, Sophon runs code in its process-based sandbox instead.

Next steps

On first open, the Dashboard's Setup Wizard asks for your first model provider. Sophon ships with none configured, so you bring your own API key or a local model. Continue with Configuration.