Install

There is no published installer for Agentbits yet, so today you run it from source. This page covers what you need, how to start the app, where it keeps your data, and what happens when you update or uninstall.

System requirements

Windows 10/11	The main target. The Windows installer is built for x64.
macOS	Experimental. A macOS package can be built, but it has not been tested on a real Mac yet.
Linux	No package. Running from source works.
Node.js 22 or newer	Needed only to run or build Agentbits from source.
An AI provider	Optional at first. The free Demo needs nothing. For real work you need Claude Code CLI, Codex CLI, or an Anthropic or OpenAI API key. See Providers.

Agentbits stores API keys and passwords with the operating system keychain: Windows DPAPI, macOS Keychain or Linux Secret Service. If no keychain is available, Agentbits refuses to save secrets.

Installer status

No installer has been published on GitHub Releases yet. Windows packages (and later macOS) will be attached there once a release has been built and checked.

When installers are published, they will not be code-signed. Windows SmartScreen will show a warning the first time you run one:

1. In the “Windows protected your PC” window, click More info.
2. Click Run anyway.

Run from source

1. Install Node.js 22 or newer. Check with node --version.

2. Get the code and install dependencies:

   git clone https://github.com/godilman/agentbits.git
   cd agentbits
   npm ci

   npm ci downloads Electron and the other packages. Native modules come prebuilt, so you don’t need Visual Studio Build Tools or other compilers.

3. Start the app:

   npm run dev

npm run dev starts development mode and reloads when the code changes. To run a production build instead:

npm run build
npm start

Build the Windows installer yourself

On Windows you can build the installer locally:

npm ci
npm run dist:win

The result is release/Agentbits-Setup-<version>.exe (x64). Run npm ci first so the package is built from a clean install. The installer lets you choose who it is for and where to install, adds desktop and Start menu shortcuts, and shows the license. Like future published installers, it is unsigned, so expect the SmartScreen warning above.

If something goes wrong

• PowerShell says “running scripts is disabled on this system”: run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or use npm.cmd run dev instead.
• “Electron failed to install correctly”: the Electron download was interrupted. Run node node_modules\electron\install.js.

More fixes are in Troubleshooting.

Where your data lives

Everything Agentbits stores (organization, projects, chats, tasks, memory, reports, attached files, backups) is in one data folder on your computer:

System	Data folder
Windows	%APPDATA%\Agentbits
macOS	~/Library/Application Support/Agentbits
Linux	~/.config/Agentbits

The database is agentbits.db, with agentbits.db-wal and agentbits.db-shm next to it. Backups go to the backups folder and original attached files to files. To open the folder from the app, go to Settings → Data management and click Open folder.

Your project folders are separate. Agentbits never deletes them, and backups do not include them.

Use a separate test profile

Set the AGENTBITS_DATA_DIR environment variable to point Agentbits at another folder. Your normal data stays untouched, and an empty folder gives you a fresh first run.

$env:AGENTBITS_DATA_DIR = "$env:TEMP\agentbits-test"; npm run dev     # Windows PowerShell

AGENTBITS_DATA_DIR=/tmp/agentbits-test npm run dev                     # macOS / Linux

The folder is created if it doesn’t exist. Each data folder runs as its own app instance. Opening Agentbits a second time with the same data folder only brings the existing window to the front. To start the test profile over, close the app and delete that folder.

Tip: Use a test profile with the Demo provider to try templates, approvals, cleanup, backup and reset without risking your real data.

Update

Agentbits does not update itself.

• Installer: run the newer installer over the old version. You don’t need to uninstall first. Choose the same install option (for you only or for everyone) as the first time. Your data folder is kept, and the new version upgrades the database when it starts.

• From source: pull the new code, reinstall dependencies and start again:

  git pull
  npm ci
  npm run dev

Warning: Opening an upgraded database with an older version of Agentbits is not supported. Take a backup in Settings → Data management before you update.

Uninstall

Uninstalling Agentbits removes the app but keeps your data folder, so a later install picks up where you left off. If you also want to remove your data, delete the data folder listed above after uninstalling. This deletes your organization, projects, history and saved API keys. Project folders on disk are not affected.