SolanaOS Hub

Central hub for skill management, gateway operations, and the control UI.

Architecture

┌──────────────────┐     ┌────────────────────┐     ┌──────────────────┐
│   Control UI     │────▶│   Gateway Bridge   │────▶│   Headless Nodes │
│  (Lit + Vite)    │ WS  │  (Go TCP Server)   │ TCP │  (Orin/RPi/etc)  │
│  ui/             │     │  pkg/gateway/       │     │                  │
└──────────────────┘     └────────────────────┘     └──────────────────┘
     Port 5173 (dev)        Port 18790 (bridge)
                            Port 18793 (WS/canvas)

Key Codebase Paths

Component	Path	Description
Gateway Bridge	pkg/gateway/bridge.go	TCP server, node auth, JSON-line protocol
Gateway WebSocket	pkg/gateway/ws.go	WebSocket transport for browser clients
Control UI	ui/	Lit web components, Vite build, connects via WS
UI Gateway Client	ui/src/ui/gateway.ts	WebSocket client with device auth
Skills	skills/	All operator skills (this directory)

Control UI

The control UI is a Lit web component app at ui/.

Dev Server

cd /Users/8bit/solanaos/ui && npm run dev

Build

cd /Users/8bit/solanaos/ui && npm run build

Test

cd /Users/8bit/solanaos/ui && npm test

UI connects to gateway via WebSocket

The UI uses solanaos-gateway subprotocol to communicate with the Go gateway. See ui/src/ui/gateway.ts for the client implementation. Protocol frames:

• hello-ok — auth handshake with device token
• event — server-push events (presence, health, state)
• res — request/response pairs

Gateway

The Go-native gateway at pkg/gateway/ provides:

• TCP Bridge (port 18790): JSON-line protocol for headless nodes
• WebSocket (port 18793): Browser/extension connections
• Auth: Token-based + device identity signing (Ed25519)
• Canvas Host: Serves HTML to connected nodes

Start Gateway

cd /Users/8bit/solanaos && go build -ldflags="-s -w" -o build/solanaos . && ./build/solanaos node gateway-spawn

Configuration

In ~/.solanaos/solanaos.json:

{
  "gateway": {
    "bind": "auto",
    "port": 18790,
    "authToken": "your-token"
  },
  "canvasHost": {
    "enabled": true,
    "port": 18793,
    "root": "~/clawd/canvas"
  }
}

ClawHub CLI (Skill Registry)

Install

npm i -g clawhub

Auth (publish)

clawhub login
clawhub whoami

Search

clawhub search "postgres backups"

Install

clawhub install my-skill
clawhub install my-skill --version 1.2.3

Update (hash-based match + upgrade)

clawhub update my-skill
clawhub update my-skill --version 1.2.3
clawhub update --all
clawhub update my-skill --force
clawhub update --all --no-input --force

List

clawhub list

Publish

clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --changelog "Fixes + docs"

Notes

• Default registry: https://clawhub.com (override with CLAWHUB_REGISTRY or --registry)
• Default workdir: cwd (falls back to SolanaOS workspace); install dir: ./skills (override with --workdir / --dir / CLAWHUB_WORKDIR)
• Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set