Browse docs Menu

Start here

Docs home Install Buffaly Install on Windows Install on Linux Install on Mac Quickstart How-to library

Learn Buffaly

What Buffaly is User guide Core concepts Coming from other agents Memory and skills

Build and extend

Add a prompt skill Add a ProtoScript skill Add a C# DLL tool Add a model provider Skills, services, and tools ProtoScript services

Operate

Sessions and long-running work Session anatomy Plan, Scratch, and Tasks Session artifacts Session timeline Compaction

Reference

Ontology and ProtoScript Providers and authentication Web modules and UI Diagnostics & recovery Safety rules Secrets handling SmartPatch

Public prerelease

Install Buffaly on Mac.

Buffaly publishes an Apple Silicon Mac prerelease package through the mac-latest GitHub release tag. Install from the tarball, connect to PostgreSQL or an external Microsoft SQL Server, then validate with the included shell scripts.

Download and verify the Mac package

Use the ARM64 tarball for Apple Silicon Macs. GitHub serves this from the mac-latest prerelease tag so the link remains stable across Mac package refreshes.

Download Mac tarball Download checksum Open prerelease

mkdir -p "$HOME/Downloads/buffaly-install"
cd "$HOME/Downloads/buffaly-install"

curl -L -o buffaly-osx-arm64-latest.tar.gz \
  https://github.com/buffaly-ai/buffaly-installer/releases/download/mac-latest/buffaly-osx-arm64-latest.tar.gz
curl -L -o buffaly-osx-arm64-latest.sha256 \
  https://github.com/buffaly-ai/buffaly-installer/releases/download/mac-latest/buffaly-osx-arm64-latest.sha256

shasum -a 256 -c buffaly-osx-arm64-latest.sha256
tar -xzf buffaly-osx-arm64-latest.tar.gz
PACKAGE_DIR="$(tar -tzf buffaly-osx-arm64-latest.tar.gz | head -1 | cut -d/ -f1)"
cd "$PACKAGE_DIR"

Install from scratch with PostgreSQL

Use this path when the Mac will connect to PostgreSQL databases reachable from the Mac. The installer applies the packaged PostgreSQL schema scripts when the supplied database user has enough privileges.

Mac prerequisites

command -v brew >/dev/null 2>&1 || echo 'Install Homebrew first: https://brew.sh/'
brew install libpq
brew link --force libpq

command -v bash
command -v python3
command -v psql
command -v tar

Set PostgreSQL connection strings and install

Use separate sessions and semantic databases. Replace the placeholder host, user, and password values.

export BUFFALY_INSTALL_ROOT="$HOME/buffaly"
export BUFFALY_PORT="5088"

export BUFFALY_PG_HOST="<postgres-host>"
export BUFFALY_PG_PORT="5432"
export BUFFALY_PG_USER="<postgres-user>"
export BUFFALY_PG_PASSWORD="<postgres-password>"

export BUFFALY_SESSIONS_DB="buffaly_mac_sessions"
export BUFFALY_SEMANTIC_DB="buffaly_mac_semanticdb_entities"
export BUFFALY_SESSIONS_CONNECTION_STRING="Host=$BUFFALY_PG_HOST;Port=$BUFFALY_PG_PORT;Database=$BUFFALY_SESSIONS_DB;Username=$BUFFALY_PG_USER;Password=$BUFFALY_PG_PASSWORD"
export BUFFALY_SEMANTICDB_CONNECTION_STRING="Host=$BUFFALY_PG_HOST;Port=$BUFFALY_PG_PORT;Database=$BUFFALY_SEMANTIC_DB;Username=$BUFFALY_PG_USER;Password=$BUFFALY_PG_PASSWORD"

bash ./scripts/install.sh \
  --install-root "$BUFFALY_INSTALL_ROOT" \
  --port "$BUFFALY_PORT" \
  --auth none \
  --sql-mode postgresql \
  --sessions-connection "$BUFFALY_SESSIONS_CONNECTION_STRING" \
  --semantic-connection "$BUFFALY_SEMANTICDB_CONNECTION_STRING"

