🔥 androoAGI/starnet：让真实 AI Agent 在像素空间站中协作的本地优先桌面平台

StarNet 是一个本地优先的桌面运行框架：你可以创建 AI Agent，将它们组织在一个像素风空间站中，并观察它们借助真实模型与工具完成真实工作。这个空间站并非装饰——它是实时运行状态的投影，产品契约具有字面含义：一个房间就是一个按能力范围划分的团队、一条走廊就是一条已获授权的交接通道、一个摆放的物体就是一次真实的能力授予。你绘制的布局，就是 Agent 实际运行的工作流。

先从一个 Agent 开始，再放置工作舱或召唤专家，以更多、并发的方式运行——每一个都是真正独立且边界明确的 Agent 运行实例，拥有自己的工作区与权限。该运行框架执行的是真实模型调用、真实工具操作与真实成本，而非为模拟效果制作动画。

• 模型调用通过本地 Node sidecar 流式传输。
• 工具操作通过明确的能力与同意检查执行。
• Agent 记忆、对话记录、支出记录、任务和计划都会持久化到磁盘。
• 多个 Agent 可在独立工作区和受限权限下并发运行。
• 可视化空间站投影的是该运行框架能够证明的同一份运行时状态。

StarNet 不会模拟收入、已完成工作、模型活动或支出。其核心产品法则是：界面绝不能声明运行框架无法证明的状态。

桌面版构建可在 StarNet 发布页面 获取。

**Apple Silicon 提示：**请使用原生 aarch64 DMG。Apple Silicon 设备应避免使用 x64 DMG：它会在 Rosetta 2 下运行，而非使用原生架构。

公共发布流程支持 Windows 和 macOS。除非 Windows 安装程序通过 Authenticode 与时间戳验证、两个 Mac 构建均通过 Developer ID 检查与 Apple 公证、并且每个更新器产物都拥有有效的更新器签名，否则流程将拒绝发布。这些是流水线要求，并不代表某个已下载或已安装副本已在你的机器上经过测试；INSTALL.md 说明了应验证的内容以及何时应停止操作。Linux 软件包仅为内部构建产物，并非受支持的公共发布目标。

早期版本：Windows 是测试最充分的桌面目标。macOS 的真实环境覆盖较少。遇到问题？请告知我们：androo.agi@gmail.com。

要求：Node.js 18+（Node.js 22 与 CI 保持一致）、Git。仅桌面 shell 需要 Rust 和 Tauri prerequisites。

sidecar 仅使用 Node 核心模块，因此无需安装任何额外依赖即可运行：

git clone https://github.com/androoAGI/starnet.git
cd starnet
node sidecar/index.js

打开 http://localhost:8787，随后连接提供商——自带 OpenRouter API key（BYOK），或使用受支持的 OAuth 登录。运行 Agent 时，提供商请求会离开你的机器；除非你显式使用网络工具或连接器，否则空间站状态、对话记录、记忆和账本都会保留在本地 StarNet 工作区。完整数据流向请参阅 PRIVACY.md。

使用本地模型免费运行

无需密钥、无需账户、无需付费：安装 Ollama，拉取一个模型（ollama pull llama3.1），然后选择 OLLAMA 作为提供商——可在首次启动时的模型选择页面进行设置，或稍后前往 SETTINGS → PROVIDERS。StarNet 会通过 127.0.0.1:11434 与 Ollama 通信，且只有在能够列出你的本地模型时才会报告其已就绪。需要如实说明的是：本地模型通常比云端模型更小，因此在长任务上预计会更慢、效果也更粗糙。

用于桌面开发：

npm ci
npm run desktop:dev     # dev shell
npm run desktop:build   # build installers locally

从 OpenClaw 或 Hermes 迁移？

StarNet 可以导入现有 Agent：将其指向磁盘上的 OpenClaw 或 Hermes 主目录，它会根据找到的人格设定、指令、记忆和模型生成一个 StarNet Agent。API 密钥不会迁移——你需要在 KEYS 标签页中重新输入。

前端通过 localhost HTTP/NDJSON 和 SSE 消费真实的 sidecar 事件。密钥属于本地权限边界：密钥由 sidecar / OS keychain 持有，绝不存放在前端。

请从 docs/INDEX.md 开始阅读持续更新的文档。较早的规划文档仍保留在仓库中，作为设计历史，并已作相应标注。

npm run test:fast          # required merge gate
npm run test:http          # live sidecar HTTP/E2E suite
npm test                   # validation + world + fast + HTTP suites
npm run security:secrets   # full-history secret scan; requires Gitleaks in PATH

发布汇总命令为 npm run qa:ready。它与候选版本绑定：任何新提交都会使此前的 READY 凭据失效，直至重新运行受影响的实时门禁检查。

贡献与安全

欢迎贡献——请阅读 CONTRIBUTING.md，并遵守行为准则。

请勿通过公开 issue 报告漏洞。请遵循 SECURITY.md 中的私密报告说明。

StarNet 以 MIT License 开源。第三方组件仍遵循其原始许可证——详见 NOTICE.md。

MIT License 仅覆盖代码。 StarNet 名称、Logo、空间站美术与精灵图，以及项目其余品牌标识均归 Andrew Sims 所有，不随该许可证授权——无论明示或默示，均不授予任何商标或其他品牌权利。

MIT 许可证意味着你可以 fork、修改和再分发代码，包括用于商业用途。但你不能将其作为 StarNet 发布：fork 和衍生项目必须使用自己的名称、Logo 和美术资源，且不得将自身表述为该项目，或表述为获得该项目认可。

