English | 简体中文

Rakazo 是一款开源的 AI Agent，旨在打造持久在线的 AI 队友，同时也是一个可在个人设备上运行的自托管 AI 助手。它提供 Web 端、Electron 桌面端应用，并支持 iPhone 和 Android。用户可以自带模型和计算环境提供商，也可以在本地运行完整技术栈。

它是 Grok Bot、Meta Muse、OpenAI Dots、Instinct、OpenClaw 以及 Hermes Agent 的开源、自托管替代方案。

Rakazo 目前处于测试阶段（Beta）。了解更多信息请访问 rakazo.com。

• 持久运行的机器人（Bot），拥有独立的对话、记忆、例行工作流与历史记录
• 语音模式：支持语音播报回复、语音听写和直接与机器人通话。可自带 ElevenLabs、OpenAI、Cartesia 或 Fish Audio 密钥
• 共享的团队计算机（Team Computers）与隔离的专用计算机（Private computers）
• 支持浏览器、终端、文件系统和图形桌面访问
• 支持向对等机器人或短期子 Agent 委派任务
• 通过 Pi 支持自带模型凭据（Bring-your-own model credentials）
• 支持通过 Composio 或 Pipedream Connect 集成第三方应用，并支持用户安装的 Treg、远程 MCP 以及 OpenAPI 工具源
• 支持 Docker、E2B、Daytona、CreateOS、Boat 以及受信任的本地计算机环境

视频/嵌入内容：演示视频

• TypeScript
• React 19、Vite 与 Tailwind CSS
• Electron 与 Expo
• Hono 与 oRPC
• PostgreSQL 与 Prisma
• Better Auth
• Graphile Worker
• Pi
• Docker、E2B、Daytona、CreateOS 和 Boat
• Composio、Pipedream Connect、MCP 与 OpenAPI 集成

快速开始（已发布镜像）

环境要求：Docker Engine、Compose 插件、curl 和 OpenSSL。无需克隆仓库或安装 Node。

bash mkdir -p rakazo && cd rakazo && curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh && bash install-images.sh

安装脚本会下载 Compose 文件，生成包含随机密钥的 .env，并启动 Rakazo。重复运行时会保留现有的 .env。

在浏览器中打开 http://127.0.0.1:5173，注册账户并连接模型。默认启用本地 Docker 计算机环境。可选的远程提供商包括：e2b、daytona、createos、boat 或 railway，需搭配对应的 API 密钥。

默认镜像标签为 edge（主分支构建，支持 linux/amd64 + linux/arm64）。详情和可用标签参见：自托管指南。

在受限网络环境下，可覆盖安装脚本下载源（RAKAZO_DOWNLOAD_BASE），跳过已存在的 Compose 文件（--local / RAKAZO_DOWNLOAD_SKIP_EXISTING），或镜像引导脚本 URL —— 详见受限网络 / 镜像下载。

如需在 Agent 辅助下完成安装，请参考 SETUP_PROMPT.md。

当后端在服务器上运行时，机器人将保持持续在线。可以在 VPS 上使用相同的安装脚本，然后通过桌面应用、移动应用或浏览器连接。

bash bash install-images.sh --prepare-only

编辑 .env：SANDBOX_PROVIDER=boat（或 e2b / daytona / createos）并填入 API 密钥，设置 RAKAZO_HOST=your.domain

bash install-images.sh

建议在 5173 端口前配置 HTTPS 反向代理；docs/self-host.md 介绍了 Caddy 配置及主机安全加固方案。在桌面应用中选择 Existing instance 并输入 https:// 地址即可。

也可以在 Railway 上一键部署；参考 Railway 配置指南。

本地开发（源码检出）

需要 Node.js 22.22.2 或 22.x 最新版、Node.js 24.x 或 Node.js 26+；pnpm 9；以及 Docker。不支持 Node.js 23.x 和 25.x。

bash git clone https://github.com/elie222/rakazo.git cd rakazo cp .env.example .env

