Install and run | SAG Wiki

SAG provides two primary installation paths: a desktop application and self-hosted Docker. Desktop is the direct choice for personal use. Docker suits development, trusted local networks, and environments where you manage the data yourself.

Choose an installation path

Method	Best for	Runtime dependencies	Data location
Desktop	Individuals who want a ready-to-use app	No separate Python, Node.js, or database installation	Operating-system application data directory
Docker Compose	Developers, servers, and trusted LANs	Docker Desktop or Compose v2	Docker volume `sagdata`
Local source	Contributors and frontend/backend debugging	Python 3.11+ and Node.js 20+	`apps/api/.data/`

Desktop application

Download the latest stable build from GitHub Releases.

Platform	Installer	Notes
macOS 15+, Apple Silicon	`SAG-*-mac-arm64.dmg`	Signed and notarized, with stable-channel automatic updates
Windows 10/11, x64	`SAG-Setup-*-win-x64.exe`	Currently unsigned and may show an unknown-publisher warning; automatic updates are supported

Every release also includes SHA256SUMS.txt for download-integrity verification. Full-package upgrades do not overwrite your knowledge base or uploaded files.

Docker quick start

git clone https://github.com/Zleap-AI/SAG.git
cd SAG
docker compose up -d --build

The first start does not require an API key, Python, Node.js, or an external database. When both services are healthy, open:

Web workspace: http://localhost:3000
OpenAPI documentation: http://localhost:8000/docs
API readiness check: http://localhost:8000/api/v1/system/ready

Check service status:

docker compose ps
docker compose logs -f api web

Both api and web should report healthy. The first image build and API cold start can take several minutes.

Stop and start again

docker compose down
docker compose up -d

docker compose down stops the containers but preserves the database, knowledge indexes, and uploads in sagdata.

Do not run docker compose down -v while you still need the data. The -v flag permanently deletes the default data volume.

Custom ports

Copy the environment template, then change the host ports and the API address used by the browser:

cp .env.example .env

WEB_PORT=3100
API_PORT=8100
BIND_ADDRESS=127.0.0.1
SAG_CORS_ORIGINS=http://localhost:3100
NEXT_PUBLIC_API_BASE=http://localhost:8100

NEXT_PUBLIC_API_BASE is embedded in the Web build. Rebuild after changing it:

docker compose up -d --build

Network boundary

Compose listens on 127.0.0.1 by default. SAG is currently designed as a local, single-user product. Do not expose ports 3000 and 8000 directly to the public internet.

For remote access, place HTTPS and an external access-control layer in front of SAG, such as a VPN, an IP allowlist, or an authenticated reverse proxy. See Production deployment for the complete requirements.