GS-LLM

ChatGPT on your Apple IIgs. GS-LLM is a native GS/OS application that talks to modern LLMs — GPT, Grok, Claude, Gemini, Llama, and more — over your LAN. A sleek 640×200 Super Hi-Res UI streams replies live while a tiny Mac-side helper holds your API keys and handles TLS so the GS never sees a secret.

Built on the same Marinetti TCP stack and app patterns as GS Miner: cooperative socket state machine, line-delimited JSON, config on disk, clean gold-master .2mg.

v0.40 — gold master, 2026-06. Native GS/OS chat client with streaming replies, session history, light/dark themes, multi-provider Model menu, Settings page, and boot splash. Shippable 2IMG / CFFA-mountable GSLLM40 disk. Seven cloud providers plus local Ollama and LM Studio via the stdlib-only Python bridge.

📖 Architecture and wire protocol: GS_LLM_OVERVIEW.md

---

Features

GS-LLM is a complete GS/OS desktop app, not a terminal hack. It boots, connects, streams, and remembers your chats.

Runs on real iron or emulator

• 640×200 SHR UI — code-drawn chrome: session rail, white-paper transcript, double-height input, up-arrow send, status lamp.
• Light / dark themes — palette swap (OA-L / OA-D).
• Session history — saved to ProDOS files under /GSLLM/SYSFILES/.
• Boot splash — six-second title card while config and history load.

Networking & chat

• Marinetti TCP to a LAN helper — same non-blocking poll loop as GS Miner.
• Streaming replies — token-by-token delta frames rendered live.
• Multi-provider Model menu — OpenAI, xAI Grok, Anthropic, Gemini, Groq, OpenRouter, Cerebras, Ollama, LM Studio (populated at runtime from the bridge).
• Settings page — host, port, theme; no recompile to point at your Mac.

Mac helper (the bridge)

• Stdlib-only Python — no pip install.
• Web config UI — paste keys, test, enable providers, pick default models.
• Keys never cross the LAN — the GS sends prompts only; TLS stays on the Mac.

---

Download

Everything you need to run GS-LLM is on GitHub Releases — no git clone required.

Asset	Description
gsllm_v0.40.2mg	ProDOS 2MG disk — mount or write to media, boot GS/OS, open /GSLLM/GSLLM40
gsllm-bridge-v0.40.zip	Mac helper — unzip anywhere, launch Start GS-LLM Helper.command (see below)

Unzip the bridge folder anywhere — Downloads, Desktop, or ~/Applications/GS-LLM-Bridge. Folder location does not affect macOS security warnings. Requires Python 3.8+ (python.org if needed).

Building from source (optional): disk/make_master.sh for the disk (needs ORCA/C via Golden Gate, plus AppleCommander.jar and wrap_2mg.py from the GS Miner repo one directory up — see gs/README.md), bridge/make_release_zip.sh for the helper zip.

---

macOS blocked the helper? (Gatekeeper)

If Start GS-LLM Helper.command shows "Not Opened — Apple could not verify…" with Move to Trash / Done, that is normal for GitHub downloads. It is not malware — the helper is stdlib Python (gsllm_bridge.py; readable source, no installer).

On recent macOS (Ventura / Sonoma / Sequoia), right-click → Open often does not work either — you get the same Move to Trash / Done dialog. Unzipping to Applications does not help.

First launch — use Terminal (reliable):

1. Open Terminal (Spotlight → Terminal).
2. Paste one line and press Return (edit the path if you did not unzip to Downloads; tip: drag the GS-LLM-Bridge folder onto the Terminal window to paste its path):

xattr -cr ~/Downloads/GS-LLM-Bridge && cd ~/Downloads/GS-LLM-Bridge && python3 gsllm_bridge.py --open

3. Your browser opens the config page. Leave Terminal open while using the GS.

The xattr step clears Apple's download quarantine. After that, double-clicking Start GS-LLM Helper.command usually works on later launches.

Other options: System Settings → Privacy & Security → Open Anyway (may appear after a blocked attempt). Same copy-paste line is in FIRST LAUNCH — paste in Terminal.txt inside the zip. More detail: bridge/README.md.

---

Get a model first (free — no credit card)

You only need one working provider:

Provider	Why pick it	Get a key
Groq	Fastest free tier — great streaming on the GS	console.groq.com/keys
Google Gemini	~1,500 free requests/day	aistudio.google.com/app/apikey
OpenRouter	25+ free models with one key	openrouter.ai/keys
Cerebras	~1M free tokens/day	cloud.cerebras.ai
Ollama / LM Studio	No key — local model on your Mac	ollama.com / lmstudio.ai

Paid keys work too: OpenAI, xAI Grok, Anthropic Claude.

---

Requirements

• Apple IIGS booted into GS/OS (System 6.0.x) — launch GSLLM40 from the Finder.
• Marinetti TCP/IP connected (Uthernet II, or emulator with working TCP).
• Mac on the same LAN running the helper (Python 3.8+).

---

Quick start

1. Download both files from Releases — the .2mg disk and the gsllm-bridge-*.zip.
2. Start the helper — on first macOS launch, use Terminal (see macOS blocked the helper? above — right-click → Open often fails on recent macOS).
3. Add a model — paste a key, Test key, tick Enabled, Save.
4. Mount the disk — gsllm_v0.40.2mg on emulator or CFFA.
5. Run GSLLM40 — File → Settings… → enter Mac Host + port 6510.
6. Chat — type a prompt, press Return.

---

Security model

• API keys live only on the Mac (bridge/config.json, gitignored, chmod 600).
• Config web UI binds to 127.0.0.1 only.
• Optional LAN access token on the LLM port.

---

Repo layout

gs-llm/
  gs/        GS app (ORCA/C) + host test harnesses
  bridge/    Mac helper + web config
  disk/      make_master.sh → gsllm_v0.<rev>.2mg
  branding/  README screenshots

Details: gs/README.md, bridge/README.md.

---

Built with

• GS Miner — transport, config, logging, disk pipeline reused here
• Golden Gate + ORCA/C — 65816 build on macOS
• Cursor — app, bridge, docs, and splash art

Issues and pull requests welcome.