# BangSo Bot [![GitHub stars](https://img.shields.io/github/stars/elie222/rakazo?labelColor=black&style=for-the-badge&color=2563EB)](https://github.com/elie222/rakazo/stargazers) [![Discord](https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?labelColor=black&style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/RWwKa2Sn7h) ![BangSo Bot — AI teammates you actually own](./docs/readme-hero.png) 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, and Docker. ```bash git clone https://github.com/elie222/rakazo.git cd rakazo cp .env.example .env ``` Set `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, and `SCREEN_PROXY_SECRET` in `.env` to independent long random values. Docker sandboxes also need a dedicated `SANDBOX_SUPERVISOR_TOKEN`. 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. ```bash docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d pnpm install pnpm db:generate pnpm db:migrate pnpm sandbox:build pnpm dev ``` After `.env` is configured, the same local startup sequence is available as: ```bash pnpm start:local ``` The script checks Docker and required tools, starts Postgres, prepares the database, builds the local computer image when missing, and then starts the API, worker, web app, and sandbox supervisor. 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= 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).