运行 openssl rand -hex 16 生成两个随机值，分别赋给 POSTGRES_PASSWORD 和 POSTGRES_APP_PASSWORD，然后填入 DATABASE_MIGRATION_URL 和 DATABASE_URL。应用将以独立的 rakazo_app 用户身份连接，并受行级安全策略（Row-Level Security）约束；数据库迁移则以所有者身份运行（参见数据库角色文档）。将 BETTER_AUTH_SECRET、ENCRYPTION_KEY 和 SCREEN_PROXY_SECRET 设置为独立的随机长字符串。Docker 沙箱还需要配置专用的 SANDBOX_SUPERVISOR_TOKEN。你还可以设置 OPENROUTER_API_KEY，或在引导界面中连接支持的模型提供商。

如果使用 Docker Desktop 进行宿主机端开发，需在 .env 中设置 SANDBOX_CONTROL_VIA_LOOPBACK=true。Supervisor 会自动发现 Docker Desktop 的用户套接字；如使用其他 Docker 运行时，可通过 DOCKER_HOST 或 DOCKER_SOCKET 进行覆盖。

托管应用目录为可选项。如需 Composio 请设置 COMPOSIO_API_KEY；如需 Pipedream Connect 请配置 PIPEDREAM_CLIENT_ID、PIPEDREAM_CLIENT_SECRET 和 PIPEDREAM_PROJECT_ID 三项。用户无需启用这两个托管目录，也可以直接在 Integrations 中添加 HTTPS MCP 服务端、Treg 端点或 OpenAPI JSON 文档。连接器凭证在服务端加密存储，绝不会通过 API 返回。

Treg 按用量计费。自托管用户需自行提供 Treg Token；在托管商业产品中嵌入 Treg 的运营方应查阅 Treg 集成条款，该条款要求托管转售需签署书面协议。

bash docker compose --env-file .env
-f infra/compose/docker-compose.yml
-f infra/compose/docker-compose.postgres-host.yml
up postgres -d pnpm install pnpm db:generate pnpm db:migrate pnpm sandbox:build pnpm dev

在默认的 Compose 配置中，Postgres 仅限容器网络内部访问（与发布镜像保持一致）。postgres-host 覆盖层会将环回地址 127.0.0.1:5433 映射出来，供宿主机端的 pnpm 和数据库工具使用。若该端口被占用，请修改 .env 中的 POSTGRES_HOST_PORT 以及 DATABASE_URL 与 DATABASE_MIGRATION_URL 中的端口。如果不使用该覆盖层，可通过 docker compose --env-file .env -f infra/compose/docker-compose.yml exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' 打开 Shell。请使用 URI 安全的 POSTGRES_PASSWORD（openssl rand -hex 16）。已有的 pgdata 卷会保留初次初始化时的用户、密码和数据库，因此请在 .env 中保持这些值一致，或使用 ALTER ROLE / 重命名在数据库内就地修改。仅在备份后（或确认数据可废弃时）再重建数据卷；执行 docker compose down -v 会删除所有 Postgres 数据状态。

在浏览器中打开 http://127.0.0.1:5173，注册账户，连接模型，并创建你的第一个机器人。

关于部署、提供商选择、备份与升级，请参阅自托管指南。

若要使用 CreateOS，需设置 SANDBOX_PROVIDER=createos 和 CREATEOS_SANDBOX_API_KEY。可选配置 CREATEOS_SANDBOX_BASE_URL、CREATEOS_SANDBOX_SHAPE 和 CREATEOS_SANDBOX_ROOTFS 默认值分别为 https://api.sb.createos.sh、s-2vcpu-2gb 和 desktop:1。

若要使用 Railway 计算机，需在 API 和 Worker 上设置 SANDBOX_PROVIDER=railway、RAILWAY_API_TOKEN 和 RAILWAY_ENVIRONMENT_ID。请明确指定沙箱环境；Railway 自动生成的环境 ID 对应的是托管主应用的环境。建议使用权限范围最小的可用 Railway API Token：优先使用能够满足沙箱操作且被客户端认证支持的 Project Token。该提供商目前采用 Bearer 认证，因此建议使用 Team/Workspace Token 而非个人账户 Token。实时屏幕与桌面需要配置为 PRIVATE 网络模式，以便通过 Railway 的公共域名提供屏幕服务。计算机在此模式下运行，可以访问同属于该 Railway 项目/环境的其他服务以及公共互联网。官方建议为沙箱划分单独的 Railway 项目（或至少是独立环境），将其与主应用和数据库隔离开来。使用前请重新创建已有的 ISOLATED 计算机。桌面环境会在首次启动时自动安装。停止计算机时会保存可移植的 home 目录并销毁沙箱；下次启动时会在新的沙箱中恢复该 home 目录。Railway 沙箱按使用量计费。新计算机将在 Railway 默认区域启动，可通过设置 RAILWAY_SANDBOX_REGION（例如 asia-southeast1-eqsg3a）使其尽量靠近 API；运行中的计算机会在下次启动时迁移。工作区导出时会直接拒绝超过 64 MiB 的文件而非截断，可通过配置 RAILWAY_MAX_WORKSPACE_FILE_BYTES 调整该上限。

