BitBuddy public alpha guide

Start here

Public alpha expectations

BitBuddy is public alpha software. It is meant for curious users who are comfortable running a local developer-style app and reporting rough edges. It is not a stable 1.0 product yet.

Start here

Requirements

Before installing, make sure the machine has these basics:

• Python 3.11+ for the BitBuddy backend.
• Node.js 18+ for the local Svelte dashboard.
• git so the installer can clone and update the source.
• A model provider, such as Ollama, llama.cpp, or an OpenAI-compatible endpoint.

Install

Installer commands

The public installer clones BitBuddy into your home directory, creates a Python virtual environment, installs dashboard dependencies, and creates a bitbuddy launcher.

macOS / Linux

curl -fsSL https://getbitbuddy.com/install.sh | bash

Windows PowerShell

irm https://getbitbuddy.com/install.ps1 | iex

If the installer says ~/.local/bin is not on your PATH, add the line it prints, restart the terminal, then run:

bitbuddy doctor

Install

Manual install from source

Use this path if you want to inspect every step or modify the source checkout yourself.

git clone https://github.com/bitbuddy-project/bitbuddy-brain.git ~/.bitbuddy/src/bitbuddy-brain
cd ~/.bitbuddy/src/bitbuddy-brain
python -m venv .venv
source .venv/bin/activate
pip install -e .
cd web
npm install
cd ..
bitbuddy doctor

On Windows, create and activate the virtual environment with PowerShell syntax instead:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

Setup

First run

Run setup once, start the backend, then open the tokenized dashboard URL:

bitbuddy setup
bitbuddy serve
bitbuddy dashboard

The setup wizard asks for a name, base personality, model provider, optional project memory, and optional calendar settings. It shows a summary before writing configuration.

Setup

Model providers

BitBuddy needs a chat-capable model. Local models keep more traffic on your machine, but larger hosted models may be more capable.

bitbuddy provider check
bitbuddy provider models
bitbuddy provider stream-test --prompt "Say hello briefly."

Setup

Dashboard and API token

The backend binds to 127.0.0.1:8787 by default. The dashboard runs on 127.0.0.1:5173 and sends an X-BitBuddy-Token header to protected API routes.

bitbuddy auth token
bitbuddy auth rotate

For LAN testing, start the backend with --allow-lan and keep the token private. Do not expose the plain HTTP backend directly to the internet.

Setup

Run as a background service

On Linux with user systemd, BitBuddy can keep the backend running after login.

bitbuddy service install
bitbuddy service enable
bitbuddy service status
bitbuddy service logs -f

The service runs the backend only. Open the UI with bitbuddy dashboard when you want to use it.

Features

Calendar

BitBuddy includes a local calendar view, reminders, holiday overlays, and assistant calendar tools. The authenticated dashboard can manage events; assistant calendar actions are governed by the assistant permission settings.

Configure calendar basics in Settings -> Calendar. If BitBuddy should use calendar context in chat or autonomy, review the assistant calendar access controls there too.

Features

Projects

Project memories let BitBuddy understand explicit project paths without broad home-directory access.

bitbuddy projects add my-project /path/to/project
bitbuddy projects index my-project
bitbuddy projects map my-project
bitbuddy projects list

BitBuddy indexes and summarizes project context into its own data under ~/.bitbuddy. File-writing tools are separate and require the relevant safety gates.

Features

Memory and continuity

BitBuddy keeps memory in layers: conversations, project context, preferences, skills, goals, and self/personality notes. You can inspect memories in the dashboard and use bitbuddy doctor to verify the local database.

Memory is local. There is no hosted BitBuddy account or cloud memory sync in the public alpha.

Features

Skills

Skills are reusable procedures stored locally under ~/.bitbuddy/skills. BitBuddy can list, load, validate, create, patch, and archive skills through confined tools.

Use skills for workflows you want BitBuddy to repeat consistently, such as debugging routines, frontend implementation checklists, or project-specific release steps.

Operate

Config and data locations

~/.bitbuddy/config.yaml       # local configuration
~/.bitbuddy/api_token         # local API token
~/.bitbuddy/bitbuddy.sqlite   # chats, memories, activity, permissions
~/.bitbuddy/projects          # per-project memory data
~/.bitbuddy/artifacts         # default generated artifact workspace
~/.bitbuddy/skills            # local skills
~/.bitbuddy/workspace         # BitBuddy-owned notes and drafts

Secrets such as provider keys and OAuth tokens are stored locally outside the main config file where possible.

Operate

Update BitBuddy

If you installed with the public installer, rerun the installer to update the source checkout and reinstall dependencies. For a manual checkout, pull and reinstall:

cd ~/.bitbuddy/src
git pull
source .venv/bin/activate
pip install -e .
cd web
npm install
cd ..
bitbuddy doctor

Operate

Uninstall or reset

To stop a Linux user service:

bitbuddy service disable
bitbuddy service stop

Remove the source checkout and launcher if you only want to uninstall the app code. Remove ~/.bitbuddy only if you also want to delete local memory, chats, config, tokens, and skills.

rm -rf ~/.bitbuddy/src
rm -f ~/.local/bin/bitbuddy

Help

Known limitations

• BitBuddy is an alpha and will continue changing after release.
• There is no hosted account, team mode, or cross-device sync.
• The physical body, desktop app, mobile app, and Devices page are roadmap items.
• Small local models may struggle with long context, tools, and multi-step work.
• LAN access is possible but should be treated as advanced local-network use, not internet exposure.