DialectOS full-app demo, explained like you are five

This demo is for testing the real product path from a browser.

The tiny mental model

Imagine three blocks:

1. Browser page — the buttons and text box you click.
2. DialectOS backend — the safe middleman. It receives browser requests and calls DialectOS code.
3. Model/provider — the brain that actually writes the translation.

The browser must not call the model directly because that would expose API keys and skip server-side checks.

So the flow is:

browser -> DialectOS demo backend -> provider registry -> local/cloud model

When should something go in a container?

Use a container when setup would otherwise be annoying or inconsistent.

Good container uses:

• You need Node, pnpm, build steps, and server startup to work the same way for everyone.
• You want to deploy the same thing locally, on a VPS, or in staging.
• You have multiple moving parts and want one command to start them.

Bad container uses:

• Storing secrets inside the image.
• Baking a huge model file into the app image when a model volume/sidecar is cleaner.
• Hiding broken setup instead of documenting it.

Local mode: easiest if you already have LM Studio or another model server

Start your model server first. It needs to expose an OpenAI-compatible chat endpoint.

Then run:

LLM_API_URL="http://127.0.0.1:1234/v1/chat/completions" \
LLM_API_FORMAT="openai" \
LLM_MODEL="your-local-model-name" \
LLM_ALLOW_LOCAL=1 \
pnpm demo

Open:

http://127.0.0.1:8080

What happens:

• pnpm demo builds DialectOS.
• It starts scripts/demo-server.mjs.
• The page calls /api/translate.
• The server calls the real provider stack with semantic dialect prompts.

Container mode: app container plus model container

This repo includes:

• Dockerfile.demo — builds the DialectOS demo backend image.
• docker-compose.yml — starts the demo backend and an Ollama model service.

Start the model container first:

docker compose up -d ollama

Download the model into the persistent Ollama volume:

docker compose --profile setup run --rm ollama-pull

Start the full demo:

docker compose up --build demo

Then open:

http://127.0.0.1:8080

What each container does:

• demo is the website plus DialectOS backend.
• ollama is the local model server.
• ollama-pull is a one-shot setup helper that downloads the model.
• ollama-models is a persistent volume, so the model does not download again every time.

VPS mode, like Hostinger

A VPS is useful for staging because other people can open a real URL.

Recommended VPS shape:

public HTTPS URL
  -> reverse proxy
  -> DialectOS demo container
  -> provider endpoint

The provider endpoint can be:

• an Ollama sidecar if the VPS is strong enough,
• a remote LM Studio/OpenAI-compatible endpoint,
• or a cloud model provider.

CPU-only VPS warning: local models can be slow without a GPU. The VPS can still host the web/API layer while the model runs somewhere else.

Safety rules

• Never put API keys in browser JavaScript.
• Never commit .env files.
• Never expose a public demo without rate limits/auth if it uses paid providers.
• If /api/status says no provider is configured, fix the model/provider first.