Electron 桌面应用和 Expo 移动应用与 Web 应用共用同一套 Rakazo API。

在开发技术栈运行的情况下，启动 Electron：

bash pnpm --filter @rakazo/desktop dev

首次运行时，桌面应用会询问是在当前设备运行 Rakazo 还是连接至现有服务器。选择 This computer 将通过 Docker Compose（与 infra/compose/install-images.sh 相同的文件）在应用数据目录下安装并启动已发布的镜像，因此必须预先安装 Docker Desktop、OrbStack 或 Docker Engine；若未安装，应用会提供下载链接。正式安装版本会锁定为其自身对应的镜像版本；开发源码构建则拉取 edge。运行 pnpm dev 的开发者应选择 Existing instance 并填入 http://127.0.0.1:5173。公共服务器必须使用 HTTPS；仅环回地址和私有局域网地址允许使用 HTTP（不支持链路本地地址 link-local）。应用在保存前会校验 Rakazo 的健康检查端点，后续启动将直接进入该实例。应用退出后后台服务仍会保持运行；可通过应用菜单中的 Stop Local Stack 将其停止。

在 Linux 上，桌面应用以 AppImage 格式发布，需要依赖 FUSE 2（libfuse.so.2）。仅包含 FUSE 3 的发行版（如 Fedora Silverblue 或 Ubuntu 24.04）会报错 dlopen(): error loading libfuse.so.2。请安装 FUSE 2 库（Fedora 上为 fuse-libs，Ubuntu 24.04 上为 libfuse2t64，旧版 Ubuntu/Debian 上为 libfuse2），或在不使用 FUSE 的情况下运行 AppImage：

bash chmod +x Rakazo-.AppImage ./Rakazo-.AppImage --appimage-extract-and-run

This computer 选项会检查 docker CLI，目前无法检测 Podman。若想尝试其他支持 compose 命令且兼容 Docker 的 CLI，请在启动应用前将 RAKAZO_DOCKER_BINARY 设置为其路径。

使用应用菜单中的 Change Rakazo Server… 可重新连接。关闭该窗口而不保存将返回上一个实例。如需自动化开发配置，可设置 RAKAZO_WEB_URL 指向其他地址而不更改已保存实例，或设置 RAKAZO_FORCE_SETUP=1 强制重新执行初始化配置向导。

移动端构建与发布说明请参阅 docs/mobile-release.md。

Web 端（及 Electron 托管）界面在 Settings → Language 下支持英语、德语、韩语、土耳其语、印地语、葡萄牙语（巴西）、简体中文、西班牙语、俄语、法语、希伯来语和荷兰语。Expo 应用内置了英语、简体中文、俄语、德语和荷兰语五种语言包，可在 Account → Language 中切换。在用户保存选择前，系统会根据设备语言或 EXPO_PUBLIC_DEFAULT_UI_LOCALE 选用初始语言包。营销官网（apps/www）通过页脚语言链接提供 en/de/ko/zh 版本（/、/de/、/ko/、/zh/）；其他营销页面目前保持英文。俄文营销首页与原生 Electron 安装向导/菜单的本地化工作正在跟进中。

text apps/ Web、API、Worker、桌面端、移动端及公共网站 packages/ 领域模型、协议契约、持久化层、适配器、UI 和测试工具 infra/ 本地服务与计算机环境镜像 docs/ 系统架构、运维与发布指南

常用检查命令：

bash pnpm lint pnpm check pnpm test pnpm test:integration pnpm test:e2e

开发工作流与测试矩阵参见 CONTRIBUTING.md。