Install from scratch with external Microsoft SQL Server

SQL Server does not run directly on macOS for this installer path. Put SQL Server on Windows, Linux, or another reachable host, create separate Buffaly databases and a separate app login, then point the Mac installer at those databases.

Provision SQL Server databases

Run this from a machine that has SQL Server command-line tools and admin access to the SQL Server instance. The script uses the package-generated database artifacts.

bash ./scripts/provision-sqlserver.sh \
  --admin-connection "-S <sql-host>,<sql-port> -U <admin-login> -P '<admin-password>' -C" \
  --server "<sql-host>,<sql-port>" \
  --app-login buffaly_mac_app \
  --app-password '<strong-app-password>' \
  --sessions-db buffaly_mac_sessions \
  --semantic-db buffaly_mac_semanticdb_entities \
  --sessions-artifacts ./scripts/sessionsdb \
  --semantic-artifacts ./scripts/semanticdb

The app login should access only the new Mac-specific databases. If the SQL Server hosts other Buffaly databases, verify the Mac app login cannot access them before installing.

Install on the Mac

export BUFFALY_INSTALL_ROOT="$HOME/buffaly"
export BUFFALY_PORT="5088"

export BUFFALY_SESSIONS_CONNECTION_STRING='Server=<sql-host>,<sql-port>;Database=buffaly_mac_sessions;User Id=buffaly_mac_app;Password=<strong-app-password>;TrustServerCertificate=True;Encrypt=False;'
export BUFFALY_SEMANTICDB_CONNECTION_STRING='Server=<sql-host>,<sql-port>;Database=buffaly_mac_semanticdb_entities;User Id=buffaly_mac_app;Password=<strong-app-password>;TrustServerCertificate=True;Encrypt=False;'

bash ./scripts/install.sh \
  --install-root "$BUFFALY_INSTALL_ROOT" \
  --port "$BUFFALY_PORT" \
  --auth none \
  --sql-mode external \
  --sessions-connection "$BUFFALY_SESSIONS_CONNECTION_STRING" \
  --semantic-connection "$BUFFALY_SEMANTICDB_CONNECTION_STRING"

Launch and validate

Start with the shell scripts. Only add automatic startup after this validation passes.

"$BUFFALY_INSTALL_ROOT/buffaly-start.sh" --install-root "$BUFFALY_INSTALL_ROOT"
"$BUFFALY_INSTALL_ROOT/buffaly-status.sh" --install-root "$BUFFALY_INSTALL_ROOT"
"$BUFFALY_INSTALL_ROOT/validate.sh" --install-root "$BUFFALY_INSTALL_ROOT" --url "http://127.0.0.1:$BUFFALY_PORT/" --expect-no-auth

Open locally at http://127.0.0.1:5088/buffaly-agent.html. From another machine on Tailscale, use http://<mac-tailscale-host-or-ip>:5088/buffaly-agent.html after confirming the Mac firewall allows the listener.

Optional: start automatically with a user LaunchAgent

Use a user LaunchAgent, not a system LaunchDaemon, so Buffaly runs as the logged-in Mac user and can read/write the user-owned install root.

mkdir -p "$HOME/Library/LaunchAgents"
cat > "$HOME/Library/LaunchAgents/com.buffaly.agent.plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.buffaly.agent</string>
    <key>ProgramArguments</key>
    <array>
      <string>/bin/zsh</string>
      <string>-lc</string>
      <string>$HOME/buffaly/buffaly-start.sh --install-root $HOME/buffaly</string>
    </array>
    <key>WorkingDirectory</key>
    <string>$HOME/buffaly</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>$HOME/buffaly/logs/agent.out.log</string>
    <key>StandardErrorPath</key>
    <string>$HOME/buffaly/logs/agent.err.log</string>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
  </dict>
</plist>
PLIST

launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.buffaly.agent.plist"
launchctl enable "gui/$(id -u)/com.buffaly.agent"
launchctl kickstart -k "gui/$(id -u)/com.buffaly.agent"
launchctl print "gui/$(id -u)/com.buffaly.agent"