Own Your AI (OYA) Quickstart, as shipped in the download

# Getting Started

## One-minute overview

`oya` is a local AI agent that proves it never phoned home. You run it on your machine, it talks to a local model you control, and when you're done you get a **signed report** showing exactly what happened, who it contacted, what it accessed — and cryptographic proof nothing was added or edited after the fact.

## Your first run

### 1. Start a model server

You need a language model running. Pick one:

```bash
# llama.cpp (recommended, ~1GB for small models)
llama-server -m path/to/model.gguf -p 8081

# Or: Ollama
ollama run qwen2:7b  # runs on port 11434 by default

# Or: LM Studio (graphical app, runs on port 1234)
```

If you don't have a model yet, `oya` can help — see **Model Selection** below.

### 2. Start oya

```bash
oya serve --web --yes --port 8770
```

Then open **http://127.0.0.1:8770** in your browser.

### 3. Talk to it

Click **"Chat"**, type a prompt, press Enter. It detects your model automatically.

Done. Everything stays on your machine. No accounts, no API keys to a vendor, no telemetry.

## Model Selection

If you don't have a model server running, `oya model setup` walks you through it:

```bash
oya model setup
```

It measures your hardware (GPU VRAM if visible, else RAM), recommends models that fit safely with headroom for context, shows their size and license, and can download one from HuggingFace if you say yes.

**In the web app:** click **"Manage engine"** (sliders icon, top bar) → **"Choose a different model"** to see the full catalogue.

## Understanding isolation

By default, `oya` runs with **network isolation** — subprocess spawning is blocked, and the report says so. This is what lets it make a claim about non-egress that actually holds.

**Why it matters:** you can hand the signed report to a compliance officer and they can verify it, using a standalone tool, with zero trust in us. The number isn't a promise — it's a measurement.

If you need to run `git push` or `npm install`, toggle the **"Isolation"** switch in the sidebar (the one showing the number). It disables the sandbox for that run and updates the report to say so.

## The Signed Report

When you finish a session, click **"Export"** → **"Evidence Pack"** to download:

1. **The report itself** — what happened, who was contacted, every tool call
2. **The attestation chain** — hash-linked, signed entries so any edit is caught
3. **The tool inventory** — every tool used, with argument traces
4. **Compliance mappings** — how this run addresses GDPR, AI Act, DORA, NIS2

Everything in the pack cites the source file and field it came from. You can verify it offline with zero trust in the code — the verification tool has no dependencies and the public key is embedded.

## Security modes

- **Sealed (default)** — network isolation, subprocess caging, no outbound calls
- **Unsealed** — lets the agent run `git push`, `npm install`, and similar. The report says so.
- **Airplane** — harder isolation using a network namespace. Same as sealed for most purposes but you don't trust the sandbox implementation — the kernel enforces it.

Airplane requires Linux. On macOS and Windows, sealed uses `sandbox-exec` and WSL respectively, with a runtime probe that verifies it actually works.

## Commands you'll use

| What | Command |
|---|---|
| Start the agent | `oya serve --web --yes` |
| Just talk to the model once | `oya prompt "your question"` |
| Run a saved prompt/script | `oya run script.mjs` |
| Restore from a checkpoint | `oya resume agent-123` |
| See what's stored | `oya memory list` |
| Check isolation works | `oya isolation` |
| Export the evidence pack | `oya pack` |

Full reference in **Tools & Commands**.

## What's different from other agents

| | You get | Hosted agent doesn't |
|---|---|---|
| Proof of non-egress | ✓ Signed report + ledger | Only their word |
| Self-hosted | ✓ Runs on your machine | Cloud vendor owns the box |
| Offline | ✓ Works air-gapped | Requires internet |
| Verifiable isolation | ✓ Runtime probe | Trust their claim |
| Personal model | ✓ Your choice, your weights | Their model, their inference, their logs |
| No telemetry | ✓ We never know you exist | Vendors log everything |

The trade: you choose and manage the model, so inference is slower than a $10k GPU cluster. The gain: you know what happened, and you can prove it.

## Next steps

- **Run your first turn:** start a model, `oya serve`, click Chat
- **Pick a better model:** `oya model setup` or **Manage engine** in the web app
- **Understand the report:** see **Evidence & Compliance**
- **Integrate with your code:** see **Developer Guide** for the `/api` endpoints and ACP
- **Troubleshoot:** see **FAQ & Common Issues**