Aura Terran setup guide

Prerequisites

Hardware

• Operating system — Windows
• Memory — 32 GB RAM
• Processor — Intel Core i7 or equivalent
• GPU (optional) — NVIDIA RTX 3090 or equivalent recommended when using Ollama for local models

Software

• Windows — download the installer from the download page
• Documents to index — folders or files for your namespaces (Markdown, PDF, plain text, and more)
• Optional: MCP clients (Cursor, Claude Desktop) if you want rag_search over your corpora
• Optional: Ollama or an OpenAI-compatible API if you enable a chunking LLM during ingest

Installation

Download the latest Windows installer from the download page (currently v1.12.22).

1. Run AuraTerran-Setup-1.12.22.exe
2. Complete the installer — Aura Terran runs locally with auto-updates enabled
3. Launch the app from the Start menu

Configuration

Most settings are configured in the desktop app under Settings — not via hand-edited config files for day-to-day use.

• General — tray behavior, startup, indexing performance, and update checks
• Chunking — chunk size, overlap, intelligent splitting, and optional chunking LLM
• Retrieval — hybrid search, top-K, score thresholds, reranking, and always-inject behavior
• Management API — port, auto-start, and bearer token for scripts and automation
• Passthrough — OpenAI- and Ollama-compatible listeners that retrieve, inject context, then forward to your upstream LLM (Personal+)
• MCP Server — inbound rag_search for IDE clients
• External MCPs — third-party tool servers in the passthrough loop (Pro+); tool policy on Teams
• Web search — optional web results blended with corpus retrieval (Pro+)
• License — activate a paid key under Settings → License

Beyond Settings, use in-app canvases to keep retrieval honest: Retrieval Lab (Tune A/B + Baseline regression guard), Grounding (claim support vs injected chunks), and Conflicts (auto-settlement, Activity log, and authority tiers).

Default ports (configurable): Management API on 3000, inbound MCP on 3100. Passthrough listener ports are set under Settings → Passthrough.

Adding documents

Use the Ingestion tab to point Aura Terran at folders or files and pull them into a namespace (for example work-docs, personal-notes).

1. Create or select a namespace
2. Ingest folders or files — embeddings are built automatically
3. Confirm indexing finished in the Vector Store view before querying

Each namespace is an isolated corpus: its own documents, embeddings, and retrieval scope.

Optional chunking LLM

Core search uses on-device embeddings by default and does not require OpenAI or Ollama. Optionally, under Settings → Chunking, point at Ollama or an OpenAI-compatible API to refine split boundaries during ingest only — not on every search.

At answer time you can either point OpenAI- or Ollama-shaped clients at Aura's passthrough listeners (Aura retrieves, injects context, then forwards to your upstream LLM), or call Management API / inbound MCP for ranked chunks only and run the completion in your own client.

Running the app

Start Aura Terran from the Start menu. The Server tab shows status for:

• Management API — corpus search, ingest, and admin API
• Passthrough — OpenAI / Ollama listeners with RAG-in-the-loop
• MCP Server — rag_search for external MCP clients
• External MCPs — third-party tools coordinated alongside RAG (Pro+)

Copy the bearer token from Settings before calling REST or MCP from scripts or IDE bridges. /health stays open for liveness checks without a token.

Using retrieval

Use one of these paths to get local corpus context into your tools:

• Search UI — tune and debug retrieval inside the app
• Retrieval Lab — A/B two retrieval configurations on a labelled question set before changing settings
• Grounding — when using passthrough, see which claims the injected chunks actually support
• Conflicts — find near-identical passages that disagree before a stale copy answers a question
• LLM passthrough — point OpenAI- or Ollama-compatible clients at Aura (Personal+); Aura injects context then forwards to your configured upstream
• Management API — POST /admin/corpus-search for ranked chunks from scripts or custom agents
• MCP — call rag_search from Cursor or Claude Desktop

With Management API or MCP, inject returned chunks into your agent's prompt, then call your chat model yourself. Prefer passthrough when you want Aura to inject and verify answers automatically. Always double-check critical decisions against source documents — retrieval quality still depends on your corpus, chunking, and prompts.

Works with Aura Wire (optional)

Terran is a standalone product. Wire’s Terran stage is a bridge that injects this corpus into Wire chat. Index once here; enrich every Wire chat — or keep using passthrough and MCP when that fits better. Paid Terran (Personal, Professional, and Teams) includes the Wire bridge entitlement at no extra charge; Terran Free does not. Buying Wire does not include Terran — you still need a local Terran install to inject ranked chunks.

1. Keep Direct RAG REST enabled (default http://127.0.0.1:41800)
2. In Wire, open Pipeline → Aura Terran → Connection, enable the stage, and set the REST URL, namespace, and search options
3. Confirm the IDE gRPC injection map shows Ready, then watch enrich/skip metadata in Live Traffic — never chunk text

See the Wire Terran stage for full setup notes. If Terran is offline, Wire forwards without injection (fail-open).

Troubleshooting

Indexing fails or hangs

Check disk space, file permissions, and embedding provider connectivity. Review in-app logs and the Server tab.

No results or poor answers

Confirm the right namespace is active and documents finished indexing. Tune chunking and retrieval in Settings.

REST or MCP client cannot reach Aura Terran

Verify the listener is enabled, the port matches your client config, and you send the bearer token from Settings.

Chunking LLM errors

Check the Ollama or OpenAI-compatible base URL and model name under Settings → Chunking. Retrieval works without a chunking LLM.

Bugs and feature requests

Contact Halo Softworks with steps to reproduce, versions, and error messages.

Known limitations

• Windows installer is the primary distribution today
• Retrieval quality varies with document quality, chunking, and namespace design
• Generated answers should be validated for critical use cases
• Large corpora may require tuning chunk size, hardware, and retrieval settings

For product overview, see the Aura Terran product page.