194 lines
8.2 KiB
Markdown
194 lines
8.2 KiB
Markdown
# BangSo Bot
|
|
|
|
[](https://github.com/elie222/rakazo/stargazers)
|
|
[](https://discord.gg/RWwKa2Sn7h)
|
|
|
|
|
|
|
|
BangSo Bot is an open-source platform for running persistent AI teammates. It is available on the web,
|
|
as an Electron desktop app, and through an Expo mobile app. Bring your own model and computer
|
|
provider, or run the complete stack locally.
|
|
|
|
BangSo Bot is in beta. Learn more at [rakazo.com](https://rakazo.com).
|
|
|
|
## Features
|
|
|
|
- Persistent bots with their own conversations, memory, routines, and history
|
|
- Voice mode: speak replies, dictate, and call a bot. Bring your own ElevenLabs, OpenAI, or Cartesia key
|
|
- Shared Team Computers and isolated Private computers
|
|
- Browser, terminal, file, and graphical desktop access
|
|
- Bots that can delegate to peer bots or short-lived subagents
|
|
- Bring-your-own model credentials through Pi
|
|
- App integrations through Composio or Pipedream Connect, plus user-installed Treg, remote MCP, and OpenAPI tool sources
|
|
- Docker, E2B, Daytona, Box, and trusted local-computer support
|
|
|
|
## Demo
|
|
|
|
https://github.com/user-attachments/assets/dccdeddb-2134-4a56-8eed-b2e591736b1c
|
|
|
|
## Stack
|
|
|
|
- TypeScript
|
|
- React 19, Vite, and Tailwind CSS
|
|
- Electron and Expo
|
|
- Hono and oRPC
|
|
- PostgreSQL and Prisma
|
|
- Better Auth
|
|
- Graphile Worker
|
|
- Pi
|
|
- Docker, E2B, Daytona, and Box
|
|
- Composio, Pipedream Connect, MCP, and OpenAPI integrations
|
|
|
|
## Quick start (published images)
|
|
|
|
You need Docker Engine, the Compose plugin, curl, and OpenSSL. No clone or Node install.
|
|
|
|
```bash
|
|
mkdir -p rakazo && cd rakazo &&
|
|
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh &&
|
|
bash install-images.sh
|
|
```
|
|
|
|
The installer downloads the Compose files, creates `.env` with random secrets, and starts BangSo Bot.
|
|
It preserves an existing `.env` when rerun.
|
|
|
|
Open [http://127.0.0.1:5173](http://127.0.0.1:5173), create an account, and connect a model.
|
|
Local Docker computers are on by default. Optional remote providers: `e2b`, `daytona`, or `box`
|
|
with the matching API key.
|
|
|
|
Default image tag is `edge` (main builds, `linux/amd64`). Details and tags:
|
|
[self-hosting guide](./docs/self-host.md#published-images-no-checkout).
|
|
|
|
For an agent-assisted install, use [SETUP_PROMPT.md](./SETUP_PROMPT.md).
|
|
|
|
## Local development (source checkout)
|
|
|
|
You need Node.js 22+, pnpm 9, Docker, and Make.
|
|
|
|
```bash
|
|
git clone https://github.com/elie222/rakazo.git
|
|
cd rakazo
|
|
make up
|
|
```
|
|
|
|
That is the local baseline: a `bangso` Linux account in the computer image, Traditional Chinese UI,
|
|
sudo on that account, and a rebuilt `rakazo/computer:local` image. `make up` copies `.env.example`
|
|
when `.env` is missing, injects blank secrets and computer defaults, then starts the stack at
|
|
[http://127.0.0.1:5173](http://127.0.0.1:5173).
|
|
|
|
Changeable values live in `.env`. Edit them, then run `make up` again. Leave a key blank and make
|
|
fills the local default (`COMPUTER_USER_PASSWORD=bangso`, `COMPUTER_ALLOW_SUDO=1`,
|
|
`VITE_DEFAULT_UI_LOCALE=zh-TW`) or a random secret. Values already set are left alone.
|
|
|
|
You can also set `OPENROUTER_API_KEY`, or connect a supported model provider during onboarding.
|
|
|
|
Managed app catalogs are optional. Set `COMPOSIO_API_KEY` for Composio, or the
|
|
`PIPEDREAM_CLIENT_ID`, `PIPEDREAM_CLIENT_SECRET`, and `PIPEDREAM_PROJECT_ID` trio for Pipedream
|
|
Connect. Users can add an HTTPS MCP server, Treg endpoint, or OpenAPI JSON document from
|
|
**Integrations** without enabling either managed catalog. Connector credentials are encrypted on the
|
|
server and are never returned by the API.
|
|
|
|
Treg is usage-metered. Self-hosters supply their own Treg token; operators embedding Treg in a
|
|
hosted product should review [Treg's integration terms](https://treg.to/integrate.md), which require
|
|
a written agreement for hosted resale.
|
|
|
|
`make down` stops local Postgres without deleting volumes. `make image` only rebuilds the computer
|
|
image. `pnpm start:local` is the same stack without forcing an image rebuild when the image already
|
|
exists.
|
|
|
|
To run the complete stack in Docker and expose only the web entry point to the local network, run
|
|
`pnpm start:docker-lan`. The script detects the Mac's LAN IPv4 address and prints the URL to open
|
|
from another device. API, Postgres, worker, supervisor, and sandbox ports remain private.
|
|
|
|
Open [http://127.0.0.1:5173](http://127.0.0.1:5173), create an account, connect a model, and create
|
|
your first bot.
|
|
|
|
For deployment, provider selection, backups, and upgrades, see the
|
|
[self-hosting guide](./docs/self-host.md).
|
|
|
|
## Desktop and mobile
|
|
|
|
The Electron and Expo apps are clients of the same BangSo Bot API used by the web app.
|
|
|
|
With the development stack running, launch Electron with:
|
|
|
|
```bash
|
|
pnpm --filter @rakazo/desktop dev
|
|
```
|
|
|
|
On first run the desktop app asks whether to use the BangSo Bot stack on this computer
|
|
(`http://127.0.0.1:5173`) or connect to an existing server. Public servers must use HTTPS; HTTP is
|
|
accepted only for loopback and private LAN addresses (not link-local). The app verifies BangSo Bot's
|
|
health endpoint before saving, and later launches go straight to that instance.
|
|
|
|
Use **Change BangSo Bot Server…** in the application menu to reconnect. Closing that window without
|
|
saving returns to the previous instance. For development automation, set `RAKAZO_WEB_URL` to point
|
|
the shell somewhere else without changing the saved instance, or `RAKAZO_FORCE_SETUP=1` to run
|
|
setup again.
|
|
|
|
Mobile build and release instructions live in [docs/mobile-release.md](./docs/mobile-release.md).
|
|
|
|
## Web UI language
|
|
|
|
The web (and Electron-hosted) UI supports English, Deutsch, 한국어, Türkçe, हिन्दी,
|
|
Português (Brasil), and 繁體中文. Change it under
|
|
**Settings → Language**. The marketing homepage (`apps/www`) is available in en/de/ko via
|
|
footer language links (`/`, `/de/`, `/ko/`); other marketing pages stay English.
|
|
|
|
## Development
|
|
|
|
BangSo Bot is a TypeScript monorepo built with React, Electron, Expo, Hono, Postgres, Prisma, Graphile
|
|
Worker, and Pi.
|
|
|
|
```text
|
|
apps/ web, api, worker, desktop, mobile, and public website
|
|
packages/ domain, contracts, persistence, adapters, UI, and test tooling
|
|
infra/ local services and computer images
|
|
docs/ architecture, operations, and release guides
|
|
```
|
|
|
|
Common checks:
|
|
|
|
```bash
|
|
pnpm lint
|
|
pnpm check
|
|
pnpm test
|
|
pnpm test:integration
|
|
pnpm test:e2e
|
|
```
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and test matrix.
|
|
|
|
## Documentation
|
|
|
|
```bash
|
|
pnpm test # unit, property, and in-process contract tests
|
|
pnpm test:integration # Postgres journeys, Graphile jobs, LISTEN/NOTIFY
|
|
pnpm test:e2e # Playwright against the emulated stack
|
|
pnpm test:e2e -- --sandbox=e2b # the same deterministic suite against real E2B
|
|
pnpm test:e2e -- --sandbox=daytona # the same suite against real Daytona
|
|
pnpm test:e2e -- --sandbox=box # the same suite against real Box
|
|
pnpm test:topology # local Docker + Graphile worker recovery (needs Docker)
|
|
pnpm test:canary # live OpenRouter / E2B / Box canaries
|
|
# explicit real vision-model + real E2B desktop acceptance test:
|
|
COMPUTER_E2E_MODEL=<vision-capable-openrouter-model-id> pnpm test:computer
|
|
```
|
|
|
|
- [Self-hosting](./docs/self-host.md)
|
|
- [Computer runtime and isolation](./docs/computer-runtime.md)
|
|
- [Mobile releases](./docs/mobile-release.md)
|
|
- [Performance testing](./docs/performance.md)
|
|
|
|
## Contributing
|
|
|
|
The Playwright workflow can also be started manually with **Sandbox provider** set to `e2b`, `daytona`, or `box`.
|
|
Those options require `E2B_API_KEY`, `DAYTONA_API_KEY`, or `BOX_API_KEY`, keep the deterministic scripted agent runtime, and destroy
|
|
the provider machines after the run. The default and all automatic runs remain on `fake`.
|
|
Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull
|
|
request. For security vulnerabilities, follow [SECURITY.md](./SECURITY.md) instead of filing a public
|
|
issue.
|
|
|
|
BangSo Bot is licensed under the [Apache License 2.0](./LICENSE).
|
|
|
|
Questions and ideas are welcome in the [BangSo Bot Discord community](https://discord.gg/RWwKa2Sn7h).
|