Install Synapse

The binaries live in a public mirror: romulofebasi/synapse-releases. The source still lives in romulofebasi/synapse (private). Anyone can install without a GitHub account.

One-liner (macOS, Linux)

curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh | sh

Installed? → ONBOARDING.md walks you from here to your first answer (syn setup → syn init → first entities), with the real output you’ll see.

The installer:

1. detects uname -s / uname -m,
2. resolves the latest release tag (or SYNAPSE_VERSION if set),
3. downloads the matching tarball and attempts the documented best-effort checksum/signature checks,
4. extracts and drops syn into INSTALL_DIR (default /usr/local/bin),
5. on macOS, clears the Gatekeeper com.apple.quarantine attribute unless configured otherwise.

The installer does not require every verification prerequisite to be present. Read release verification for its exact skip/warning behavior and the strict manual workflow when both publisher and archive checks are required.

Environment knobs

Examples:

# pin an example release; choose the reviewed tag required for your installation
curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh \
  | SYNAPSE_VERSION=v1.4.0 sh

# no sudo, no PATH change
curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh \
  | INSTALL_DIR="$HOME/.local/bin" sh

Manual download

The archive layout is:

synapse-<version>-<target>.tar.gz
└── synapse-<version>-<target>/
    ├── syn                  (or syn.exe on Windows)
    ├── README.md
    ├── LICENSE
    └── CHANGELOG.md

Choose the reviewed tag and matching archive from the public releases. Source documentation can describe newer capabilities than the selected binary:

Intel Macs (x86_64-apple-darwin) are not supported as of v0.5. The ONNX Runtime behind the semantic layer ships no Intel-macOS build, so there is no syn binary for that target. Apple Silicon is the only supported macOS. (Tracked for a possible later restore via a different backend: ROADMAP SYN-174.)

Linux / macOS

Before the extraction/install steps below, download the selected tag’s SHA256SUMS and SHA256SUMS.cosign.bundle, then authenticate the manifest and compare the selected archive using the manual verification guide. The commands below show the archive layout and installation; archive download alone does not verify its publisher.

VERSION=v1.4.0  # example tag; select the reviewed release you need
TARGET=aarch64-apple-darwin   # change for your platform
curl -fsSLO "https://github.com/romulofebasi/synapse-releases/releases/download/${VERSION}/synapse-${VERSION#v}-${TARGET}.tar.gz"
# Authenticate the manifest and verify this archive before extracting (VERIFYING-RELEASES.md).
tar -xzf "synapse-${VERSION#v}-${TARGET}.tar.gz"
sudo install -m 755 "synapse-${VERSION#v}-${TARGET}/syn" /usr/local/bin/syn
xattr -dr com.apple.quarantine /usr/local/bin/syn 2>/dev/null || true
syn --version

Windows (PowerShell)

$version = "v1.4.0"  # example tag; select the reviewed release you need
$target  = "x86_64-pc-windows-msvc"
$asset   = "synapse-$($version.Substring(1))-$target.zip"
$url     = "https://github.com/romulofebasi/synapse-releases/releases/download/$version/$asset"
$tmp     = "$env:TEMP\$asset"

Invoke-WebRequest $url -OutFile $tmp
# Authenticate the manifest and verify this archive before extracting (VERIFYING-RELEASES.md).
Expand-Archive $tmp -DestinationPath $env:TEMP -Force
$src = "$env:TEMP\synapse-$($version.Substring(1))-$target\syn.exe"
$dst = "$HOME\bin\syn.exe"
New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
Move-Item $src $dst -Force
# Add $HOME\bin to your PATH if you haven't already:
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\bin", "User")
syn --version

Windows may display a SmartScreen warning depending on the selected artifact and local policy. Check publisher/integrity evidence before deciding whether to run it.

With npm / npx (Node ecosystem)

npx @febasi/synapse --help          # run without installing
npm install -g @febasi/synapse      # or install the `syn` command
syn --version

The package is a thin launcher; the real binary is delivered through per-platform optionalDependencies (the esbuild model), so npm installs only the one matching your OS/arch, with no runtime download. Supported targets: darwin-arm64, linux-x64, linux-arm64, win32-x64. Published with npm provenance from its publishing workflow. Inspect the selected package’s actual attestation; this is separate from manually verifying an archive manifest and cosign bundle.

