os-hub

The full skill.

Original instructions from the publisher’s SKILL.md

# 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

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

### Build

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

### Test

```bash
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

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

### Configuration

In `~/.solanaos/solanaos.json`:

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

## ClawHub CLI (Skill Registry)

Install

```bash
npm i -g clawhub
```

Auth (publish)

```bash
clawhub login
clawhub whoami
```

Search

```bash
clawhub search "postgres backups"
```

Install

```bash
clawhub install my-skill
clawhub install my-skill --version 1.2.3
```

Update (hash-based match + upgrade)

```bash
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

```bash
clawhub list
```

Publish

```bash
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