Oktoso是AI代理的中枢第一会话中心. 一个地方可以查看需要关注的内容,浏览会话,开始聊天,并跨OpenCode,Open WebUI,Hermes等供应商回复.
该枢纽是一个小型节点/TypeScript HTTP服务. 客户端是薄而可替换的:网络,移动,桌面,Even G2眼镜和VR.
屏幕
提供方上下文,现场推理,工具活动,以及等待您的权限.
状态
执行阶段. v0.1.11 传输聊天交互切片:消息复制、以枢机为后盾的拼写、OpenCode附件、Open WebUI in-chat分支切换和重试、OpenCode会话叉和一个保存刷新时消息顺序的提供者命令固定。 OpenCode和Open WebUI是活的,网络中枢有搜索,草稿,注意,最新的第一张记录誊本,以及递增的信息流,而Even G2客户端有对接,收件,聊天,提问,批发,发现,失败状态,以及glyph传奇. 经批准的UI参考被冻结为 design-v1.3。自 v0.1.11,执行MCP北行片: oktoso mcp 斯地迪奥桥和枢纽 /mcp 带有范围符号、许可列表、审计、费率限制和注意力/会议资源订阅。 所剩空白包括:真正的Hermes,G2语音和硬件接受,MCP OAuth,以及远程/多主机加固和Termux/跨主机接受运行.
文档
docs/design.md- 架构、域模型、供应商适配器、API、安全、部署docs/plan.md- 分阶段交付计划和接受标准docs/code-structure.md- 执行系统、存储器布局、API添加和任务排序docs/ui-ia.md- 信息架构、屏幕、流量、反应和眼镜/VR适应docs/visual-audit.md- 对照审计、视觉标志和组件规则docs/design-lock.md- 冻僵了design-v1.3参考和改革政策docs/interaction-contract.md- 聊天副本、口语、附件、分枝、再试和叉语义docs/package-evaluation.md- 一揽子援助计划决定记录docs/brand/README.md- 商标、应用程序图标和横幅资产AGENTS.md- 用户界面/设计合同和代理人存放处指示docs/openapi.yaml- 生成API合同docs/deployment.md- 远程提供者、Termux、Docker、系统、TLS和VPN部署SECURITY.md- 证书处理和脆弱性报告docs/publishing.md- npm信任的出版和发布工作流程docs/prototypes/index.html- 具有模拟数据的交互式UI原型
应用程序
- 连G2 ——可观的注意并回复眼镜表面.
原则
- 中心拥有提供者证书,会话索引编制,正常化,关注,以及活动粉丝出道.
- 客户端消费了1个HTTP/SSE API. 没有客户拥有商业逻辑.
- 提供方API是真理的来源. 枢纽缓存和索引.
- 非加太公司没有要求,枢纽上也没有本地代理程序.
- 没有网络假设。 电线守护(WireGuard),Tailscale(Tailscale),LAN(LAN),和TLS(TLS)是运营商的担忧.
- 一个代码库运行于Termux,Linux,macOS,一个Raspberry Pi,或者一个VPS上.
发展
pnpm install
pnpm dev
- 网络 :
http://localhost:5175 - 中枢 API :
http://127.0.0.1:8787 - 发展标志:
dev-token-oktoso(预填入dev登录;运行)pnpm pair:dev以链接代替) - OpenCode 读取/写出:会话索引、笔录、作曲、新会话和中断
- 打开 WebUI : 聊天, 当前分支, 模型, 新聊天, 并快速发送
- 提供者: OpenCode 和 Open WebUI 适配器; Hermes 仍然是只健康假名
- 注意:权限,表单,未读会话,失败,提供者支持的行动,以及活导航徽章
pnpm dev 启动枢机, Vite, 假 Open WebUI/Hermes 服务器, 以及假 OpenCode 服务器 。 真正的提供者证书属于被忽略的 .env.local 文件 :
OPENCODE_BASE_URL=http://127.0.0.1:4096
OPENCODE_USERNAME=opencode
OPENCODE_PASSWORD=...
OPENWEBUI_BASE_URL=https://openwebui.example
OPENWEBUI_API_KEY=...
当这些变量出现时,匹配的提供者使用真实实例而不是假实例. 关闭一个提供者的基础 URL 离开提供者在其本地的假端点。 dev 命令不会启动被冻结的原型.
.env.local 财务报告和审定财务报表 .data/ 被忽略。 保留 .env.local 在模式下 0600承诺 dev-token-oktoso 是本地唯一的所有者符; 生成长随机 HUB_TOKEN 任何可达到的部署。 旋转它可以取消每对会话.
原型
pnpm prototype
打开 http://127.0.0.1:4174 在浏览器中。 调整窗口大小以查看移动布局 .
构建
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm openapi:check
pnpm build
pnpm test:e2e 构建单端口捆绑,并运行Playwright浏览器套件,以对抗临时枢纽和假供应商.
不配置靴子开始本地工作空间空 :
pnpm start
它创建了没有提供者的集线器配置,生成了恒定所有者符,打印一次,并启动集线器. 第一次启动时,它也会在服务器监听后打印出一次性的对接链接. 在配置中添加提供者并重新启动 。 明确要求 --config 或者说 HUB_CONFIG 路径永远不会被隐含地创建.
配置与其它用户配置共存, 而不是在工作目录中 :
| 平台 | 配置 |
|---|---|
| Linux, Termux 软件 | $XDG_CONFIG_HOME/oktoso/hub.config.json (单位:千美元)~/.config/oktoso/hub.config.json (默认) |
| 马科斯 | ~/Library/Application Support/Oktoso/hub.config.json |
| 窗口 | %LOCALAPPDATA%\Oktoso\hub.config.json |
--config <path> 或者说 HUB_CONFIG 超过它。 遗产 ./hub.config.json 在工作目录中,当平台配置尚未存在时,仍然使用,而枢纽在返回时会打印出一行警告. 运行时状态默认为平台状态目录( R)$XDG_STATE_HOME/oktoso, (中文(简体) ), ~/Library/Application Support/Oktoso/data, (中文(简体) ), %LOCALAPPDATA%\Oktoso\data)),所以读取标记和草稿不会将每个工作目录分叉.
文件持有所有者符和每个提供者证书. 它被创建 0600 内置 a 0700 目录,当文件被另一个账户读取或写入时,中枢拒绝启动,打印 chmod 600 命令运行.
pnpm start 运行已建 dist/hub.js。同一切入点与 oktoso npx 安装的 bin : npx @amoshydra/oktoso 启动中枢,并 npx @amoshydra/oktoso pair 连接到运行中枢.
供应商证书
从提供者屏幕或配置文件中添加提供者, 包含基础 URL 和提供者签发的证书 。 身份证明只写:API从不返回,在编辑时留下密码空白保留所存储的值.
| 提供者 | 认证 | 证书来自哪里 |
|---|---|---|
| 打开代码 | 基本认证, 用户名 opencode | opencode service get password 在运行 OpenCode 的机器上,或 .password 内 ~/.local/state/opencode/service.json |
| 打开 WebUI | 借记符 | 设置 — 账户 — API 密钥 在打开 WebUI 中 |
| 赫尔墨斯 | 借记符 | 这个 API_SERVER_KEY 它的 API 服务器启动于 |
提供者表单在证书字段下显示相同的提示. OpenCode 一次生成其服务密码, 并在整个重启时保留它; 如果它被重新生成, 更新提供者或行显示 auth-error。 。 。 .
对齐浏览器或可穿戴
配对避免将所有者代币复制到每个客户端.
在第一个创建配置的启动时,TUI打开一个设置面板,上面会显示一次所有者符号. 新闻 p 打开配对的 QR。 普通和非TTY模式打印出首个运行的对接链接。 后来开始打印一行提醒而不是链接. 链接打开一个确认页;在您按下前不会对齐 配对此设备。 。 。 .
在前景终端中, 类型 p 并随时按 Enter 键打印新链接。 服务器继续运行. 中心启动时, 这是正常的路径 npx 或者说 pnpm start。 。 。 .
对于背景进程或第二个终端,运行:
pnpm pair
用包装的CLI,即 npx @amoshydra/oktoso pair它为回回路和局域网地址打印一次性链接。 链接在五分钟后失效,工作一次。 主人代号从不共享. 对于已建服务器:
node dist/hub.js --pair
当终端是 TTY 有局域网地址时,命令还打印 a 扫描成对 QR码. 用手机相机扫描,打开确认页. 在支持的安全文本浏览器上,登录屏幕也提供 扫描配对QR 使用浏览器条码检测 API。 在Plain-HTTP 局域网的出处或浏览器上,没有API,取而代之的是使用电话相机应用.
使用 --url https://hub.example.com 当枢机在代理机后面时。 CLI从配置中以所有者代号认证,必须运行在可以到达中枢的主机上. 如果中枢被绑定在一个回回地址,则绑定 0.0.0.0 或通过 --url 用于配对另一个设备。 如果你以 HUB_HOST 或者说 HUB_PORT 覆盖, 将相同的变量传递到 pair 命令,所以打印的链接匹配。 对 Dev 配置, 使用 pnpm pair:dev。 。 。 .
Paired浏览器使用30天的HttpOnly会话 cookie,不将指针存储于JavaScript. 会话在浏览器活动时自动刷新;过期后闲置的浏览器再刷新. API 客户端可以打电话 POST /api/v1/auth/refresh 他们的会话代号。 从另一个来源装入的软件包仍然可以粘贴所有者或会话符号. 旋转 HUB_TOKEN 取消每对会话.
打开一对页不消耗代码,因此聊天链接预览是安全的. 按键 配对此设备 消耗它。 5分钟后,页面显示一个过期消息,让你按 p 在中枢终端中;如果浏览器已经对齐,则直接去应用.
用于代理的多氯乙烯
OpenCode等MCP客户端可以使用Oktoso作为其控制平面:
oktoso mcp # read-only tools
oktoso mcp --allow-write
大桥会讲MCP过stdio,会读取"枢纽配置",并用"配置符"给"枢纽REST API"打电话. 只读是默认值 。 写作工具覆盖发送,创建,中断,标记读取,并采取行动引起注意. 服务器拒绝向引用并需要的 OpenCode 会话写入 confirm: true 在核准一个注意事项之前.
中枢也可以在 /mcp 超流性HTTP. 启用 mcp 在中心配置中添加一个带有可选写、提供者和工具瞄准镜的无记名符号:
{
"mcp": {
"enabled": true,
"tokens": [
{ "id": "controller", "token": "${MCP_TOKEN}", "allowWrite": true }
]
}
}
托管的电话是限速的,限时的,会话的,并附在 <dataDir>/mcp-audit.jsonl。会议也暴露 oktoso://attention 财务报告和审定财务报表 oktoso://sessions 有订阅更新的资源。 见 docs/mcp-northbound.md 用于完整配置、 OpenCode 远程设置、 工具列表、 控制器快捷以及安全规则.
终端用户界面
在前台TTY中,枢纽制造出全屏仪表板:
╭─ Oktoso ──────────────────────────────────────────── v0.1.0 ─╮
│ http://127.0.0.1:8787 up 12m 04s json │
├──────────────────────────────────────────────────────────────┤
│ Providers 2/3 Sessions 12 Attention 3 1 SSE │
│ Event 1042 Requests 142 Errors 0 p pair · ? help │
├──────────────────────────────────────────────────────────────┤
│ Activity │
│ 18:52:01 desktop-opencode online │
│ 18:52:04 attention permission · Fix auth │
├──────────────────────────────────────────────────────────────┤
│ p pair · l logs · r refresh · o open · ^C quit · ? help │
╰──────────────────────────────────────────────────────────────╯
密钥 :
p—对一设备;打开 QR/link 模式l切换活动和日志;j编号 :k滚动r——重新检查提供者并刷新缓存o——打开web UI,或在模式打开时打开配对链接c复制配对链接或首发所有者代号t——在配对模式打开时只复制配对代码?- 关键帮助Ctrl+C——退出
在第一次运行时,中枢打开了一个设置面板,上面显示的是一次所有者符号. 新闻 p 到对对。 配对模式保持了QR,主局域网链接,并可以在不重新油漆的情况下可见过期时间,因此链接仍然可以选择. 在一对设备后,面板在5秒后返回仪表板.
再次运行命令
如果 Oktoso 已经监听了配置的主机和端口, 则秒 npx @amoshydra/oktoso 不崩溃与 EADDRINUSE。它打印状态卡和退出:
Oktoso 0.1.0 is already running at http://127.0.0.1:8787
pid 1234 · up 12m 04s · event seq 1042
Web UI http://127.0.0.1:8787
Pair npx @amoshydra/oktoso pair
Status npx @amoshydra/oktoso status
Stop Ctrl+C in the original terminal, or kill 1234
有用的表格 :
npx @amoshydra/oktoso status # is it running, and where?
npx @amoshydra/oktoso pair # pair a device against the running hub
npx @amoshydra/oktoso --port 8788 # after stopping the current hub
npx @amoshydra/oktoso --host 0.0.0.0 # override the bind host on next start
第二例需要自己的状态和日志目录;先停止当前中枢,或用单独的目录运行:
HUB_DATA_DIR=.data-8788 HUB_LOG_DIR=.logs-8788 npx @amoshydra/oktoso --port 8788
如果端口被不同的过程所占用,命令会这样说并推荐另一个端口. 没有堆栈追踪.
结构化的日志不出现在仪表板上. 在TUI模式下,它们前往平台日志目录:
Linux/Termux $XDG_STATE_HOME/oktoso/logs/hub.log
macOS ~/Library/Logs/Oktoso/hub.log
Windows %LOCALAPPDATA%\Oktoso\Logs\hub.log
只有两个文件被保存: hub.log 当前运行和 hub.log.prev 用于上次运行。 运行在 25 MiB 旋转,如果单个运行是那么长,则替换上一个文件. --log-file, (中文(简体) ), --log-dir, (中文(简体) ), --no-log-file,以及 HUB_LOG_MAX_BYTES 覆盖默认值 .
使用 --plain 用于向后滚动的会话; 人类输出停留在 stdout上, JSON 日志进入 stderr 。 使用 --log-json 为服务和流程管理人员提供服务。 非 TTY 进程从不启动 TUI; 与之配对 npx @amoshydra/oktoso pair 从任何终端. --help 列出所有旗帜.
堆栈
- 节点.js 24+
- 类型脚本
- 24+节点上的Hono
- 反应 + 参考网络客户端的虚拟
- 纯 JavaScript 依赖性, 没有本地模块
- JSON 状态存储器首先; 可选
node:sqlite稍后的适配器 - 捆绑
dist/hub.js便携式部署
警卫
提供方证书,所有者代币,配对链接,运行时状态远离Git. 见 SECURITY.md 用于报告和部署指导.
许可证
麻省理工学院. 见 LICENSE。 。 。 .
下一个
接下来:MCP北上. 实验桥上 feat/mcp-northbound 暴露了枢纽的阅读工具,与 --allow-write 对于写作工具,自控拒绝, 一个确认的门批准, 和一能发送。 未发运。 后续行动由中心主办 /mcp 有范围标志和每工具审计的终点.