Getting started

Bestie is a local-first AI companion. Install Bestie locally, then use the bestie command for setup, diagnostics, chat, and channels.

Prerequisites

• Node.js and npm.
• A checkout of the Bestie source repository.
• An OpenAI-compatible LLM provider.
• An API key stored in .bestie/.env, never in config.json.
• Optional: a Telegram bot token if you want the Telegram channel.

Install from the checkout

From the Bestie source repository:

./install.sh --skip-onboard
bestie onboard
bestie doctor

The installer defaults to ~/.local/share/bestie/source and exposes bestie from ~/.local/bin. Reinstalling preserves .bestie/ and refuses unknown existing install directories.

Common commands

After installation, use the bestie command:

bestie --help
bestie onboard
bestie onboard --skip-provider-test
bestie chat
bestie status
bestie logs
bestie doctor
bestie doctor --json
bestie doctor --fix

Inside terminal chat, useful commands include:

/help
/status
/memory
/memory pause
/memory resume
/pending

Verify the setup

Run Doctor after onboarding:

bestie doctor
bestie status

Provider troubleshooting

Start with:

bestie doctor
bestie status

Common failures:

• Provider request timed out: the endpoint responded too slowly. Try again, use a faster model, or increase llm.timeoutMs.
• Could not reach the provider endpoint: check llm.baseUrl, DNS, VPN/proxy settings, and provider availability.
• Provider authentication failed: check the API key in .bestie/.env and llm.apiKeyEnv in config.
• Provider rate limit reached: wait or check quota and billing with the provider.
• Provider returned an unusable response: confirm the model supports OpenAI-compatible chat completions.

Example timeout override:

{
  "llm": {
    "timeoutMs": 120000
  }
}

The default timeout is 60000 ms. Retry defaults are conservative: llm.maxRetries is 1 and llm.retryDelayMs is 500 ms.