1. The Core Bottleneck: What Engineering Pain Point Does It Smash?

Current AI development tools remain trapped within the narrative of chat interfaces, forcing developers to perform archaeological digs through dozens of pages of scrollback logs while losing intuitive control over concurrent agent instances. Ambiguous permission boundaries lead to unauthorized tool execution, multi-instance coordination lacks physical topological constraints, and runtime costs remain completely inside a black box.

StarNet reconstructs the product contract via a local-first desktop harness, strictly aligning visual presentation with the underlying runtime state. Rooms map to capability-scoped teams, hallways mirror authorized handoff lanes, and placed objects equate to real system capability grants. The layout drawn on the canvas becomes the workflow executed by the agents, eliminating the cognitive gap between visual state and actual runtime state.

💡 Architectural Insight: StarNet's core breakthrough lies in abandoning simulated animations, strictly enforcing that the interface must be an absolute projection of runtime state, turning the visual topology directly into an executable engineering contract.

2. Core Architecture and Underlying Data Flow

StarNet adopts a decoupled yet tightly bound local architecture. The frontend uses vanilla JavaScript to render the pixel-art station world, consuming real-time events over localhost HTTP/NDJSON and SSE. The backend relies on an independent Node.js runtime as a local sidecar handling model routing, tool execution, persistence, and consent checks. The desktop shell is driven by Rust and Tauri, ensuring low overhead and native security.

[ Desktop UI / Canvas ] --( HTTP / NDJSON / SSE )--> [ Node.js Sidecar ]
                                                             │
                     ┌───────────────────────────────────────┴───────────────────────────────────────┐
                     ▼                                       ▼                                       ▼
        [ Provider Router (API/Ollama) ]       [ Capability & Consent Check ]         [ OS Keychain (API Keys) ]

Within the data flow, the frontend holds zero sensitive secrets; all API keys reside securely within the OS keychain. When a task initiates on the canvas, commands route to the Node sidecar, passing explicit capability and consent checks before hitting LLMs. Actual generated files and ledgers persist directly to local disk storage without asserting unprovable states.

3. Technical Selection and Hardcore Benchmarks

Evaluation Dimension This Solution (starnet) Traditional Paradigm Typical Competitor Production Benefit
State Veracity UI state strictly matches runtime Animations detached from execution Relies on opaque cloud estimation Eliminates misleading false states
Secret Management Hosted in OS Keychain, zero frontend Stored in plaintext LocalStorage Retained on third-party servers Eradicates browser XSS credential theft
Multi-Agent Concurrency Isolated workspaces & transcripts Single-thread or shared context Heavy process coupling, high contention Prevents context pollution & leaks
Deliverable Artifacts Lands as real disk files in OUTBOX Buried inside long chat histories Temporary sandbox files lost on exit Immediate consumption without extraction

This architecture abandons the comfort zone of cloud hosting. By pushing state management, permission verification, and asset persistence back to the local host, it delivers rich desktop interaction while holding the hard engineering line on security and observability.

4. Hands-on Geek Practice: Zero to Minimum Viable Loop

Clone the source repository in your local environment and spin up the Node sidecar to build the minimum working loop. Prerequisites require Node.js 18+ and Git.

# Clone the official repository
git clone https://github.com/androoAGI/starnet.git
cd starnet

# Run the local Node core sidecar (runs natively without extra installs)
node sidecar/index.js

Open http://localhost:8787 in your browser. Paste your OpenRouter API key on the first-run brain screen, or pick Ollama by running ollama pull llama3.1 which binds to 127.0.0.1:11434.

// sidecar/index.js core initialization logic snippet
const http = require('http');
const { initWorkspace, loadKeyChain } = require('./runtime');

// Establish local security boundary, rejecting unauthorized remote calls
const server = http.createServer(async (req, res) => {
  const sessionState = await loadKeyChain();
  if (!sessionState.isAuthenticated) {
    res.writeHead(401, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Unauthorized local authority' }));
    return;
  }
  // Dispatch event stream to target agent workspace
  dispatchToAgentSpace(req, res);
});

server.listen(8787, '127.0.0.1', () => {
  console.log('StarNet sidecar active on http://127.0.0.1:8787');
});

5. Production Deployment Gotchas and Avoidance Strategies

During live deployments and extended Night Shift runs, hardware resources and model latencies present primary engineering friction points. Local small models struggle with complex multi-step reasoning, while unconstrained concurrency spikes local memory usage instantly.

⚠️ Gotcha Warning [Local Model Performance Ceiling]: When running small local models (under 8B parameters via Ollama) on multi-step recipes, avoid setting high concurrency limits. Lacking the instruction-following headroom of large cloud models, small models easily get lost and loop infinitely on long tasks; enforce strict Explicit Leash thresholds in Night Shift settings.

⚠️ Gotcha Warning [macOS Architecture Mismatch]: When packaging or running from source on Apple Silicon Macs, strictly utilize the native aarch64 build artifact. Falling back to the x64 version forces Rosetta 2 translation, significantly increasing IPC latency between the Tauri desktop shell and Node sidecar, and causing tray timeout failures.