Getting Started

Installation

Install the complete suite via Homebrew or grab the native installers (asanagidb, asanagidb-admin, asanagidb-mcp, asanagi-idx, asna) for your platform.

Homebrew (macOS & Linux)

The fastest way to install the complete Asanagi suite (asanagidb, asanagidb-mcp, asanagi-idx, asna, asanagidb-admin) on macOS and Linux:

# Tap the official repository and install the suite
brew tap asanasoft/tap
brew install asanagidb asanagi-idx

macOS

# mount the DMG, then run the AsanagiDB installer pkg inside it
sudo installer -pkg asanagidb-vX.Y.Z.pkg -target /

Binaries /usr/local/bin/{asanagidb, asanagidb-admin, asanagidb-mcp}

Config /etc/asanagi/fleet.yaml

Data /var/lib/_asanagi/asanagi/data

Logs /var/log/asanagidb.log

Service LaunchDaemon ai.asanagi.asanagidb, runs as root (required on Darwin 27+), HOME set to /var/lib/_asanagi

# activate — HOME must match the service's, not your own account's
sudo HOME=/var/lib/_asanagi asanagidb activate <LICENSE_KEY>
sudo launchctl kickstart -k system/ai.asanagi.asanagidb

Linux

# from the extracted tarball
sudo bash install.sh

Binaries /usr/local/bin/{asanagidb, asanagidb-admin, asanagidb-mcp}

Config /etc/asanagi/default.yaml (per-instance)

Data /var/lib/_asanagi/asanagi/data

Logs journalctl -u asanagidb@default -f

Service systemd asanagidb@<instance>, runs as the real _asanagi system user (home /var/lib/_asanagi)

# activate as the _asanagi service user, not as yourself or plain root
sudo -u _asanagi asanagidb activate <LICENSE_KEY>
sudo systemctl restart asanagidb@default

The Linux archive also ships asna, the interactive Gremlin console. It links libedit at runtime; the installer checks for it and skips asna with a note rather than installing something that fails on first run. Install libedit2 (apt) or libedit (dnf) and re-run to get it.

Windows

# from the extracted zip, in an Administrator PowerShell
.\install.ps1

Binaries C:\Program Files\Asanagi\AsanagiDB\

Config C:\ProgramData\Asanagi\AsanagiDB\config\default.yaml

Data C:\ProgramData\Asanagi\AsanagiDB\data

Logs Event Viewer -> Windows Logs -> Application

Service Windows Service "AsanagiDB", runs as NT AUTHORITY\LocalService

# activate, then copy the license into the LocalService profile the
# service actually reads from
asanagidb-admin.exe activate <LICENSE_KEY>
New-Item -ItemType Directory -Force "C:\Windows\ServiceProfiles\LocalService\.asanagi"
Copy-Item "$env:USERPROFILE\.asanagi\license.json" "C:\Windows\ServiceProfiles\LocalService\.asanagi\license.json"
Restart-Service AsanagiDB

asna is not currently included in the Windows archive.

Why license activation trips people up

license.json always lives at $HOME/.asanagi/license.json — but $HOME is resolved for whichever account is actually running the AsanagiDB service, not the account you're logged in as. Running activate as yourself writes the license to your own home directory, which the installed service never reads — it looks like activation silently failed, when really it succeeded in the wrong place. Always activate using the exact command shown above for your platform, and restart the service afterward.