ramone-edge

┌─────────────────────────────────────────────┐
│  ATLAS SYSTEMS // ramone-edge               │
│  the public face of a private GPU           │
└─────────────────────────────────────────────┘

The only publicly addressable component of the Ramone ask-my-infrastructure system. Validates Turnstile, enforces rate limits, probes the tunnel for awake state, and pipes Server-Sent Events back from a FastAPI service running on SPECULAR-CORE through a Cloudflare Tunnel.

browser ─▶ ramone.atlas-systems.uk ─▶ ramone-edge (this worker)
                                          │
                                          │  X-Atlas-Secret + private CNAME
                                          ▼
                                ramone-tunnel.atlas-systems.uk
                                          │  cloudflared
                                          ▼
                              SPECULAR-CORE :8000 (ollama-rag-kit)
                                          │
                                ┌─────────┴─────────┐
                                ▼                   ▼
                            ChromaDB             Ollama (llama3.1:8b)

Routes

Method	Path	Description
GET	/	Standalone interface (HTML, no JS framework, embedded Turnstile)
GET	/status	Cached awake/asleep probe for the live indicator (30 s cache)
POST	/ask	Validated and rate-limited question proxy; streams SSE on success

Why a Worker in front of a Tunnel

The same reason every other service in the estate has a Worker in front of it. A naked FastAPI exposed through a Tunnel works, but the Worker buys five things the FastAPI shouldn't have to care about:

• A free, edge-resident Turnstile validation step that filters bots before any GPU work begins.
• KV-backed rate limits that survive Worker isolate eviction.
• A coherent origin allowlist so a third-party page cannot read the response.
• A cached wake-state probe so the Lab page status indicator does not hammer the tunnel.
• A single hop for the atlas-notify hook, keeping the FastAPI free of business-logic awareness about who else cares about its traffic.

Local development

npm install
npm run check       # node --check on every src/*.js
npm run lint
npm run test
npm run dev         # wrangler dev with --remote

Public Interface V2

The browser surface is a polished chat product expressed through the Atlas terminal/console visual language. It introduces Ramone personally, retains the “Ask my infrastructure.” command, explains the public knowledge boundary, and keeps the full conversation interface visible when SPECULAR-CORE is offline. The opening is one integrated workspace: a desktop knowledge rail sits beside the greeting, animated topology, availability notice, composer, and starter questions. The greeting types once per browser session, a separate musing line retains Ramone's character, and the workspace visibly condenses into retrieval activity when a question is submitted. Curated local personality responses work while Ramone is asleep and are explicitly labelled as having no evidence.

The accepted Atlas Interface Kit is vendored under assets/interface/v0.2.0/, verified against its manifest, and embedded into the Worker response. The Worker serves the exact pinned WOFF2 files from immutable same-origin routes, so the CSP can remain self-only and there is no browser-time dependency on Google Fonts, the kit repository, or another service. The matching OFL licence texts are retained in the vendored bundle.

npm run verify:interface  # verify the pinned bundle and its fingerprints
npm run build:interface   # deterministically regenerate the embedded module

Pull requests that touch the interface publish an isolated workers.dev preview. The preview has no production route, service binding, KV binding, schedule, or inference access. It deliberately reports SPECULAR-CORE as offline and returns a deterministic cited answer so the complete unavailable state and expandable evidence cards can be reviewed safely. CI captures Chrome and Firefox evidence at 320, 375, 768, 1024, and 1440 pixels.

If the interface bundle is absent, altered, or out of sync with its generated module, validation fails before deployment. If the production status request fails, the browser fails closed to the explicit offline explanation while the rest of the interface remains usable. Rollback is the normal Worker version rollback to the preceding deployment; no API route, binding, or local inference change is required.

Required secrets

wrangler secret put TURNSTILE_SECRET
wrangler secret put UPSTREAM_SECRET      # must match ollama-rag-kit ATLAS_SECRET
wrangler secret put NOTIFY_TOKEN

Required wrangler.toml replacements

Before first deploy, fill in:

• zone_id for atlas-systems.uk
• KV namespace id for the RL binding
• TURNSTILE_SITE_KEY

The site key is public and lives in [vars]; the secret key is a secret.

Tests

npm test

Coverage focuses on the security-critical and contract-critical paths: CORS origin enforcement, rate-limit math, the atlas-notify event shape, the public interface shell, its pinned design-system bundle, offline behavior, temporary session ownership, streaming source treatment, and isolated preview boundaries.

Interface conformance

Phase G adds a read-only product-surface declaration and pinned Atlas Infra validation without changing inference or edge behaviour. See docs/PHASE-G-INTERFACE-CONFORMANCE.md.

How it fits into Atlas Systems

ramone-edge is the bounded public gateway between the Atlas Systems web surface and local Ramone services. The edge layer owns browser-facing validation, rate limiting, wake-state checks, and streaming transport while local inference stays behind the tunnel.

It also reports operational failures through atlas-notify and follows the same fail-closed public/private boundary used by the wider estate.

The transferable principle is to put public trust boundaries at the edge and keep the local service focused on the work only it can perform.

---

Part of atlas-systems.uk