欢迎参与社区贡献。在提交 Pull Request 之前，请阅读 CONTRIBUTING.md。如发现安全漏洞，请遵循 SECURITY.md 的指引进行提交，切勿发布公开 Issue。

Rakazo 基于 Apache License 2.0 开源许可协议分发。

如有任何问题和建议，欢迎提交探讨。

English | 简体中文

Rakazo is an open source AI agent for persistent teammates, and a self-hosted AI assistant you can run on your own machine. It is available on the web, as an Electron desktop app, and on iPhone and Android. Bring your own model and computer provider, or run the complete stack locally.

It is an open source, self-hosted alternative to Grok Bot, Meta Muse, OpenAI Dots, Instinct, OpenClaw, and Hermes Agent.

Rakazo is in beta. Learn more at rakazo.com.

• Persistent bots with their own conversations, memory, routines, and history
• Voice mode: speak replies, dictate, and call a bot. Bring your own ElevenLabs, OpenAI, Cartesia, or Fish Audio 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, CreateOS, Boat, and trusted local-computer support

demo.mp4

• TypeScript
• React 19, Vite, and Tailwind CSS
• Electron and Expo
• Hono and oRPC
• PostgreSQL and Prisma
• Better Auth
• Graphile Worker
• Pi
• Docker, E2B, Daytona, CreateOS, and Boat
• 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.

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 Rakazo. It preserves an existing .env when rerun.

Open 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, createos, boat, or railway with the matching API key.

Default image tag is edge (main builds, linux/amd64 + linux/arm64). Details and tags: self-hosting guide.

On restricted networks, override the installer download base (RAKAZO_DOWNLOAD_BASE), skip existing Compose files (--local / RAKAZO_DOWNLOAD_SKIP_EXISTING), or mirror the bootstrap script URL — see Restricted networks / mirror downloads.

For an agent-assisted install, use SETUP_PROMPT.md.

Bots stay on when the backend runs on a server. Use the same installer on a VPS, then connect from the desktop app, the mobile app, or a browser.

bash install-images.sh --prepare-only
# edit .env: SANDBOX_PROVIDER=boat (or e2b / daytona / createos) with its API key, RAKAZO_HOST=your.domain
bash install-images.sh

Put HTTPS in front of port 5173; docs/self-host.md covers the Caddy setup and host hardening. In the desktop app choose Existing instance and enter the https:// address.

Or deploy on Railway; see the Railway setup guide.

Local development (source checkout)

You need Node.js 22.22.2 or newer in the 22.x line, Node.js 24.x, or Node.js 26+; pnpm 9; and Docker. Node.js 23.x and 25.x are not supported.

git clone https://github.com/elie222/rakazo.git
cd rakazo
cp .env.example .env

Set POSTGRES_PASSWORD and POSTGRES_APP_PASSWORD to two values from openssl rand -hex 16, then put them in DATABASE_MIGRATION_URL and DATABASE_URL. The app connects as its own rakazo_app login, which row-level security applies to; migrations run as the owner (database roles). Set BETTER_AUTH_SECRET, ENCRYPTION_KEY, and SCREEN_PROXY_SECRET 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.

For host-side development with Docker Desktop, set SANDBOX_CONTROL_VIA_LOOPBACK=true in .env. The supervisor discovers Docker Desktop's user socket automatically; DOCKER_HOST or DOCKER_SOCKET can override it for another Docker runtime.

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, which require a written agreement for hosted resale.

docker compose --env-file .env \
  -f infra/compose/docker-compose.yml \
  -f infra/compose/docker-compose.postgres-host.yml \
  up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build
pnpm dev

Postgres stays network-internal in the default Compose file (same as published images). The postgres-host overlay publishes loopback 127.0.0.1:5433 for host-side pnpm and DB tools. If that port is occupied, change POSTGRES_HOST_PORT and the ports in DATABASE_URL and DATABASE_MIGRATION_URL in .env. Without the overlay, open a shell with docker compose --env-file .env -f infra/compose/docker-compose.yml exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'. Use a URI-safe POSTGRES_PASSWORD (openssl rand -hex 16). An existing pgdata volume keeps the user, password, and database from first init, so keep those values in .env, or change them in place with ALTER ROLE / rename. Recreate the volume only after a backup (or when the data is disposable); docker compose down -v deletes all Postgres state.

