Aura

A local-first, provider-neutral AI agent platform — in Go.

An agent for ongoing work: tools, document retrieval, temporal memory, scheduled jobs, and a web cockpit on infrastructure you control.

What is Aura? · What it does · Architecture · Quick Start · Docs · Development

---

What is Aura?

Aura is a self-hosted, multi-user AI agent. Its Go binary hosts the runtime, tools, CLI, Telegram gateway, and embedded web cockpit; each person signs in to their own identity, with their own memory database, workspace and sandbox. Docker Compose runs Postgres, ArcadeDB, Garage, embedding, ingestion, web search, voice and the bundled integrations alongside it.

The model is chosen in the cockpit settings: OpenRouter (the default route), a ChatGPT plan, the bundled local llama.cpp server, or Ollama. Local storage does not make cloud inference offline: a cloud provider receives the context sent to its model; with a local server nothing leaves the host for inference.

Hardware: a mini PC with 16 GB of RAM is enough. The default stack measured 7 GB with speech-to-text and text-to-speech running on a 16 GB mini PC (2026-09-02). No local LLM runs by default: inference goes to the provider you choose.

_{A real run on a local stack: Aura stores the fact in its memory graph, loads the deferred task tool and schedules the reminder; a new chat then answers from memory, with provenance. Model replies were written by Claude through an OpenAI-compatible endpoint; waiting time is trimmed.}

What it does

• Streaming agent loop with shared step/time budgets and repeated-call controls to bound work.
• Deferred tools and tool_search — discover tools and load their schemas when needed, including tools from mounted MCP servers.
• Adaptive reasoning router — selects reasoning effort using the configured classifier and the active model's supported capabilities.
• Full host terminal + filesystem tools — real operating power, with destructive-command approval gates and secret redaction.
• Graph-native memory — facts, sources and validity windows in ArcadeDB; temporal paths return supporting evidence. Postgres-authoritative conversations have a derived recall projection and managed context compaction.
• Document retrieval — indexed passages with source hashes and citations, plus access to the original file for calculations and whole-file tasks.
• Self-extension — author and run skills, use bundled memory/PIM/WhatsApp integrations, and connect additional MCP servers.
• Scheduler and self wake-ups — one task tool (at | every | cron) for reminders and agent_job runs, with job policy, operator controls and outcomes delivered to the owning conversation.
• Per-identity sandbox — a full-capability box per operator (opt-in sandbox profile; runc, behind an egress floor), with deliverables handed back over the channel (send_file), never as a path.
• Multi-user — Authula sign-in (password, plus a TOTP step for accounts enrolled in it), one isolated ArcadeDB database per identity enforced by the server, capability grants, and an admin audit view.
• Multi-channel — CLI REPL, Telegram (voice/photo/docs/HITL), and a web cockpit over AG-UI/SSE with mid-turn steering, approvals, voice input/output, and live settings.
• Studio — image and video generation in the cockpit (docs/STUDIO.md).
• Documents, photos and video — the agent edits spreadsheets, Word documents, decks, PDFs, photos and video sequences through the Craft apps' MCP servers, run in the identity's box and fenced to its workspace.
• Bundled integrations — calendar/e-mail (PIM MCP, OAuth providers), WhatsApp (unofficial client), web search through a bundled SearXNG, snapshot share links to a conversation, and Cloudflare remote access.

Where Aura sits next to Open WebUI and LibreChat: docs/COMPARISON.md.

Architecture

Transport & UX     cmd/aura (CLI) · channels (+telegram) · agui (SSE) · webui (embedded SPA) · webauth (Authula) · setup · askuser
Agent runtime      agent (LlmAgent, Budget, Events, hooks, workflow Seq/Par/Loop) · runner · swarm · steer
Tools & MCP        agent/tools (registry, deferred, tool_search, fs/shell/web/skill) · agent/mcptools · mcp (+manager) · mcpoauth · sandbox
Intelligence       llm (+openai_compat) · chatgptplan · semindex (embed-index core) · reasoningtrace · scoring · multimodal · mediagen
Capabilities       web · skills · cron · onboarding · documents · share · retention
Persistence        db (Postgres+sqlc) · arcadedb (memory + retrieval) · conversations · identity · objectstore · secret · settings
Observability      obs · agent/panicobs · reasoningtrace · toolinvocations · cachemetrics

