starnet

A living pixel-art station where real AI agents do real work.

[Download] [Platforms] [License: MIT] [Local-first]

Download · Install guide · Run from source · Docs · Contributing

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.

Features

What is real

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

Download

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.

Run from source

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 qwen3:8b), 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. Pick a model that supports tools (ollama show <model> lists them): agents act through tool calls. Honest caveat: local models are smaller than the cloud ones, so expect slower and rougher work on long tasks, and a task needs a large context window — an 8B model takes about 10 GB of graphics memory while it works.

For desktop development:

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

Terminal mode

The desktop app ships a starnet command beside it. Run it with no arguments and it opens a live dashboard on the station the app is running: the crew down the left (a spinner on whoever is working), the chosen agent's conversation beside it, and every approval as a card you answer with y or n (v shows the full request first). It reads the same state the app does, so it never shows work the station cannot prove.

StarNet doesn't have to be open. With it closed, starnet starts it in the background: the same station with your keys (they stay in the app's keychain), and no window opens; the tray icon shows it's running. When the last starnet session ends it closes again, unless routines are armed or StarNet is set to stay in the tray (the same as closing its window). Opening StarNet while it runs shows that same station; on macOS, open it from its menu-bar icon (Open StarNet), since a Dock click doesn't bring that window back yet.

So you can just type starnet in a new terminal: the Windows installer puts that folder on your user PATH (the uninstaller takes it off), and on macOS StarNet links the command into ~/.local/bin the first time it starts, adding that folder to ~/.zprofile if no shell profile has it yet (STARNET_NO_CLI_LINK=1 turns that off). Other commands: starnet ls (every agent and its open asks), starnet approve / starnet deny, starnet watch (the live event stream, one line each), starnet flow (workflows) and starnet -p "<task>" (one run, answer on stdout). starnet --help lists them all. From a checkout, use node bin/starnet.js.

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 CONNECT › ABILITIES › CONNECTED › API KEYS.

Architecture

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.

Testing

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.

License

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.