The unscoped synapse name is taken on npm by an unrelated package, so Synapse publishes under the @febasi organization scope.

How it is published (SYN-103): the npm packages are built and published from the public synapse-releases mirror (.github/workflows/npm-publish.yml), which runs after a release is mirrored. It uses npm trusted publishing (OIDC) (no long-lived token) and, because the mirror repo is public, npm generates provenance attestations automatically. Owner setup (one time): configure a trusted publisher on each of the five @febasi/synapse* packages pointing at the synapse-releases repo + that workflow. The launcher source lives in the mirror under npm/synapse/.

From source

If your platform isn’t in the table, or you want to hack on syn:

git clone https://github.com/romulofebasi/synapse.git
cd synapse
./scripts/bootstrap.sh        # enable git hooks, check toolchain
cargo build --release         # default binary (includes the semantic layer): see "Feature flags" below
./target/release/syn --version

You need:

• Rust 1.89+ (see ADR-009 + its SYN-168 amendment).
• A POSIX shell for the hooks.
• macOS, Linux, or Windows (MSRV-tested on Ubuntu in CI).

Feature flags: the v0.5 semantic layer ships by default

cargo build --release produces the default binary: full CLI, MCP server, FTS5 search and the v0.5 semantic layer: on-device embeddings (fastembed / BGE-M3), NER (GLiNER), and hybrid search. The default feature set is ["mcp", "v05_backends"] (SYN-168); the layer adds only ~25 MB (ONNX Runtime) to the binary and bundles no models.

The default build already includes the semantic layer (ADR-008 / SYN-168). To opt out and produce a minimal core binary: full CLI + MCP + FTS5 search, no embeddings/NER/hybrid, and ~25 MB smaller: build with no default features:

# Minimal core binary (no semantic layer):
cargo build --release --no-default-features --features mcp

# Try the mechanics offline, zero downloads (deterministic stub):
cargo build --release --no-default-features --features "mcp test_backend"
./target/release/syn embed --check     # works without any model

# Add hosted embeddings (OpenAI/Voyage) on top of the default layer:
cargo build --release --features network_backends

The default syn already carries the embed command and the --semantic / --no-vector / --grade search flags. See COMMANDS.md and CONFIGURATION.md.

Models download on consent, not at build and not on first write. The binary ships without the ~2.5 GB of local models. They are pulled only when you explicitly ask: answering “yes” to the syn init onboarding prompt, or running syn embed --all (or syn embed <slug>). Until then, writes save without embedding and syn search degrades to FTS + graph: nothing blocks and nothing downloads silently. syn embed --check is read-only and reports models_ready false without downloading. Budget ~2.5 GB for the multilingual defaults, ~325 MB for the English opt-downs; the cache (overridable via SYNAPSE_MODEL_CACHE; see CONFIGURATION.md) is shared across every workspace on the machine.

Full detail: exact models, source repos, cache paths, offline / air-gapped use, privacy, licenses, and the Linux glibc ≥2.38 requirement: lives in MODELS.md.

Signature verification and operating-system trust

Release archives using the current signing workflow include SHA256SUMS and SHA256SUMS.cosign.bundle. Verify the selected release’s actual assets, expected tagged workflow identity and exact archive digest before extraction. Follow VERIFYING-RELEASES.md for the manual policy and the convenience installer’s best-effort behavior.

Sigstore authenticates release evidence; it does not provide Apple notarization or Windows code-signing trust. Gatekeeper/SmartScreen can still prompt. Clearing quarantine or accepting an operating-system prompt is not a substitute for checking the artifact’s publisher and integrity. Check the chosen release notes for platform-specific signing status.

Uninstall

Synapse ships its own uninstaller (SYN-74). The flags compose:

syn uninstall                  # remove the binary at $(which syn)
syn uninstall --purge          # also delete the global config dir
syn uninstall --everything     # also delete the workspaces registry
syn uninstall --everything --force   # skip the y/N prompt (CI-friendly)

--everything implies --purge. Workspace folders (~/brain or wherever you ran syn init) are never touched; they are plain Markdown owned by you.

If syn is no longer on $PATH for some reason, the manual fallback still works:

sudo rm /usr/local/bin/syn          # or wherever you put it
rm -rf ~/.config/synapse                       # global config (Linux)
rm -rf ~/Library/Application\ Support/synapse  # global config (macOS)