Open 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.

To use CreateOS, set SANDBOX_PROVIDER=createos and CREATEOS_SANDBOX_API_KEY. Optional CREATEOS_SANDBOX_BASE_URL, CREATEOS_SANDBOX_SHAPE, and CREATEOS_SANDBOX_ROOTFS default to https://api.sb.createos.sh, s-2vcpu-2gb, and desktop:1.

To use Railway computers, set SANDBOX_PROVIDER=railway, RAILWAY_API_TOKEN and RAILWAY_ENVIRONMENT_ID on the API and worker. Choose the sandbox environment explicitly; Railway's automatic environment ID identifies the hosted app's environment. Use the narrowest Railway API token that works: prefer a project token if sufficient for sandbox operations and supported by the client's authentication. This provider currently uses bearer authentication, so use a team/workspace token rather than a personal account token. The live screen and desktop require PRIVATE networking so Railway's public domain can serve the screen. Computers use this mode and can reach other services in the same Railway project/environment, as well as the public internet. We recommend a dedicated Railway project (or at least a separate environment) for sandboxes, separate from the app and database. Recreate existing ISOLATED computers before use. The desktop is installed on first start. Stopping a computer saves its portable home and destroys the sandbox; the next start restores that home in a new sandbox. Railway sandbox usage is metered. New computers start in Railway's default region. Set RAILWAY_SANDBOX_REGION (for example asia-southeast1-eqsg3a) to keep them near the API; a running computer moves on its next start. Workspace exports reject files above 64 MiB without truncating them. Set RAILWAY_MAX_WORKSPACE_FILE_BYTES to change this limit.

The Electron and Expo apps are clients of the same Rakazo API used by the web app.

With the development stack running, launch Electron with:

pnpm --filter @rakazo/desktop dev

On first run the desktop app asks whether to run Rakazo on this computer or connect to an existing server. This computer installs and starts the published images with Docker Compose (the same files as infra/compose/install-images.sh) under the app's data directory, so Docker Desktop, OrbStack, or Docker Engine must be installed; the app links to them when it is not. Installed builds pin the image tag to their own version; unpackaged builds pull edge. Developers running pnpm dev should pick Existing instance with http://127.0.0.1:5173 instead. Public servers must use HTTPS; HTTP is accepted only for loopback and private LAN addresses (not link-local). The app verifies Rakazo's health endpoint before saving, and later launches go straight to that instance. The stack keeps running after the app quits; Stop Local Stack in the application menu turns it off.

On Linux the desktop app ships as an AppImage, which needs FUSE 2 (libfuse.so.2). Distributions that only include FUSE 3, such as Fedora Silverblue or Ubuntu 24.04, show dlopen(): error loading libfuse.so.2. Install the FUSE 2 library (fuse-libs on Fedora, libfuse2t64 on Ubuntu 24.04, libfuse2 on older Ubuntu and Debian), or run the AppImage without FUSE:

chmod +x Rakazo-*.AppImage
./Rakazo-*.AppImage --appimage-extract-and-run

This computer looks for the docker CLI and does not detect Podman. To try another Docker-compatible CLI that supports the compose commands, set RAKAZO_DOCKER_BINARY to its path before starting the app.

Use Change Rakazo 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.

The web (and Electron-hosted) UI supports English, Deutsch, 한국어, Türkçe, हिन्दी, Português (Brasil), 简体中文, Español, Русский, Français, עברית, and Nederlands under Settings → Language. The Expo app ships English, 简体中文, Русский, Deutsch, and Nederlands catalogs, and Account → Language lists all five. A device language or EXPO_PUBLIC_DEFAULT_UI_LOCALE still selects the starting catalog before a saved choice. The marketing homepage (apps/www) is available in en/de/ko/zh via footer language links (/, /de/, /ko/, /zh/); other marketing pages stay English. The Russian marketing homepage and native Electron setup/menu remain separate follow-up work.

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:

pnpm lint
pnpm check
pnpm test
pnpm test:integration
pnpm test:e2e

See CONTRIBUTING.md for the development workflow and test matrix.

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request. For security vulnerabilities, follow SECURITY.md instead of filing a public issue.

Rakazo is licensed under the Apache License 2.0.

Questions and ideas are welcome in the Rakazo Discord community.