Skip to content

Installation

The fastest path is the one-command installer: it brings its own dependencies.

One-click cloud

Prefer a hosted VM? Launch the complete Postgres + Qdrant stack from the Deploy to AWS or Deploy to Azure buttons on soulacy.io. Both paths create an HTTPS endpoint without exposing SSH or the data services. See the cloud deployment guide for the exact resources and operating model.

curl -fsSL https://soulacy.io/install.sh | bash

What it does:

  1. Detects your OS/architecture (macOS & Linux, amd64 & arm64).
  2. Downloads the latest release binaries or, if no release is published yet, builds from source automatically, fetching private copies of Go and Node into ~/.soulacy/toolchain when they're missing (no Homebrew, no system package changes).
  3. Installs soulacy (the gateway) and sy (the CLI) to /usr/local/bin.
  4. Creates your workspace at ~/.soulacy/soulspace with a default config.
  5. Offers to install Ollama and pull llama3 so you have a local LLM out of the box.
  6. Offers to start the gateway and open the GUI at http://localhost:18789.

Pin a version

curl -fsSL https://soulacy.io/install.sh | SOULACY_VERSION=v0.1.11 bash

Set the variable on the installer process (bash), not only on curl.

Requirements

See footprint and requirements for measured size and the distinction between gateway, models, tools, and external services. There is no blanket RAM/startup guarantee.
OS macOS 13+ or Linux (amd64 / arm64)
Prebuilt core curl, tar, compatible platform/system libraries, and TLS trust store
Source fallback / optional tools Build dependencies and tool runtimes depend on platform/features
LLM Ollama (local, free) or an OpenAI / Anthropic / Gemini API key

Build from source

git clone https://github.com/vmodekurti/soulacy-personal.git soulacy
cd soulacy
make all          # GUI + gateway + CLI → ./bin/soulacy and ./bin/sy
sudo install -m755 bin/soulacy bin/sy /usr/local/bin/

make all needs Go 1.26.10+, Node/npm, and the platform's C/SQLite development requirements. It forces a GUI rebuild; make build rebuilds it incrementally when sources change. The gateway embeds the web UI at compile time.

Docker

From a checkout (works today, builds the image locally):

git clone https://github.com/vmodekurti/soulacy-personal.git soulacy
cd soulacy
docker compose up --build -d

The gateway listens on 18789; state persists in the /home/soulacy/.soulacy volume:

docker run -d --name soulacy \
  -p 18789:18789 \
  -v soulacy-data:/home/soulacy/.soulacy \
  ghcr.io/vmodekurti/soulacy-personal:latest   # published with tagged releases

More (Compose details, reverse proxies): Docker deployment guide.

Pre-built binaries

Tagged releases publish soulacy_<version>_<os>_<arch>.tar.gz bundles (each contains both soulacy and sy) on GitHub Releases:

grep 'soulacy_v0.1.11_darwin_arm64.tar.gz' checksums.sha256 | shasum -a 256 -c -
tar -xzf soulacy_v0.1.11_darwin_arm64.tar.gz
sudo install -m755 soulacy sy /usr/local/bin/

Releases also include release-manifest.json, which records the release version, source commit, generation time, and every artifact's OS, architecture, byte size, and SHA-256 digest for installer and CI checks.

If the releases page is empty, use the one-command installer above: it falls back to a source build automatically.

Verify

soulacy --version  # gateway version
sy version         # CLI + framework version
sy doctor          # checks workspace, config, providers, and the gateway

Both soulacy --version and sy version are supported in v0.1.8. If a build prints only a commit hash, it was probably installed from source; use a tagged release when you want sy update to compare versions automatically.

Understand where configuration lives

Fresh installations use:

~/.soulacy/soulspace/config.yaml

Soulacy resolves configuration in this order:

  1. SOULACY_CONFIG_PATH when explicitly set;
  2. config.yaml inside SOULACY_WORKSPACE or the resolved workspace;
  3. the legacy ~/.soulacy/config.yaml location;
  4. ./config.yaml for a development checkout.

Services do not necessarily share your login user's home or environment. If a foreground gateway accepts an API key but systemd does not, follow the Linux/VPS service configuration checklist.

What's next?

  1. sy onboard: the guided first-run path for provider, search, starter agent, update manifest, and auto-start.
  2. Follow the Quick Start, then take the GUI tour.