Getting Started

Installation

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

Homebrew (macOS & Linux)

The fastest way to install AsanagiDB on macOS and Linux. The formula installs asanagidb, asanagidb-admin, asanagidb-mcp, and asna:

# Tap the official repository and install
brew tap asanasoft/tap
brew install asanagidb

AsanagiIDX and AsanagiTOGAF are not distributed through Homebrew. They install from a downloadable archive — see their product pages.

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, asna}

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, asna}

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. As of 2.0.0 it has no external library dependency — the line editor is built in — so it installs and runs out of the archive with nothing else to add.

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

As of 2.0.0 the Windows archive also includes asna.exe, the interactive Gremlin console.

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.