Local Buffaly Installation
A guide for installing a standalone local Buffaly instance on a Windows machine. Learn how to prepare, run the provisioning workflow, configure local databases, and launch your agent in IIS.
What you will install
A local Buffaly installation sets up a fully self-hosted, offline-first instance of Buffaly on your machine. It consists of several decoupled services working together seamlessly:
Buffaly Agent Web
The main Razor Pages user interface, local sessions workspace, and live chat dashboard.
Buffaly Worker Service
The background orchestration engine that boots and manages dedicated model pipelines and execution loops.
Sessions Web
A companion diagnostics and monitoring site to inspect real-time session timelines, memory structures, and compaction stats.
SQL Server Storage
Dedicated local SQL databases containing your local Semantic DB (ontology data) and Sessions DB (messages, features, and logs).
Optional Voice Gateway
Some installer packages also include the companion voice gateway app; configure it after the base web, worker, sessions, and database flow is healthy.
Before you begin: Choose your instance name
The installer/provisioner derives folder names, database names, and local host bindings using a short Instance Name slug.
Choosing a unique name (such as matt) avoids database and host-name conflicts with other developers on the same machine.
System requirements
The provisioning workflow verifies these requirements during installation, but you should prepare them beforehand:
hosts files.Provider API keys, Google Workspace setup, web modules, and advanced integrations are not required to complete the base local install. Add those after the main site, sessions, provider catalog, and worker loop validate successfully.
Step-by-step workflow
Work through these installation phases to set up your local environment:
Download & unpack
Download the installer package from the Buffaly repository or download site. Unpack it into a secure temporary folder (e.g., C:\temp\BuffalyInstaller\Buffaly-latest).
Check prerequisites
Run the machine prerequisite scanner in the provisioning UI to verify .NET 9, PowerShell 7, SQL Server connectivity, and IIS configuration. Resolve any red warnings before continuing.
Choose folders
Select the extracted package source directory and choose a unique destination folder for your new local instance root (e.g., C:\inetpub\wwwroot\matt.local).
Configure the instance
Set up your local instance properties. Typical local configurations include:
| Setting | Typical Local Default | Role |
|---|---|---|
| Instance Name | matt | Unique short slug deriving default hostnames/databases. |
| SQL Server | localhost\SQLEXPRESS2025 | Target SQL Server engine for schemas and tables. |
| Semantic database | buffaly_semanticdb_matt | Stores semantic schemas, vectors, and ontology mappings. |
| Sessions database | buffaly_sessions_matt | Stores active sessions, full conversation history, and flags. |
| Sessions root path | C:\inetpub\wwwroot\matt.local\data\sessions | The root folder hosting live session files and plan state. |
Choose local hosting
Choose IIS hosting for standard local operation. The provisioner creates the local IIS sites, standard host bindings, app pool permissions, and an internal worker callback binding used for same-machine worker-to-web communication:
Run readiness scan
Initiate a readiness scan to verify directory access, SQL credentials, IIS binding permissions, and database validity. Make sure everything passes before proceeding.
Provision, configure & validate
Click provision to initialize or migrate databases, write local environment config files (appsettings.json),
seed or repair database-backed feature settings, and bind local IIS identities.
Launch Buffaly
Open your browser and navigate to your configured main URL (e.g., http://matt.local/). Create an initial session and confirm the chat UI, Sessions list, provider catalog, and worker startup path load without startup errors.
Basic validation checklist
After setup, run these diagnostics to guarantee your local instance is healthy and operational:
Post-install directory layout
Your local install directory is divided into separate spaces with explicit write/override boundaries:
For the complete, authoritative description of folder ownership rules, see the Install Layout documentation.
Troubleshooting local startup
If your local installation fails to load or start correctly, diagnose the issue from local logs first:
Open the newest error logs here to identify missing settings or runtime exceptions immediately.
Common local failure causes:
- Database Connectivity: SQL Server service is stopped, or the application pool identity does not have permission to access the local DB.
- Port Bindings: The configured callback ports or standard HTTP ports are already in use by another application.
- Missing Config Root: The appsettings in the
configfolder are corrupt, missing, or lack required encryption keys. - Stale App Config: App-local settings can override config-root settings after an incomplete update; repair the installed files and re-run provisioning validation.
- Worker Config: If a worker cannot start, confirm the worker feature points at installed files and that
config\agent-worker\appsettings.jsonexists under the install root.