Tech stack

Language	Go 1.27
Persistence	Postgres (sqlc, pgx) + ArcadeDB (graph memory, full-text + LSM vector index) + Garage (S3 object store)
Models	Default DeepSeek-V4 Flash via OpenRouter; also a ChatGPT plan, the bundled llama.cpp server (Gemma 4 12B QAT, localllm profile) or Ollama. The active profile (provider, model, budgets) is hot-reloaded from the cockpit settings, no restart
Cockpit	React SPA embedded in the binary, served behind Caddy and the Authula sign-in
Tests	Unit, property, race, leak, mutation, live integration, and browser tests; owned-surface coverage ≥85%
CI	build/vet/lint · CodeQL · -race + goleak · db/ArcadeDB/embed integration · MUSR two-identity E2E · web lint/test/mutation/Playwright · critical mutation ≥70% killed
Distribution	Docker Compose appliance; edge tracks master, v1.2.0 is the latest tagged release (checked 2026-10-24)

Project structure

cmd/aura/                CLI entry and subcommands
cmd/arcadedb-mcp/        Aura's own ArcadeDB memory MCP server
cmd/aura-*/              sidecar binaries (Cloudflare and ingest supervisors, media index, file cards)
internal/                the runtime, one package per concern (see Architecture)
web/                     React cockpit, embedded into the binary from internal/webui/dist
services/ingest/         document ingestion sidecar
packages/create-aura/    the npx installer (create-aura-appliance)
docker/ deploy/ caddy/   image builds, systemd units and the updater, Caddy front door
scripts/                 install, smoke, restore drill, coverage, file-size cap
docs/                    install, architecture, capabilities, release and backup guides
.planning/               GSD planning artifacts

Quick Start

You need Docker on the target (4 CPU cores, 14 GiB usable RAM, 20 GiB free disk) and Node.js 22.13+ on the workstation. The installer generates .env, downloads the Compose assets and starts the stack, locally or on a Linux host over SSH:

npx create-aura-appliance                 # local
npx create-aura-appliance --mode remote   # Linux target over SSH

Then open https://<host>, create the first user (the operator), and let the cockpit's first-run setup pick the model route, the OpenRouter key and the optional Telegram bot.

Windows (Docker Desktop), the curl installer, release channels, the local CA, updates and WhatsApp pairing: docs/INSTALL.md.

Documentation

Doc	For
docs/INSTALL.md	Install and operate — Linux/macOS/Windows, release channels, first access, updates, sidecars
docs/ARCHITECTURE.md	How the system is built — layers, turn lifecycle, invariants
docs/TECHNICAL_OVERVIEW.md	CTO / due-diligence overview — problem, differentiators, maturity
docs/CAPABILITIES.md	Capability matrix — shipped / in-progress / roadmap
docs/STUDIO.md	Studio — image and video generation, photo and multi-track video editing
docs/COMPARISON.md	How Aura compares with Open WebUI and LibreChat
docs/CLI.md	CLI reference — every aura subcommand
docs/BACKUP-RESTORE.md	Backup schedules, restore drill, manual restore, recovery scope
docs/release-readiness.md	How a release is cut — the eleven-report exact-SHA gate, operational checks
CLAUDE.md · prd.md	Engineering guidance · product requirements (source of truth)

Development

Go from go.mod, Docker and a POSIX shell (Linux, or WSL on Windows):

git clone https://github.com/chetto1983/Aura.git
cd Aura
cp .env.example .env
make tools && lefthook install
make quality                    # vet + lint + deadcode + race + vuln + build, no containers
make db-migrate memory-up       # bring the stack up
make quality-full               # quality + coverage gate

Source builds, the local image, make targets and the review discipline: CONTRIBUTING.md. Report vulnerabilities privately per SECURITY.md, never in a public issue.

License

MIT Copyright 2026 Davide Marchetto.