Gateway · :8080
OpenAI-compatible entry point, authentication, routing, integrations, metering, and health.
Customer documentation · v1
Operate workplace AI inside your perimeter.
Ovrion is delivered as a container you run on infrastructure you control. Bring an OpenAI-compatible model backend, connect the workplace channels you need, and keep prompts and responses in your own request path.
Customer-owned runtimeOpenAI-compatible APIExplicit send semantics
No hosted Ovrion inference serviceThe public website and documentation are hosted by Ovrion. Your model traffic is not. Production inference runs on your hardware or your own cloud account.
01 · Deploy
Run the released image
Ovrion ships as ghcr.io/finsavvyai/ovrion. Pin a commit-SHA tag for reproducible deployments; use latest only when you intentionally want the newest release.
docker pull ghcr.io/finsavvyai/ovrion:latest
docker network create lunacluster-net
export BACKEND_URL="http://host.docker.internal:1234/v1"Start the master
docker run -d --name lunacluster-master --network lunacluster-net \
-e LUNACLUSTER_MASTER_HOST=0.0.0.0 \
-e LUNACLUSTER_MASTER_PORT=8000 \
-v lunacluster-key:/root/.lunacluster \
ghcr.io/finsavvyai/ovrion:latest \
python3 -m src.core.start_masterStart a model worker
The image does not bundle model weights. Point the worker at LM Studio, Ollama, vLLM, llama.cpp, or another OpenAI-compatible server you operate.
docker run -d --name lunacluster-worker --network lunacluster-net \
-e LUNACLUSTER_MASTER_HOST=lunacluster-master \
-e LUNACLUSTER_MASTER_PORT=8000 \
-v lunacluster-key:/root/.lunacluster \
ghcr.io/finsavvyai/ovrion:latest \
python3 -m src.workers.proxy_worker \
--backend "$BACKEND_URL" --master lunacluster-masterStart the gateway
docker run -d --name lunacluster-gateway --network lunacluster-net \
-p 8080:8080 \
-e LUNACLUSTER_MASTER_HOST=lunacluster-master \
-e LUNACLUSTER_MASTER_PORT=8000 \
-e LUNACLUSTER_GATEWAY_HOST=0.0.0.0 \
-e LUNACLUSTER_ADMIN_TOKEN="$(openssl rand -hex 32)" \
ghcr.io/finsavvyai/ovrion:latest \
python3 -m src.api.gateway --master-host lunacluster-master \
--host 0.0.0.0 --port 8080Use the shared key volumeThe master and worker share
~/.lunacluster/cluster.key through lunacluster-key. For workers on another host, distribute LUNACLUSTER_API_KEY through your secret manager.02 · Develop
Run locally in one command
On macOS, deterministic development mode installs a local backend, master, proxy worker, and gateway as launchd services. Stub answers are always marked simulated: true.
./scripts/bin/install_launchd.sh install \
--dev-stub --rate-limit 5000 --no-auth
./scripts/bin/install_launchd.sh statusFor real inference, start LM Studio on port 1234 and replace the development backend:
./scripts/bin/install_launchd.sh install \
--backend http://localhost:1234/v1 --no-auth03 · Observe
Health means ready to answer
GET /health returns HTTP 200 only when the master is reachable and at least one online worker advertises a usable model. An online heartbeat with zero models is degraded and returns HTTP 503.
curl http://localhost:8080/health
curl http://localhost:8080/v1/models
curl http://localhost:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"luna-fast","messages":[{"role":"user","content":"hello"}]}'| Field | Meaning |
|---|---|
master | Whether the gateway can reach cluster coordination. |
workers.usable | Online workers currently advertising at least one model. |
models_available | Unique concrete models available across usable workers. |
status | healthy is HTTP 200; degraded is HTTP 503. |
04 · Understand
A small, inspectable request path
Master · :8000
Worker registration, heartbeat state, model inventory, and cluster coordination.
Worker · :8005+
Forwards requests to a model backend you control and advertises only currently available models.
Model backend
LM Studio, Ollama, vLLM, llama.cpp, or another OpenAI-compatible runtime.
Completion responses identify the selected worker and model. Provenance confirms which customer-controlled node answered the request.
05 · Connect
Workplace integrations
Slack
Signed events, slash commands, interactions, mentions, direct messages, and thread replies.
Microsoft Teams
Bot Framework JWT verification, mention stripping, plain replies, and Adaptive Cards.
Outlook
Delegated OAuth, draft replies, thread summaries, and tentative calendar responses without organizer notification.
Google Workspace
Domain-wide delegation for Gmail drafts, thread summaries, and Calendar tentative responses.
Signed Business Cloud webhooks and explicit outbound replies through Meta's API.
Word + PowerPoint
Customer-configured gateway, selected-document context, and insertion at the current selection.
Local integration testingSet
OVRION_BILLING_DISABLED=1 only in development. Production integrations require an active subscription.06 · Verify
Know exactly what can send
| Channel | Behavior | Enforcement |
|---|---|---|
| Outlook | Draft-only; no mail send. | Mail.Send is excluded at OAuth consent and no send method exists. |
| Gmail | Draft-only by Ovrion code. | Code-level only: Google's draft-capable scopes also technically grant send. |
| Calendar | Tentative response without notifying the organizer. | Microsoft uses sendResponse: false; Google uses sendUpdates=none. |
| Slack + Teams | Webhook response returned inline. | Signed inbound requests; Ovrion does not independently call a send API in this path. |
| Outbound reply is sent. | Explicit Meta Business Cloud API call; this channel is not draft-only. |
07 · Scale
Prepaid GPU, bounded by design
The GPU wallet meters customer-triggered RunPod capacity by the second. Charges use the raw provider rate plus the configured Ovrion margin, recorded in an append-only local ledger.
- Credits are prepaid through a one-time purchase.
- The running pod is debited every 30 seconds using actual elapsed time.
- The pod stops before the wallet can become negative.
- Provider rate, margin, elapsed time, and balance remain visible.
Two separate commercial gatesThe workplace subscription unlocks integrations. GPU credits pay for burst compute. One does not silently include the other.
08 · Recover
Troubleshooting
Health returns 503 with zero usable workers
Check the model backend first. Its /v1/models endpoint must return at least one model. The proxy worker refreshes model discovery on its heartbeat.
curl http://localhost:1234/v1/models
curl http://localhost:8005/health
curl http://localhost:8000/cluster/nodesWorker registration is rejected
Master and worker must share the internal cluster key. Use the same Docker volume on one host or set the same LUNACLUSTER_API_KEY through your secret manager across hosts.
Gateway returns 429
A client exceeded the configured request window. Correct accidental polling loops first; increase LUNACLUSTER_RATE_LIMIT_REQUESTS only when the traffic is intentional.
No documentation sections match your search.