Skip to content

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

☁️ Cloud Nine AI

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

License: MIT Node Tests Runtime deps Deploy

Cloud Nine AI workspace — animated persona avatar above a mobile-first composer with camera, microphone and screen-share controls

Why this exists

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.


⚡ Quickstart

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:8080

Open 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 + embeddings

Leave every key in config.json empty. 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.


🚀 What it does

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.

💬 Chat

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 —

📎 Context

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)

🧠 Memory, agents and tools

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 —

🎨 Media, search and voice

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/.


🔧 Configuration

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.


✅ Tests

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.


⚙️ Deployment

Cloudflare Pages

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 deploy

npm 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 publish deletes build/ and refills it with the minified release bundle, and a running dev server is watching that folder. It now notices (the release build writes build/build-info.json last, with mode: "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.


🛠️ Architecture

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.ts is 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.

The build system

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.

Known limits

  • Ollama is local development only — a deployed Worker cannot reach localhost. Point OLLAMA_BASE_URL at a reachable host to use it from a deployment.
  • stdio MCP servers likewise exist only locally; a deployed workspace takes remote http/sse servers 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.

🤝 Contributing

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 beside anthropic.ts / openai.ts / xai.ts and wire it into dispatch.ts.
  • Touching tools/? Rebuild and commit build.js with your change (see The build system).
  • Cross-app integration? It goes through shared/Modules/ContextBus.ts — apps never import across the input/ · 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.

💼 Consulting Services

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.


⚖️ License

MIT © Scalable Dynamics

Vendored browser libraries in public/js/ (d3, pdf.js, JSZip, docx, docx-preview) remain under their own licenses.

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages