A complete AI workspace that runs on your machine — with no framework, no bundler, and no cloud account required.
Multi-provider chat · knowledge-graph memory · agent runtime with MCP tools · multimodal capture · image & video generation · realtime voice with an animated persona
Most AI workspaces are a React app wrapped around one vendor's SDK. This is the opposite of that.
No framework. shared/element.ts is a JSX factory that compiles TSX straight to real DOM. No virtual DOM, no diffing, no reconciler. Zero runtime dependencies ship to the browser — the entire client is your own code.
No vendor lock-in. Anthropic, OpenAI, xAI and local Ollama sit behind one dispatch layer. Every model id and base URL lives in a single registry (server/providers/registry.ts); retiring a model is a one-line change.
Nothing you own leaves your machine. Conversations and the knowledge graph live in IndexedDB, files and generated media in CacheStorage, settings in localStorage. There is no server-side user store — because there is no user store.
It genuinely runs with no cloud account. Install Ollama, leave every key empty, and the whole workspace works. Features that need a key hide their affordance instead of failing.
It is also a reference architecture: eleven documents with validated diagrams explain exactly how a framework-free, multi-provider, local-first AI app is built — including an honest Issues & Technical Debt list in every one.
Prerequisites — Node.js 20+. That's the only hard requirement.
git clone https://github.com/scalable-dynamics/oncloudnine.git
cd oncloudnine
npm install
npm start # builds the apps and serves http://localhost:8080Open http://localhost:8080 (use localhost, not 127.0.0.1).
That is the whole bootstrap — there are no manual steps. On first run build.js creates config.json from config.example.json (every value empty) and prints which keys are set. The build stays running and rebuilds on every change to shared/, input/, persona/, app/, server/ and public/.
Want it fully local, with no cloud keys at all?
ollama pull qwen3:32b && ollama pull nomic-embed-text # chat + embeddingsLeave every key in
config.jsonempty. Chat, memory, files, folders, capture and the persona all work.
Adding cloud providers is optional and incremental — set any subset of ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY in config.json and restart. Each key unlocks the capabilities marked below.
Everything below is implemented and covered by tests. Where a capability needs a provider key, it says so — without that key the feature reports itself as not configured and its UI affordance is hidden rather than dead.
| Capability | Needs |
|---|---|
| Streamed replies with sanitized markdown, code blocks, tool steps and copy | any one provider |
| Server-side tool orchestration (inline tools + background generation tasks) | any one provider with tool use |
Admin defaults for provider, model and global system prompt (/admin.html) |
operator; writes require local access or ADMIN_SECRET |
| Conversations: create, switch, rename, delete, persisted in IndexedDB | — |
| Message actions: copy, speak, regenerate, delete | speak: OpenAI or xAI key, or falls back to browser speech synthesis |
| Pending tray for background image/video/app/document/agent work | — |
| Mobile-first layout: drawers below 600 px, safe-area insets, 44 px touch targets, light/dark/system theme | — |
| Capability | Needs |
|---|---|
| Drag, drop, paste or pick files — DOCX, XLSX, PDF, CSV/TSV, JSON, XML, HTML, Markdown, text | — (PDF/DOCX/XLSX parse fully client-side) |
| Images as vision blocks | a provider whose model advertises vision (Anthropic, OpenAI or xAI) |
| Audio files transcribed on upload | OpenAI key |
| Local folder context: pick a folder, ignore rules, per-file toggles, re-scan diff, persisted handles | — |
| Camera and screen snapshots on an interval, each described into the conversation | a vision provider |
| Microphone segments transcribed | OpenAI key |
| Dictation into the composer | OpenAI or xAI key for provider transcription; browser speech recognition is the no-key fallback (Chrome/Safari) |
| Capability | Needs |
|---|---|
| Knowledge-graph memory in IndexedDB: entities, relations, embedded chunks | any provider for extraction |
| Hybrid recall — BM25 plus vector cosine, merged by reciprocal-rank fusion — injected as a visible, removable context card | Ollama (nomic-embed-text) or an OpenAI key for embeddings |
| Memory browser: search, edit, delete, d3 graph view, "memory used" disclosure, recall toggle | — |
| Agent runs with a live step timeline, tool events, artifacts, guardrails and cancel | any provider with tool use |
MCP servers: http and sse anywhere, stdio in local development |
— |
| Files hub: every upload, capture, generated file and deliverable, with preview, download and zip export | — |
| Capability | Needs |
|---|---|
Image generation (/image) |
OpenAI or xAI key |
Video generation as a polled job (/video) |
xAI key |
Web search with citation cards (/search, or the toggle) |
Anthropic or xAI key |
| Realtime WebRTC voice with live transcript, barge-in, and five tools | OpenAI key |
| Spoken replies for text chat | OpenAI or xAI key, or falls back to browser speech synthesis |
| Animated persona avatar with viseme lip-sync, editable by the model | — |
Full detail, with diagrams, is in docs/.
config.json is local and gitignored; config.example.json documents every key. Every provider is optional — with all keys empty the workspace runs in local-only mode (client features plus any local Ollama models). In production the same keys live in the Cloudflare KV namespace bound as KV.
On later runs config.json is migrated from the example: keys the example has gained are added empty, values you have already set are never touched.
| Key | Purpose |
|---|---|
OPENAI_API_KEY, OPENAI_ORGANIZATION_ID |
OpenAI — chat, realtime voice (WebRTC), transcription, TTS, embeddings, images |
OPENAI_MODEL, OPENAI_MODEL_RT, OPENAI_IMAGE_MODEL, OPENAI_API_URL |
Overrides; empty means the registry default |
ANTHROPIC_API_KEY, ANTHROPIC_MODEL, ANTHROPIC_API_URL |
Anthropic Messages API and its server-side web search |
XAI_API_KEY, XAI_MODEL, XAI_MODEL_RT, XAI_IMAGE_MODEL, XAI_VIDEO_MODEL, XAI_API_URL |
xAI Grok, web search, Imagine images and video, transcription and TTS (26 voices), realtime voice (Grok Voice Agent, WebSocket) |
OLLAMA_BASE_URL, OLLAMA_MODEL |
Local models; default http://localhost:11434 and qwen3:32b (dev only — a deployed Worker cannot reach localhost) |
DEFAULT_PROVIDER |
Which configured provider answers a request that names none |
APP_SESSION_SECRET |
Session-token signing for /api/* (generated and shared through KV when empty; set it explicitly in a deployment) |
ALLOWED_ORIGINS, API_RATE_LIMIT |
Extra allowed hosts; per-IP requests per minute per endpoint class |
AGENT_MAX_STEPS, AGENT_FETCH_ALLOWLIST |
Agent guardrails |
MCP_SERVERS |
Deployed MCP server list (locally: data/mcp-servers.json) |
config.example.json documents all of these inline. Model defaults live in one file, server/providers/registry.ts — claude-opus-5, gpt-5.2, grok-4.5, qwen3:32b.
npm test # 852 node:test unit + contract tests (contract tests need Ollama running)
npm run test:e2e # 163 Playwright specs across 20 files (npx playwright install chromium once)The unit tests mock every cloud provider, so nothing in the suite needs a paid key. The contract tests (test/contract/) talk to a live Ollama at http://localhost:11434.
The end-to-end harness will not run against a server it did not verify. npm run test:e2e starts its own dev server; webServer.reuseExistingServer is off, so a port that is already busy fails the run instead of being adopted. This matters because node build.js outlives an interrupted run: an orphaned dev server keeps answering on :8080 with whatever it last built, and a reused one means no build ran at all — a full suite can pass against code that is no longer in the tree (it did, twice).
The dev server therefore publishes what it is serving at GET /__dev/build-info (dev-only; the deployed Worker has no such route) — the checkout it was started in, the fingerprint of the source tree its build came from, and the hash of the bundle it holds in memory versus the one in build/public:
curl -s localhost:8080/__dev/build-info
{"server":"oncloudnine-dev-server","pid":51234,"mode":"dev","buildId":"…","sourceId":"…","stale":{"sources":false,"assets":false}}Playwright's globalSetup (test/e2e/support/global-setup.mjs) checks that before the first test and fails with the pid to kill when it does not match. test/unit/dev-server-harness.test.js proves the detection by standing up a server that looks like an orphan.
| Variable | Effect |
|---|---|
E2E_PORT |
Runs the whole harness (dev server + baseURL) on another port |
E2E_BASE_URL |
Points the suite at an already-running server elsewhere |
E2E_REUSE_SERVER=1 |
Opts back into reusing a running server for a fast local loop — the fingerprint check still has to pass |
If a stale server is ever holding the port: lsof -ti tcp:8080 | xargs kill.
wrangler is a devDependency — no global install needed. wrangler.toml holds the project name, compatibility date and pages_build_output_dir (./build/public), and the release build emits the Worker as build/public/_worker.js (Pages advanced mode), with the compiled server code kept out of the published tree.
One-time setup — provider keys live in a KV namespace bound as KV:
npx wrangler login
npm run deploy:kv # creates the namespace, prints its id
# paste the id into the [[kv_namespaces]] block in wrangler.toml, then store the keys:
npx wrangler kv key put --remote --namespace-id <id> OPENAI_API_KEY "sk-..."Deploy:
npm run deploy # build -> release bundle -> preflight -> wrangler pages deploynpm run deploy refuses to upload until the preflight (npm run deploy:check) passes: wrangler.toml must name the project and bind KV to a real namespace id, _worker.js must exist at the deploy root with a default export, index.html/js/app.js must be present, js/app.js must actually parse as a module, no compiled server code may sit inside the published tree, and no config.json value may appear in any published asset. It also warns when no APP_SESSION_SECRET is configured. Without the KV binding the deployed Worker resolves every provider key as unset and /api/* answers 503 {"error":{"code":"kv_unavailable"}} — the preflight fails instead of letting that ship.
Run the exact deployment artifact locally, on the real Workers runtime, before shipping it:
npm run publish && npm run deploy:local # wrangler pages dev ./build/public --kv KV --port 8788
⚠️ Stop the dev server before publishing.npm run publishdeletesbuild/and refills it with the minified release bundle, and a running dev server is watching that folder. It now notices (the release build writesbuild/build-info.jsonlast, withmode: "release"), says so on the console, and rebuilds its own development bundle. The reverse is also true: publish while a dev server is running and the dev server will overwrite what you just published. Two processes cannot own one output folder — stop it first.
input/ text, files, folders, camera, screen, microphone ─┐
persona/ animated avatar, ECS face animation ├─ separate tsconfig projects,
app/ workspace shell, chat, agent, files hub, voice ─┘ no imports across the boundary
shared/ JSX runtime, ContextBus, apiFetch, stores, memory, components
server/ Cloudflare Pages Worker: guard, 18 endpoints, providers, agent runtime, MCP client
tools/ the build system: bundler, dev server, deploy preflight -> build.js
- No framework.
shared/element.tsis a JSX factory that creates real DOM. No virtual DOM, no diffing, no npm runtime dependency in the browser. - Micro-frontends, one bundle. Each app compiles independently; the build strips modules and concatenates everything into one IIFE. Apps see each other only through generated ambient types and talk to each other only through
shared/Modules/ContextBus.ts. - One guard, two runtimes.
server/lib/security.ts— method check, origin allowlist, size caps, three-class rate limiting, HMAC session tokens — runs in front of every/api/*call in both the deployed Worker and the local dev server, so local behaviour is production behaviour. - One registry for model identity. Every model id, base URL and config key name lives in
server/providers/registry.ts. Retiring a model is a one-line change. - Local-first storage. Conversations and the knowledge graph in IndexedDB, files and generated media in CacheStorage, settings in
localStorage. Nothing user-owned is stored server-side.
build.js at the repository root is the whole toolchain — bundler, dev server with watch loop, and deploy preflight. It is compiled output, generated from tools/*.ts by npm run build (tsc with outFile), and committed so that a fresh clone runs with npm install && npm start and no build step.
If you edit anything in tools/, run npm run build and commit the regenerated build.js alongside your change. The output is deterministic — the same sources always produce a byte-identical file.
Read docs/architecture/system-overview.md first; the eleven architecture documents cover each subsystem with validated diagrams and an honest list of what is still open.
- Ollama is local development only — a deployed Worker cannot reach
localhost. PointOLLAMA_BASE_URLat a reachable host to use it from a deployment. stdioMCP servers likewise exist only locally; a deployed workspace takes remotehttp/sseservers and says so in the UI.- The Anthropic, OpenAI and xAI code paths are covered by mocked tests. Ollama is the only provider exercised by live contract tests, so nothing in this repository has ever been run against a paid key.
Issues and pull requests are welcome. Before opening a PR:
npm run build && npm test # must be clean and 852/852
npm run test:e2e # if you touched the UI- Adding a provider? Start at
server/providers/registry.ts— every model id, base URL and config key lives there — then add a dialect module besideanthropic.ts/openai.ts/xai.tsand wire it intodispatch.ts. - Touching
tools/? Rebuild and commitbuild.jswith your change (see The build system). - Cross-app integration? It goes through
shared/Modules/ContextBus.ts— apps never import across theinput/·persona/·app/boundary. - Each architecture document ends with an Issues & Technical Debt section; those are real, current, and a good place to find a first contribution.
Our experienced consultants provide tailored support for deploying, integrating, and optimizing Cloud Nine AI to meet your unique business requirements. Services include:
- Cloudflare Deployment: Expertise in deploying AI-powered applications to Cloudflare for fast, edge-based solutions.
- Azure Integration: Support for setting up, deploying, and scaling on Microsoft Azure with robust security and enterprise features.
- Google Cloud Consulting: Custom integrations for Google Cloud services, enabling high-performance AI workflows.
- Model Optimization: Assistance in selecting and tuning the best models for your tasks, including hybrid or proprietary setups.
- Custom Development: Design and implementation of bespoke features or workflows tailored to your needs.
- Ongoing Support: Continuous updates, troubleshooting, and scaling assistance for your Cloud Nine AI deployment.
For consulting inquiries, contact us at cloud@scalabledynamicsllc.com.
MIT © Scalable Dynamics
Vendored browser libraries in public/js/ (d3, pdf.js, JSZip, docx, docx-preview) remain under their own licenses.