The Problem

Teams that want an “own‑your‑model” AI assistant need a self‑hosted stack that can run a language model, a sandboxed desktop, and persistent state without locking them into a proprietary control plane. Existing “Grok Bot”‑style products either require a cloud service or expose secret keys in the client.

What This Does

rakazo delivers a full‑stack, open‑source alternative. The core API lives in apps/api/src/ (app.ts, router.ts, index.ts) and exposes HTTP endpoints that the web, desktop, and mobile front‑ends consume. The sandbox layer lives under packages/adapters/, where src/computer-support.ts and src/sandbox-factory.ts create the Docker‑based or E2B‑based sandbox instances. UI code is split across apps/web/ (React 19/Vite), apps/desktop/ (Electron) and apps/mobile/ (Expo). Persistence is handled by Postgres via Prisma and Graphile Worker (see apps/api/src/thread-message-pages.ts and the worker package).

How It Is Wired

Execution starts at apps/api/src/app.ts, which builds a Hono server, registers routes from router.ts, and starts listening on port 3100. The request flow is:

  1. HTTP request → Hono router (apps/api/src/router.ts).
  2. Route handler calls service layer in apps/api/src/thread-message-pages.ts, which interacts with the database (Prisma client) and enqueues background jobs via Graphile Worker.
  3. When a bot needs to run code, the service invokes packages/adapters/src/index.ts (the hub module). This file imports 34 other adapters but does not import back, giving it an instability of 1.
  4. The sandbox request is delegated to packages/adapters/src/sandbox-factory.ts, which selects a provider (docker or e2b) and constructs a sandbox instance (packages/adapters/src/e2b-sandbox.ts or .../docker-sandbox.ts).
  5. The sandbox runs the command through packages/adapters/src/executor.ts, the most line‑dense file (≈1 269 lines). Its output is streamed back to the API, stored in Postgres, and pushed to the client via oRPC (apps/web/src/lib/rpc.ts).

Key blast‑radius modules:

  • packages/adapters/src/index (34 outgoing imports) – any change ripples to most adapters.
  • apps/mobile/lib/api.ts (11 inbound imports) – central for mobile client‑API calls.
  • packages/adapters/src/computer-support.ts (13 inbound imports) – a hub for computer‑related logic.

No circular dependencies were detected, and the import graph contains 231 modules with 295 edges.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/rakazo
cd rakazo

# Prepare environment
cp .env.example .env
# Edit .env: set BETTER_AUTH_SECRET, ENCRYPTION_KEY, OPENROUTER_API_KEY, optional COMPOSIO_API_KEY

# Start required services
docker compose -f infra/compose/docker-compose.yml up postgres -d

# Install, generate DB artefacts, and run
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build
pnpm dev          # launches API, Graphile Worker, Vite web app, and sandbox supervisor

The API is reachable at http://127.0.0.1:3100/health, which should return "runtime":"pi", "sandbox":"docker", "jobs":"graphile", "realtime":"postgres".

Real‑World Use

A SaaS product that needs a controllable AI “assistant” can embed the web client (apps/web/src/App.tsx) and point it at a self‑hosted API instance. When a user triggers a bot action, the request travels through the Hono router, hits thread-message-pages.ts, spawns a sandbox via the adapter hub, runs the model in Pi, and streams screen updates back to the client via oRPC. The same backend powers the Electron desktop and Expo mobile apps without code duplication.

Code Health & Issues

Measured findings (static analysis)

  • HIGH – Oversized files: packages/adapters/src/executor.ts, e2b-sandbox.ts, pi-runtime.ts (≈1 269 lines each).
  • MEDIUM – Hub module: packages/adapters/src/computer-support.ts (13 inbound imports).
  • HIGH – Duplicated code: repeated 6‑line blocks across apps/api/src/app.ts, apps/worker/src/index.ts, apps/api/src/router.ts, packages/adapters/src/child-bots.ts.
  • MEDIUM – High branching density: pi-runtime.ts, computer-tools.ts, pi-credentials.ts.
  • HIGH – Deep nesting: apps/www/src/components/ProductDemo.tsx, apps/web/src/pages/Onboarding.tsx, apps/web/src/pages/Shell.tsx.

Repository health audit

  • CRITICAL – Secrets in workflow (.github/workflows/publish-playwright-report.yml).
  • HIGH – Unpinned third‑party actions (pnpm/action-setup@v4).
  • MEDIUM – No Dependabot/Renovate config.
  • MEDIUM – Docker base image not pinned by digest (infra/compose/Dockerfile).
  • MEDIUM – No dependency‑vulnerability scan in CI.
  • MEDIUM – actions/checkout runs with persisted token; should set persist-credentials: false.
  • LOW – Missing convention files (.editorconfig, .gitattributes, formatter config).

Additional observations: test suite present (94 files) and CI via GitHub Actions, but the repository commits secrets and lacks automated dependency updates.

The Bottom Line

rakazo provides a complete, self‑hostable AI‑assistant stack with clear separation between API, sandbox adapters, and multi‑platform clients. The codebase is functional but suffers from very large, branching‑heavy files and a few security hygiene gaps that should be fixed before production use. It is suitable for teams comfortable managing Docker, Postgres, and TypeScript monorepos and willing to address the identified health issues.