README
¶
OpenVaala
A self-hostable, general-purpose agent system: one runtime for the agent loop, tools on the machines you choose, and the same live conversations in every client.
English | 简体中文 · Documentation · Quickstart
Why OpenVaala
OpenVaala keeps the agent loop, tool execution and the interfaces apart — a centralized agent loop with distributed tool execution.
- One runtime, many machines. The runtime server manages each task's progress and context, while file edits and commands run on the executors you pick: this machine, a built-in sandbox, and any number of SSH hosts such as a build box, a GPU machine or a staging server. One conversation can use several of them, choosing the machine for each tool call. Executors are a pluggable layer; workers on other machines and hosted sandboxes are planned.
- Many clients, one live conversation. The terminal UI, the web UI (on your phone too), the desktop app, editors over ACP such as Zed, and Codex clients — the Codex terminal UI and desktop app — attach to the same runtime and the same conversations. Start in the terminal, check from your phone, finish in your editor; streaming output, queued messages and tool results are shared, not just the chat log.
- Works with what you have. Models over OpenAI Chat Completions, OpenAI Responses or Claude Messages; clients over ACP and the Codex app-server protocol; tools over MCP. Swap one piece without rebuilding the rest.
- Conversations you can take with you. Each conversation is its own directory of JSONL records, indexed by a SQLite database that can be rebuilt at any time. Read it, back it up or move it to another machine. Storage is pluggable by design.
Install
OpenVaala runs on Linux and macOS (amd64 and arm64).
-
GitHub Releases — download the
openvaalabinary for your platform, which includes the web UI, or a desktop package for macOS or Linux, from Releases. -
go install — the command-line tool with the web UI from the latest release:
go install github.com/VaalaCat/openvaala/cmd/openvaala@latest -
From source —
script/build.shbuilds the CLI with the web UI (Go 1.27.3+, Node.js 24+, pnpm);script/build-desktop.shbuilds the desktop app.
See Install for details.
Quickstart
-
Start the terminal UI in a project directory. The first run walks you through adding a model provider:
cd ~/code/my-project openvaala -
Type a request, such as "Explain how this project is built and run its tests", and watch the agent work. Press Enter to steer it while it runs, Tab to queue a follow-up, Esc twice to interrupt.
-
Open the same conversation in your browser:
openvaala web
OpenVaala runs tools without asking for confirmation; start somewhere you are comfortable letting an agent work, and use hooks to add checks.
Documentation
- Getting started — install, add a model, first conversation.
- Guides — conversations, the terminal, web and desktop interfaces, editors and Codex.
- Configuration — models, agents, executors, tools, skills, MCP servers, hooks and plugins.
- Reference — every command and flag, and the architecture.
The documentation also ships inside OpenVaala as a built-in skill, so you can ask an agent how to configure it.
Status
OpenVaala is under active development and has not reached 1.0. Configuration, the runtime protocol and public APIs may change between releases.
License
OpenVaala is released under the MIT License. Third-party notices are in www/THIRD_PARTY_NOTICES.md and resources/licenses/.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openvaala
command
|
|
|
openvaala-desktop
command
|
|
|
Package docs 保存 OpenVaala 的使用文档，同一份 Markdown 供文档站和内置 skill 使用。
|
Package docs 保存 OpenVaala 的使用文档，同一份 Markdown 供文档站和内置 skill 使用。 |
|
examples
|
|
|
load-config
command
本示例加载配置，查询并打印 Agent 和模型。
|
本示例加载配置，查询并打印 Agent 和模型。 |
|
internal
|
|
|
appserver
Package appserver 用 Codex app-server 协议服务 Codex 客户端（Codex TUI、Paseo）：每条 Codex 连接经 runtimeclient 连共享的 serve（本机的，或命令行、配置指定的远端），把 Codex 请求翻译成 OpenVaala 协议，再把 OpenVaala 事件翻译成 Codex 通知。
|
Package appserver 用 Codex app-server 协议服务 Codex 客户端（Codex TUI、Paseo）：每条 Codex 连接经 runtimeclient 连共享的 serve（本机的，或命令行、配置指定的远端），把 Codex 请求翻译成 OpenVaala 协议，再把 OpenVaala 事件翻译成 Codex 通知。 |
|
cli
Package cli 定义 openvaala 命令行：加载配置，运行 TUI、serve、web、acp、app-server、codex、reindex、plugin 和 config 命令。
|
Package cli 定义 openvaala 命令行：加载配置，运行 TUI、serve、web、acp、app-server、codex、reindex、plugin 和 config 命令。 |
|
config
Package config 加载应用设置和 Agent、Provider 定义。
|
Package config 加载应用设置和 Agent、Provider 定义。 |
|
desktop
Package desktop 绘制原生工作台并连接本机 Runtime Server。
|
Package desktop 绘制原生工作台并连接本机 Runtime Server。 |
|
e2e/desktopdrive
command
Command desktopdrive 是给 AI 代理用的“原生桌面版 agent-browser”：在无显示的 Linux 上起一个真实的 OpenVaala 桌面， 让代理在 shell 里一步一步读控件树、点按钮、输入文字、按键、选菜单、截图。
|
Command desktopdrive 是给 AI 代理用的“原生桌面版 agent-browser”：在无显示的 Linux 上起一个真实的 OpenVaala 桌面， 让代理在 shell 里一步一步读控件树、点按钮、输入文字、按键、选菜单、截图。 |
|
e2e/webuifixture
command
Command webuifixture 为 WebUI 的 Playwright 端到端测试准备真实环境：用 --openvaala 指定的已编译二进制 （嵌入 www/out/web 里刚构建的页面），在临时 HOME 启动 serve 和可控的假模型，把连接信息写进 --out 指定的状态文件，阻塞到收到 SIGTERM、SIGINT 或 stdin 管道关闭， 退出前停掉 serve 并删除临时目录。
|
Command webuifixture 为 WebUI 的 Playwright 端到端测试准备真实环境：用 --openvaala 指定的已编译二进制 （嵌入 www/out/web 里刚构建的页面），在临时 HOME 启动 serve 和可控的假模型，把连接信息写进 --out 指定的状态文件，阻塞到收到 SIGTERM、SIGINT 或 stdin 管道关闭， 退出前停掉 serve 并删除临时目录。 |
|
protocolgen
command
命令 protocolgen 把 pkg/runtimeprotocol 的线上协议类型生成为前端使用的 TypeScript 文件。
|
命令 protocolgen 把 pkg/runtimeprotocol 的线上协议类型生成为前端使用的 TypeScript 文件。 |
|
runtimeclient
Package runtimeclient 是 OpenVaala 协议的 Go 客户端：保持一条到 Runtime Server 的 WebSocket 连接， 断线后退避重连，并为打开的对话补齐断线期间的内容。
|
Package runtimeclient 是 OpenVaala 协议的 Go 客户端：保持一条到 Runtime Server 的 WebSocket 连接， 断线后退避重连，并为打开的对话补齐断线期间的内容。 |
|
tui
Package tui 是 OpenVaala 的终端界面：inline 模式，已定稿的内容按顺序写进终端 scrollback，横向缩放时按新宽度重建， 底部实时区域每帧重绘尾部或面板、状态行、排队预览、输入框与 footer；只通过 runtimeclient 与 Runtime 交互。
|
Package tui 是 OpenVaala 的终端界面：inline 模式，已定稿的内容按顺序写进终端 scrollback，横向缩放时按新宽度重建， 底部实时区域每帧重绘尾部或面板、状态行、排队预览、输入框与 footer；只通过 runtimeclient 与 Runtime 交互。 |
|
pkg
|
|
|
dao
Package dao 按对话、Session、Turn、Item 读写存储，读和写分成 Query、Mutation 两组接口。
|
Package dao 按对话、Session、Turn、Item 读写存储，读和写分成 Query、Mutation 两组接口。 |
|
hook
Package hook 运行用户配置的 hook：按事件找出命中的 hook，在事件所在的 Executor 上并行运行， 解析它们的输出并合并成一个决定。
|
Package hook 运行用户配置的 hook：按事件找出命中的 hook，在事件所在的 Executor 上并行运行， 解析它们的输出并合并成一个决定。 |
|
mcpclient
Package mcpclient 定义 MCP server 配置，在执行环境的工作区里连接 MCP server，并经客户端连接转发客户端侧 MCP server 的消息。
|
Package mcpclient 定义 MCP server 配置，在执行环境的工作区里连接 MCP server，并经客户端连接转发客户端侧 MCP server 的消息。 |
|
prompt
Package prompt 生成发给模型的内置提示文本：系统提示里的各个块、工具说明，以及插进对话的通知。
|
Package prompt 生成发给模型的内置提示文本：系统提示里的各个块、工具说明，以及插进对话的通知。 |
|
runtime
Package runtime 提供一个进程内 OpenVaala 的公开根入口：按 ConversationID 路由多个对话并订阅其事件。
|
Package runtime 提供一个进程内 OpenVaala 的公开根入口：按 ConversationID 路由多个对话并订阅其事件。 |
|
runtimeprotocol
Package runtimeprotocol 是 serve 与客户端共用的 OpenVaala 线上协议类型、方法表和通知表。
|
Package runtimeprotocol 是 serve 与客户端共用的 OpenVaala 线上协议类型、方法表和通知表。 |
|
runtimeserver
Package runtimeserver 是 Runtime 外层的网络协议宿主：把 WebSocket 连接上的 JSON-RPC 请求转换为 Runtime 公开调用， 并把订阅事件推送为通知。
|
Package runtimeserver 是 Runtime 外层的网络协议宿主：把 WebSocket 连接上的 JSON-RPC 请求转换为 Runtime 公开调用， 并把订阅事件推送为通知。 |
|
skill
Package skill 解析通用 Agent Skills 格式（SKILL.md），按目录优先级生成去重、排序的 skill 目录， 显式引用时由 Session 读取正文；模型也可按 Path 用通用工具读取。
|
Package skill 解析通用 Agent Skills 格式（SKILL.md），按目录优先级生成去重、排序的 skill 目录， 显式引用时由 Session 读取正文；模型也可按 Path 用通用工具读取。 |
|
storage
Package storage 定义 JSON 记录和追加日志的读写接口。
|
Package storage 定义 JSON 记录和追加日志的读写接口。 |
|
telemetry
Package telemetry 是全项目统一的遥测出口：trace、指标与日志经同一条管道写出，实体身份经 ctx 下传。
|
Package telemetry 是全项目统一的遥测出口：trace、指标与日志经同一条管道写出，实体身份经 ctx 下传。 |
|
telemetry/telemetrytest
Package telemetrytest 提供写入内存的遥测管道，供各包测试断言 span、指标与日志；与 net/http/httptest 同类。
|
Package telemetrytest 提供写入内存的遥测管道，供各包测试断言 span、指标与日志；与 net/http/httptest 同类。 |
|
terminal
Package terminal 管一个 Session 里后台命令的进程、输出、输入、时限和容量，不认识模型和 JSON。
|
Package terminal 管一个 Session 里后台命令的进程、输出、输入、时限和容量，不认识模型和 JSON。 |
|
turn
Package turn 执行一轮 Agent，并保存输入、输出和本轮状态。
|
Package turn 执行一轮 Agent，并保存输入、输出和本轮状态。 |
|
workspace
Package workspace 定义执行环境工具用的工作区：按路径读写文件、启动进程。
|
Package workspace 定义执行环境工具用的工作区：按路径读写文件、启动进程。 |
|
Package www 把构建好的 WebUI 页面文件打包进二进制。
|
Package www 把构建好的 WebUI 页面文件打包进二进制。 |