Skip to content

getting-started.md

Latest commit

 

History

History
148 lines (110 loc) · 3.82 KB

getting-started.md

File metadata and controls

148 lines (110 loc) · 3.82 KB
summary Get Bitterbot installed and run your first chat in minutes.
read_when
First time setup from zero
You want the fastest path to a working chat
title Getting Started

Getting Started

Goal: go from zero to a first working chat with minimal setup.

Fastest chat: open the Control UI (no channel setup needed). Run `bitterbot dashboard` and chat in the browser, or open `http://127.0.0.1:19001/` on the gateway host. Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).

Prereqs

  • Node 22 or newer
Check your Node version with `node --version` if you are unsure.

Quick setup (CLI)

```bash curl -fsSL https://bitterbot.ai/install.sh | bash ```

Install Script Process

```powershell iwr -useb https://bitterbot.ai/install.ps1 | iex ``` 
<Note>
Other install methods and requirements: [Install](/install).
</Note>
```bash bitterbot onboard --install-daemon ``` 
The wizard configures auth, gateway settings, and optional channels.
See [Onboarding Wizard](/start/wizard) for details.
If you installed the service, it should already be running: 
```bash
bitterbot gateway status
```
```bash bitterbot dashboard ``` If the Control UI loads, your Gateway is ready for use.

Run the Control UI

Bitterbot requires two processes: the gateway (backend) and the Control UI (frontend).

# Terminal 1 — Gateway
pnpm gateway:watch

# Terminal 2 — Control UI
cd desktop && pnpm dev

Open http://localhost:5173 in your browser to chat, view dreams, manage skills, and monitor the agent. The Control UI connects to the gateway on port 19001 automatically.

Optional extras

Requires a configured channel. 
```bash
bitterbot message send --target +15555550123 --message "Hello from Bitterbot"
```

P2P network

Bitterbot joins a decentralized P2P mesh for skill trading, reputation, and bounties. The orchestrator listens on TCP port 9100 by default.

Port 9100 open (inbound TCP) gives the best P2P performance, but is **not required**. Nodes behind NAT or firewalls automatically use circuit relay through the bootstrap node — no manual configuration needed.

See P2P configuration for relay mode, security, and advanced options.

Useful environment variables

If you run Bitterbot as a service account or want custom config/state locations:

  • BITTERBOT_HOME sets the home directory used for internal path resolution.
  • BITTERBOT_STATE_DIR overrides the state directory.
  • BITTERBOT_CONFIG_PATH overrides the config file path.

Full environment variable reference: Environment vars.

Go deeper

Full CLI wizard reference and advanced options.

What you will have

  • A running Gateway
  • Auth configured
  • Control UI access or a connected channel

Next steps

  • DM safety and approvals: Pairing
  • Connect more channels: Channels
  • Advanced workflows and from source: Setup