Getting started

Bestie is a local-first AI companion and controlled action runtime. Install it locally, connect an LLM provider, verify the setup with Doctor, then use terminal chat, channels, cron, tools, memory, and the local web console from the bestie CLI.

Install

Use the public npm package for normal installs.

Configure

Run onboarding. Store secrets in `~/.bestie/.env`, not in config JSON.

Verify

Run Doctor before trusting chat, channels, cron, memory, MCP, or tools.

Operate

Use chat, Telegram, Zalo, cron, daemon/service, and `bestie ui` when the local runtime is healthy.

Prerequisites

• Node.js 24+ and npm.
• Permission to install a global npm package.
• An LLM provider supported by bestie llm setup, such as OpenAI, Anthropic, Gemini, OpenRouter, Groq, Ollama, or a custom compatible endpoint.
• An API key stored in ~/.bestie/.env, never in ~/.bestie/config.json.
• Optional: Telegram or Zalo bot credentials for channel runtimes.

At minimum, your env file should contain the variable referenced by the active LLM profile’s apiKeyEnv:

OPENAI_API_KEY=sk-your-key-here

Use the real key for your provider and keep it out of screenshots, logs, issues, and docs.

Secret rule: config files should name environment variables; only `~/.bestie/.env` should contain provider keys or bot tokens.

Install from npm

npm install -g bestie-agent
bestie onboard
bestie doctor

The package exposes the bestie command.

Install with curl

The source installer installs the npm package and then hands off to onboarding. Use it when you prefer the one-line bootstrap path:

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

If you prefer to inspect the script first:

curl -fsSL https://www.bestieagent.com/install.sh -o install.sh
cat install.sh
bash install.sh

Common setup commands

bestie --help
bestie onboard
bestie onboard --skip-provider-test
bestie llm providers
bestie llm setup --provider openai --set-default
bestie llm setup --provider gemini --set-default
bestie llm test --model openai/gpt-4.1
bestie status
bestie logs
bestie doctor
bestie doctor --json
bestie doctor --fix

--skip-provider-test creates local files without making the provider test call. Treat setup as incomplete until Doctor passes.

Start chatting

Run terminal chat:

bestie chat

Useful terminal chat commands:

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

Try a small first message:

Summarize your current status in one sentence.

Open the local web console

Bestie includes a local web console for runtime status, Doctor, providers, character, memory, channels, approvals, MCP, tools, and settings.

bestie ui

For terminal-only or smoke-friendly runs:

bestie ui --no-open
bestie ui --port 8717
bestie ui --port 0 --no-open

The UI uses the same ~/.bestie/ runtime files as the CLI and must not return raw .env values.

Add channels

Configure Telegram:

bestie channels telegram setup
bestie channels telegram whoami
bestie channels telegram

Configure Zalo:

bestie channels zalo setup
bestie channels zalo --once
bestie channels zalo

Run channel diagnostics:

bestie channels doctor
bestie channels doctor --channel telegram --connect
bestie channels doctor --channel zalo --connect

Run background targets

Use daemon mode for manual background processes:

bestie daemon start --channel telegram
bestie daemon start --channel zalo
bestie daemon start --channel cron
bestie daemon status --channel all

Use the user service when the operating system should start configured targets for you:

bestie service install
bestie service status
bestie service restart

Avoid running daemon and service for the same target at the same time.

Verify the setup

bestie doctor
bestie status
bestie memory status
bestie channels doctor

A healthy first setup should have valid config, required env vars present, readable character files, writable logs, and a working provider profile.

Provider troubleshooting

Start with:

bestie doctor
bestie status
bestie llm test --model <provider/model>

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 the active profile’s baseUrl, DNS, VPN/proxy settings, and provider status.
• Provider authentication failed: check the API key in ~/.bestie/.env and the active profile’s apiKeyEnv.
• Provider rate limit reached: wait or check quota and billing.
• Provider returned an unusable response: confirm the selected model ref is supported by the configured provider profile.

Example timeout override:

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

The default timeout is 300000 ms. Set a lower or higher value only when your provider and operating constraints call for it. Retry defaults are conservative: llm.maxRetries is 1 and llm.retryDelayMs is 500 ms.