| --- |
| license: agpl-3.0 |
| tags: |
| - snapkitty |
| - october-2026-drop |
| - kotlin |
| - android |
| - ollama |
| - agents |
| - server-admin |
| - developer-tools |
| --- |
| |
| > Mirrored from [https://github.com/SNAPKITTYWEST/kotlin-command-center](https://github.com/SNAPKITTYWEST/kotlin-command-center) at commit `6849123`. Part of the **SnapKitty October 2026 main drop**. |
|
|
| # Kotlin Command Center |
|
|
| Talk to your Ollama agents and administer your server from your phone — |
| without opening a single inbound firewall port. |
|
|
| ``` |
| ┌──────────┐ Bearer APP_SECRET ┌──────────────────┐ Access svc token ┌────────────────┐ |
| │ Kotlin │ ───────────────────▶ │ Cloudflare │ ──────────────────▶ │ cloudflared │──▶ Ollama :11434 |
| │ app │ https://api. │ Worker gateway │ https://ollama- │ (outbound │ |
| │ (:core / │ yourdomain.com │ worker/ │ internal. │ only, no │ |
| │ :android │ │ │ yourdomain.com │ inbound │──▶ sshd :22 |
| │ :desktop)│ ───────────────────▶ │ │ ──────────────────▶ │ ports) │ |
| └──────────┘ wss://ssh. └──────────────────┘ Access svc token └────────────────┘ |
| yourdomain.com (WS handshake) on both hostnames |
| + CF-Access headers |
| ``` |
|
|
| How the pieces fit: |
|
|
| - **Server** (`server/`): `cloudflared` opens *outbound-only* tunnels for |
| Ollama (`ollama-internal.yourdomain.com → localhost:11434`) and SSH |
| (`ssh.yourdomain.com → ssh://localhost:22`). No inbound ports, ever. |
| - **Worker gateway** (`worker/`): the only thing the phone calls for |
| inference. Verifies `Authorization: Bearer <APP_SECRET>`, rate-limits per |
| IP, then forwards to the tunnel with the Cloudflare Access service token |
| attached. `/health` is unauthenticated; unknown routes 404; non-POST API |
| calls 405. |
| - **Kotlin `:core`** (`app/core/`): Ktor CIO client for the Worker |
| (`AgentClient`), plus a real JSch `SocketFactory` that bridges WebSocket |
| frames to stream-oriented SSH over piped streams (`WebSocketBridge.kt`), |
| with `StrictHostKeyChecking=yes` against a pinned `known_hosts` |
| (`SshClient`). |
| - **`:desktop`** (`app/desktop/`): terminal CLI (`health`, `prompt`, `chat`, |
| `ssh`) for testing the whole stack from a laptop. |
| - **`:android`** (`app/android/`): Compose UI (agent chat + server admin |
| tabs), source-complete. |
|
|
| ## Setup order |
|
|
| 1. **Server** — on the box that runs Ollama: |
| `sudo DOMAIN=yourdomain.com ./server/setup.sh` |
| (installs cloudflared, creates the tunnel, routes DNS, installs the |
| systemd unit). Then follow `server/ACCESS_SETUP.md` to put both hostnames |
| behind Cloudflare Access with a **service token** (Allow policy). |
| 2. **Worker** — `cd worker && wrangler secret put APP_SECRET` (+ |
| `CF_CLIENT_ID`, `CF_CLIENT_SECRET`), set `TUNNEL_BASE` in |
| `wrangler.toml`, then `wrangler deploy`. |
| 3. **App** — fill the `CC_*` env vars (see `:desktop` usage), or the |
| Android settings screen once it exists: |
| `CC_WORKER_URL`, `CC_APP_SECRET`, `CC_SSH_WS_URL`, |
| `CC_CF_CLIENT_ID`, `CC_CF_CLIENT_SECRET`, |
| `CC_SSH_USER`, `CC_SSH_HOST`, `CC_SSH_PORT`, `CC_SSH_KEY`, |
| `CC_KNOWN_HOSTS` (generate with |
| `ssh-keyscan -t rsa ssh.yourdomain.com`, verify the fingerprint |
| out-of-band first). |
| 4. Build: `./gradlew :core:test :desktop:build` (needs the Android SDK only |
| for `:android`; it is excluded from the build until then). |
|
|
| ## Security model |
|
|
| - The phone never reaches Ollama directly; the Worker is the single choke |
| point and it demands the app secret on every API call. |
| - Both tunnel hostnames require the Cloudflare Access service token at the |
| edge — the open internet gets a 403 before touching your server. |
| - SSH host keys are **pinned**: `StrictHostKeyChecking=yes` with a |
| `known_hosts` you generated. Unknown or changed keys abort the connection. |
| (The sketch this replaced used `no` — that was fixed, not inherited.) |
| - Secrets live in environment / Keystore-backed storage, never in code, |
| flags, shell history, or the repo. Nothing in this tree is a real secret: |
| domains, UUIDs, and tokens here are placeholders. |
|
|
| ## Rotation |
|
|
| - **Service token** (phone lost / token leaked): Access → Service Tokens → |
| delete `kotlin-command-center`, create a new one, `wrangler secret put` |
| the new `CF_CLIENT_ID`/`CF_CLIENT_SECRET`, update the app. The old token |
| dies immediately. |
| - **APP_SECRET**: `openssl rand -hex 32`, then `wrangler secret put |
| APP_SECRET` + update the app config. |
| - **SSH key**: rotate like any SSH key; re-run `ssh-keyscan` only if the |
| *host* key legitimately changed (and verify the new fingerprint). |
| |
| ## Verified here vs. needs your hardware |
| |
| Verified on this build machine (2026-09-30): |
| |
| - `:core` main + test sources compile clean (kotlinc 2.0.21). |
| - **8/8 unit tests pass**: Worker health/prompt/chat/auth-failure via |
| Ktor MockEngine; 256 KiB corruption-free round trip through the |
| WebSocket↔stream bridge; handshake URL/headers; a real JSch instance |
| emitting its `SSH-2.0-` banner through the bridge. |
| - `:desktop` CLI compiles and runs (usage/help path exercised). |
| - `node --check worker/worker.js` passes. |
| |
| Not verifiable here (no such infrastructure on this box): |
| |
| - Real Cloudflare account, tunnel, DNS, and Access policies. |
| - Real Ollama behind the tunnel; real sshd behind the SSH hostname. |
| - `:android` compilation — no Android SDK here. The module is excluded |
| from `settings.gradle.kts`; add `include(":android")` on a machine with |
| the SDK. Android secrets must move to EncryptedSharedPreferences before |
| shipping (see `app/android/README.md`). |
| - `./gradlew` itself: this sandbox intercepts JVM TCP loopback (Gradle |
| daemon handshake fails with the sandbox's policy banner), so the wrapper |
| could not be generated here. The Gradle scripts are standard; run |
| `./gradlew :core:test :desktop:build` on your own machine. |
| |
| ## License |
| |
| AGPLv3 — see `LICENSE`. Every source file carries an SPDX header; the |
| gate is: `grep -rL "SPDX-License-Identifier: AGPL-3.0-or-later" <sources>`. |
| |
| ### 💼 Commercial License |
| |
| SnapKitty code is free and open under **AGPL-3.0** for open-source use. Building a commercial product or service? A **proprietary commercial license** from Snapkitty Collective LLC lets you ship this code without the AGPL's source-sharing and network-use obligations. |
|
|
| **[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20kotlin-command-center)** · A.parr@belespritdaccord.uk |
|
|
|
|