StarNet is a local-first desktop harness where you create AI agents, organize them into a pixel-art space station, and watch them perform real work with real models and tools. The station is not decoration — it is a projection of live runtime state, and the product contract is literal: A room is a capability-scoped team , a hallway is an authorized handoff lane, and a placed object is a real capability grant. The layout you draw is the workflow the agents run.

Start with one agent, then place bays or summon specialists to run more, concurrently — each a genuinely distinct, bounded agent run with its own workspace and permissions. The harness performs real model calls, real tools, real cost rather than animating a simulation.

|
---|---
A crew, not a chatbot | Create agents with distinct classes, personas, and loadouts. Run several at once — each gets its own workspace, transcript, memory, and bounded permissions.
Bring your own models | Paste an OpenRouter key, or sign in with supported provider accounts (Anthropic, OpenAI, Google) — keys live in the OS keychain, never in the frontend.
Message it from anywhere | Wire agents to Telegram, Discord, Slack, Signal, or Matrix and talk to your station away from the desk.
Night Shift | Leave the station running and agents keep working inside an explicit, adjustable leash — every away-action is logged and reviewable.
Recipes, skills, schedules | Launch proven multi-step recipes, grant reusable skills, and put work on cron schedules with visible output.
Asks before it guesses | Task Briefs turn ambiguity into one concrete question with options — over any connected channel — instead of a silent wrong guess.
Finished work has a front door | Deliverables land in the OUTBOX as real files you open, not chat scrollback you archaeology.
MCP connectors | Attach Model Context Protocol servers and paste-a-key/OAuth connectors to extend what agents can touch.
Voice | Push-to-talk dictation in, one consistent station voice out.
Real ledgers | Spend, budgets, and run history persist on disk and are shown as-is.

• Model calls stream through the local Node sidecar.
• Tools operate through explicit capability and consent checks.
• Agent memory, transcripts, spend records, tasks, and schedules persist on disk.
• Multiple agents run concurrently with separate workspaces and bounded permissions.
• The visual station projects the same runtime state the harness can prove.

StarNet does not simulate revenue, completed work, model activity, or spend. Its core product law is that the interface must never assert state the harness cannot prove.

Desktop builds are published on the StarNet releases page.

Apple Silicon note: use the native aarch64 DMG. Avoid the x64 DMG on Apple Silicon: it runs under Rosetta 2 rather than using the native architecture.

The public release train supports Windows and macOS. It refuses to stage a release unless the Windows installer passes Authenticode and timestamp verification, both Mac builds pass Developer ID checks and Apple notarization, and every updater artifact has a valid updater signature. Those are pipeline requirements, not proof that a particular downloaded or installed copy was tested on your machine; INSTALL.md explains what to verify and when to stop. Linux packages are internal build artifacts only and are not a supported public release target.

Early release: Windows is the most-tested desktop target. macOS has less real-world coverage. Broken? Tell us: androo.agi@gmail.com.

Requirements: Node.js 18+ (Node.js 22 matches CI), Git. Rust and the Tauri prerequisites only for the desktop shell.

The sidecar uses Node core modules only, so it runs without installing anything:

git clone https://github.com/androoAGI/starnet.git
cd starnet
node sidecar/index.js

Open http://localhost:8787, then connect a provider — bring your own OpenRouter API key (BYOK) or use a supported OAuth sign-in. Provider requests leave your machine when you run an agent; station state, transcripts, memory, and ledgers stay in the local StarNet workspace unless you explicitly use a network tool or connector. See PRIVACY.md for the full data map.

Run free with a local model

No key, no account, no bill: install Ollama, pull a model (ollama pull llama3.1), and pick OLLAMA as the provider — on the first-run brain screen, or later in SETTINGS → PROVIDERS. StarNet talks to Ollama on 127.0.0.1:11434 and only reports it ready once it can list your local models. Honest caveat: local models are smaller than the cloud ones, so expect slower and rougher work on long tasks.

For desktop development:

npm ci
npm run desktop:dev     # dev shell
npm run desktop:build   # build installers locally

Coming from OpenClaw or Hermes?

StarNet can import an existing agent: point it at your on-disk OpenClaw or Hermes home and it mints a StarNet agent from the persona, instructions, memory, and model it finds. API keys never transfer — you re-enter those in the KEYS tab.

The frontend consumes real sidecar events over localhost HTTP/NDJSON and SSE. Secrets belong to the local authority: Secrets are held by the sidecar / OS keychain, never in the frontend.

Start with docs/INDEX.md for the living documentation. Older planning documents remain in the repository as design history and are labeled accordingly.

npm run test:fast          # required merge gate
npm run test:http          # live sidecar HTTP/E2E suite
npm test                   # validation + world + fast + HTTP suites
npm run security:secrets   # full-history secret scan; requires Gitleaks in PATH

The release aggregate is npm run qa:ready. It is candidate-bound: any new commit invalidates the prior READY receipt until the affected live gates are rerun.

Contributing and security

Contributions are welcome — read CONTRIBUTING.md and follow the Code of Conduct.

Do not report vulnerabilities in a public issue. Follow SECURITY.md for private reporting instructions.

StarNet is open source under the MIT License. Third-party components remain under their original licenses — see NOTICE.md.

The MIT License covers the code only. The StarNet name, the logo, the station artwork and sprites, and the rest of the project's brand identity are owned by Andrew Sims and are not licensed with it — no trademark or other brand rights are granted, expressly or by implication.

MIT means you may fork, modify, and redistribute the code, including commercially. What you may not do is ship it as StarNet: forks and derivatives must use their own name, logo, and artwork, and must not present themselves as this project or as endorsed by it.