SynapsesOS
Getting Started

Installation

Synapses ships as a single desktop app that includes the synapses CLI. One install gives you everything — the control panel, the daemon, and the command-line interface.

Download from synapsesos.com or install via terminal:

Terminal window
curl -fsSL https://synapsesos.com/install.sh | sh

This installs the Synapses desktop app with the CLI included.

What happens:

  1. Downloads the app for your platform
  2. Copies the CLI binary to ~/.synapses/bin/synapses
  3. Creates a /usr/local/bin/synapses symlink
  4. Adds ~/.synapses/bin to your shell PATH
  5. Launches the app for onboarding

User steps: 1 (run the command)

Path 2: Homebrew (macOS)

Terminal window
brew install synapses

Installs the Synapses app to /Applications and makes the synapses CLI available.

Path 3: Direct Download (macOS)

  1. Download the latest .dmg from GitHub Releases
  2. Open the DMG and drag Synapses to Applications
  3. Launch the app — it sets up the CLI automatically

Path 4: Headless / CI (CLI only)

On systems without a GUI, the install script automatically detects headless mode:

Terminal window
curl -fsSL https://synapsesos.com/install.sh | sh

This installs just the synapses CLI binary — no desktop app.

To force CLI-only mode even on GUI systems:

Terminal window
SYNAPSES_CLI_ONLY=1 curl -fsSL https://synapsesos.com/install.sh | sh

Path 5: From Source (Contributors)

Terminal window
git clone https://github.com/SynapsesOS/synapses
cd synapses
go build -o ./build/synapses ./cmd/synapses
./build/synapses init

See Developer Setup for connecting a source-built binary to the desktop app.

How It Works

The Synapses app bundles the synapses Go binary inside the application package. On first launch:

  1. Extracts the binary to ~/.synapses/bin/synapses
  2. Creates a symlink at /usr/local/bin/synapses (if writable)
  3. Adds ~/.synapses/bin to your shell rc file
  4. Starts the daemon automatically
  5. Registers a launch agent so the daemon starts on login

Verify Installation

Terminal window
synapses --version
synapses status

If the CLI is not found, add ~/.synapses/bin to your PATH:

Terminal window
export PATH="$HOME/.synapses/bin:$PATH"

Corporate Networks

If GitHub is blocked, set a mirror URL:

Terminal window
SYNAPSES_DOWNLOAD_URL=https://internal-mirror.corp.com curl -fsSL https://synapsesos.com/install.sh | sh

For CI with rate limit concerns, pass a GitHub token:

Terminal window
GITHUB_TOKEN=ghp_xxx curl -fsSL https://synapsesos.com/install.sh | sh

System Requirements

  • OS: macOS 12+ (arm64/x86_64), Linux (glibc 2.17+, x86_64/arm64)
  • Disk: ~50 MB for the app. SQLite index scales with codebase (~1 MB per 1,000 functions).
  • Memory: Minimal at rest. Under 500 MB during indexing.
  • Optional: Ollama for brain enrichment features.

Next Steps

Head to Quickstart to initialize your first project.