Own Your AI (OYA) manual: setup, settings and daily use

Own Your AI — sovereign local agent (v3.0 — frozen core)

An agent-first AI workbench that runs entirely against your own local model. Chat, documents and file access never leave your machine. Web search goes where you point it — your own SearXNG; there is no vendor fallback. No cloud, no telemetry, no per-token bill. Buy once, own the source.

Two surfaces, one engine: a browser web app (this folder — the first-ten-minutes surface) and a terminal CLI (cli/ — type oya, with a provable sovereignty guard). **What oya is and is not is fixed in SCOPE-FREEZE.md:** a frozen core that never contacts anyone and proves it, plus the pieces you choose — MCP servers, plugins, skills, data packs — which may reach anything you allow, with every host they contact shown in the ledger. No desktop app, no editor plugin, no messenger bridges in the core; those live outside it, as pieces or not at all.

Capabilities (frozen core): streaming chat · persistent conversations · RAG w/ citations · agent loop (native tool-calling + ReAct) with live trace · planner/worker/critic team · personas · persistent memory · skills · scheduling · read-aloud (local OS voices) · vision (image input to a vision-capable local model) · session search · Mixture-of-Agents · tool-approval gating · context compression · auxiliary-model routing · light/dark/system themes + accent picker · MCP client + runnable MCP servers · your own mailbox (IMAP/SMTP spoken directly), calendar files, file search, diff, hashes, downloads, redaction, PDF writing, SQL over your spreadsheets · the verifier (verify · isolation · compare · attest · pack · bundle). Tool and command counts are generated from the code into docs-site/, never typed here.

Why this exists

Cloud AI (Copilot, ChatGPT, notetakers) reads your data, bills per seat/token, and can disappear or change terms overnight. Free local chat UIs solve privacy but stop at chatting. Own Your AI is the missing piece: a private agent that does multi-step work — plans, uses tools, acts on your files, and checks itself — on hardware you control.

What it does

Streaming chat against any OpenAI-compatible local server (Ollama, llama.cpp, LM Studio, vLLM). Multiple conversations, all stored locally (IndexedDB).
Knowledge (RAG) — attach text files; they're chunked and embedded with your local model, stored on-device, and cited in answers.
Agent mode — a real tool-using loop (native tool-calling with a ReAct fallback) with a live trace (plan → action → observation → answer). Tools: docs, search (your SearXNG), calc, js, now, readUrl, and listFiles / readFile / writeFile in a folder you grant.
Team — optional planner → worker → critic, each on its own model.
Personas — saved system prompt + model + tool set (3 built-in, plus your own).
Backup — export/import everything as one JSON file you control.

Run it

Start a local model server — llama.cpp, LM Studio, Ollama or vLLM, anything serving an OpenAI-compatible API. With Ollama: ollama serve, then ollama pull llama3.1 and an embeddings model (ollama pull nomic-embed-text).
Install, from inside this folder:

   ./install.sh          # links `oya` onto your PATH and detects the model

Start the engine and the app — one command:

   oya up                # engine + browser app on http://localhost:8765

oya up is the way to run this. The engine is what gives the agent its full toolset — shell, files, search, git, checkpoints — plus the sovereignty guard and the egress ledger that make the claim checkable.

Opening the folder with a plain static file server still works, but you get the browser-only
toolset (a handful of in-page tools, no filesystem, no shell, no proof) and every capability this
product is sold on stays switched off. If the app shows ⚡ Enable full access in the top bar,
the engine is not attached and you are in that reduced mode — start it with oya up.

Privacy

The only network calls made on your behalf without asking are to the model endpoint you configure. Everything else is a tool you invoke — web_search reaches the SearXNG you configured, model setup reaches huggingface.co only after you say yes to a named download, the email bridge reaches your own IMAP/SMTP host, and any piece you add reaches what you allowed it to. The full classified host table is in the source (cli/oya.mjs, HOST_ROLES) and in every evidence pack, and the audit fails closed on any host it does not recognise. No third-party code, no analytics.

License

Commercial single-purchase, source included — see LICENSE.txt. One purchase covers your own machines (personal) or your organization's internal use; no redistribution or reselling; models are licensed separately by their publishers; verifier reports are evidence, not certification.

Architecture (no build step)

Vanilla ES modules: store (settings), db (IndexedDB), llm (streaming chat + embeddings), rag (chunk/embed/retrieve), tools (registry), agent (loop + team), fs (File System Access), main (UI). Read it, change it, keep it running forever — source included. If we vanish, your install doesn't.

For contributors

Working notes, audits, build plans and session handoffs live in docs/internal/ — they are the project's scaffolding, not its documentation, and were moved out of the root so that what a new reader sees first is the product.

docs/OPEN-ITEMS.md — known limitations: everything deferred or known-limited, and why