---

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.

At a glance

Key features

• 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; gVisor runsc on native Linux), 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, photo and video editing, and a multi-track video editor, all in the cockpit (details).
• 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.

Studio

The cockpit's creative workspace, per identity.

• Generate images and video from a prompt over OpenRouter's media models. The model picker shows each model's price (per image, per second or per million output tokens) and the estimated cost before you press Generate. Options cover resolution, aspect ratio, seed, and duration and sound for video; advanced inputs take a start frame, an end frame and reference images from your library. Every generation lands in a searchable history you can reuse or download. Generation needs the OpenRouter route.

• Edit photos and clips in the browser: a photo editor (Filerobot) and a quick video editor (trim, crop, rotate, audio) for any image or clip in a chat or in the Garage library.

• Multi-track video editor:

  • a video lane plus overlay lanes for titles and images, with transitions between clips;
  • per-clip transform (fill, fit, crop, flip, rotate), adjustments (opacity, brightness, contrast, saturation, hue, blur), animations and speed;
  • audio lanes for an uploaded sound, a recorded voice, a text read aloud, or the sound extracted from a clip, with noise reduction, fades and automatic ducking under speech;
  • undo and redo, saved projects, a mobile layout, and an export rendered in the browser (video, or the audio alone as WAV).

  A generated video opens in the editor with one click.

How Aura compares

Checked on 2026-10-03 against each project's own documentation. Open WebUI and LibreChat are mature, much larger projects; this table shows where Aura differs, not that it is ahead.

Choose Open WebUI or LibreChat for a polished multi-model chat front end with SSO and a large ecosystem. Choose Aura for a long-running personal agent that remembers over time, works on a schedule and reaches you on Telegram or WhatsApp.

Architecture (one screen)

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

Documentation

---

Deployment (Docker Compose appliance)

Aura is a self-hosted agent runtime packaged as a Docker Compose appliance. The default stack brings up Aura (with its migration one-shot), Postgres, ArcadeDB and its MCP, Garage, the local embedding sidecar, document ingestion, SearXNG, speech-to-text and text-to-speech, the PIM and WhatsApp MCP sidecars, the Cloudflare tunnel supervisor (idle until enabled), and Caddy in front of the Authula sign-in. Compose profiles add the rest: localllm (a llama.cpp server with Gemma 4 12B QAT), ocr, observability (Prometheus, Tempo, Grafana) and sandbox (the Docker socket proxy for per-identity boxes).

Quick Start

Releases. ghcr.io/chetto1983/aura:<tag> and the binary archives are published by the Release workflow on a v* tag, and only after the exact-SHA Production Readiness check passed for that commit (docs/release-readiness.md). Check the Releases page for the current tag (v1.0.2-rc1 is the latest) and use it as vX.Y.Z below. Independently of releases, every master push publishes the moving ghcr.io/chetto1983/aura:edge image (plus an immutable master-<sha> tag) — the continuous-delivery channel a default install tracks.

Linux or macOS

The interactive installer supports local installation or a Linux target over SSH:

npx create-aura-appliance
npx create-aura-appliance --mode remote

It requires Node.js 22.13 or newer on the workstation. The target needs at least 4 CPU cores, 14 GiB usable RAM, and 20 GiB free disk; documents, models and backup retention need additional capacity. The installer detects the embedding backend on the target: CUDA for an NVIDIA GPU Docker can drive, otherwise Vulkan for an Intel or AMD GPU exposing /dev/dri, otherwise CPU. See the installer guide for supported targets and prerequisites. The npm installer carries its own payload.

The source-hosted installer remains available:

Install Docker, then run the installer. One command on a machine with Node 18+ (npx fetches the repo and runs scripts/install.sh):

sudo npx github:chetto1983/Aura -- --appliance

or the curl equivalent of the same script — use master to track the edge channel, or a release tag vX.Y.Z to pin:

curl -fsSL https://raw.githubusercontent.com/chetto1983/Aura/master/scripts/install.sh | sudo bash -s -- --appliance

The installer checks hardware, creates .env with generated POSTGRES_PASSWORD, the three ARCADEDB_* secrets, and AURA_ACCESS_TOKEN, downloads the Compose/Caddy assets, and starts the stack. Re-running it keeps an existing .env intact. A master/edge install points .env at the :edge moving tags, and --appliance also enables the aura-image-update systemd timer: from then on the machine re-pulls aura and its MCP sidecars from GHCR on its own, migrations and Compose payload included, with no operator involved. Without --appliance (no systemd units, no timer), the stack still starts; updates stay manual.

The default stack also starts the Cloudflare supervisor healthy-idle. Enable it after setup in Settings > Remote access; the installer requires no Cloudflare credential. Existing edge appliances receive the sidecar through the payload updater without replacing database volumes. See Cloudflare Remote Access for registered-domain prerequisites, Access OTP, organization WARP, token refresh and safe disable/delete.

Add --gvisor on native Linux Docker hosts that should run Aura under runsc. Docker Desktop is intentionally not supported for that isolation tier.

Windows

Use Docker Desktop and the shipped Compose files. From PowerShell in the Aura checkout or release directory:

function New-Hex { -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) }) }
@"
POSTGRES_PASSWORD=$(New-Hex)
POSTGRES_USER=aura
POSTGRES_DB=aura
ARCADEDB_PASSWORD=$(New-Hex)
ARCADEDB_APP_PASSWORD=$(New-Hex)
AURA_ARCADEDB_TENANT_SECRET=$(New-Hex)
AURA_IMAGE=ghcr.io/chetto1983/aura:vX.Y.Z
AURA_ACCESS_TOKEN=$(New-Hex)
AURA_AUTHULA_SECRET=$(New-Hex)
SEARXNG_SECRET=$(New-Hex)
AURA_OBJECTSTORE_ACCESS_KEY=GK$((New-Hex).Substring(0,24))
AURA_OBJECTSTORE_SECRET_KEY=$(New-Hex)
GARAGE_RPC_SECRET=$(New-Hex)
AURA_GARAGE_ADMIN_TOKEN=$(New-Hex)
AURA_BACKUP_DIR=./backups
AURA_EMBED_REVISION=0f741b5a6585bd53aeb15cd1372c56f2a0f65e12
AURA_EMBED_FINGERPRINT=b5ce9d77a3fc4b3b39ccb5643c36777911cc4eb46a66962eadfa3f5f60490d63
AURA_EMBED_NGL=99
"@ | Set-Content -Path .env -Encoding ascii

docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi
docker compose up -d

This .env targets an NVIDIA GPU: the embedding sidecar reserves one, so fix Docker/NVIDIA before starting Aura if the nvidia-smi container check fails. Without an NVIDIA GPU, run embeddings on the CPU instead: set AURA_EMBED_NGL=0 and COMPOSE_FILE=compose.yaml;compose.cpu.yaml (; is Compose's path separator on Windows), which drops the GPU reservation and selects the CPU build of the pinned llama.cpp server.

The model route, the OpenRouter key and the Telegram bot token are not .env settings: choose them in the first-run web setup, and Aura keeps them in aura.settings. For local development images, replace AURA_IMAGE with aura:local after building the image.

Postgres 18 is the default Compose image for new installs. When upgrading an existing Aura deployment from Postgres 17, migrate the data with pg_dump / pg_restore or pg_upgrade; a Postgres 18 container cannot reuse a Postgres 17 data volume directly.

Access

Aura listens on loopback; Caddy serves the cockpit on HTTPS at https://<host>, behind the Authula sign-in. On a fresh install the sign-in page offers Create first user: that account is the operator, and after signing in the cockpit's first-run setup finishes the configuration. The Telegram bot is connected through the setup wizard, gated by the access token the installer prints:

https://<host>/setup/?token=<AURA_ACCESS_TOKEN>

Caddy uses tls internal. Browsers on other LAN machines will warn until they trust the local CA root from the caddy-data volume:

docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt > aura-caddy-root.crt

Trust on the Ubuntu server does not make remote browsers trust that CA. Cloudflare named-tunnel hostnames use the public edge certificate; direct port 443 bypasses Cloudflare Access and retains Authula. Quick Tunnels are temporary testing only and cannot validate Aura chat because they do not support SSE.

Updates

An edge appliance installed with --appliance updates itself: the aura-image-update.timer (5-minute cadence, flock-guarded) pulls the moving tags and recreates only what changed, running migrations first. The aura image also carries the installation payload — the Compose files, the updater and its units, the sidecar configuration — and each tick installs whatever differs from /opt/aura (backing up what it replaces under backups/payload-*) and brings the whole stack up on it. A version pin changed in compose.yaml therefore reaches every appliance on its own. sha256sum -c payload_manifest.txt inside /opt/aura shows whether a host matches its payload. Watch it with journalctl -u aura-image-update.service -f.

Manual update (pinned installs, or no systemd). Volumes persist, and the aura-migrate one-shot runs the Postgres migrations before the Aura service starts (ArcadeDB needs none — the MCP creates each identity's database on first use):

docker compose pull
docker compose up -d

Backup And Restore

Scheduled backups run inside the socketless Aura box. Postgres is dumped over the Compose network with pg_dump into AURA_BACKUP_DIR:

./backups/postgres-YYYYMMDDTHHMMSSZ.dump

Memory is backed up automatically. ArcadeDB loads docker/arcadedb/backup.json and backs up every database every 60 minutes, including newly-created identity databases. Archives live in the separate aura-arcadedb-backups volume. The configuration sets maxFiles=60 and tiered hourly/daily/weekly/monthly retention of 24/7/4/6.

The database and backup volumes are separate, but both are on the same host by default. Preserve off-host copies and the deployment configuration separately. Garage objects, workspaces, and other runtime files need their own backup policy.

Run the restore drill against the current Compose stack:

set -a
. ./.env
set +a
scripts/restore_drill.sh

The drill tests four planes: Postgres, conversation sidecars, Garage and an ArcadeDB database shaped like a tenant. It verifies restored checksums and cleans up its disposable resources. All four passed on 2026-09-07. A separate restore of an existing scheduled operator-memory archive recovered 93 entities, 75 facts and 40 mentions, including a historical fact. This is a dated recovery check, not a complete host-loss rehearsal or an RPO/RTO guarantee. See Backup and restore for scope and evidence.

Manual restore commands:

docker compose exec -T -e PGPASSWORD="$POSTGRES_PASSWORD" postgres \
  pg_restore -U "${POSTGRES_USER:-aura}" -d "${POSTGRES_DB:-aura}" \
  --clean --if-exists --no-owner --no-acl /backups/postgres-YYYYMMDDTHHMMSSZ.dump

Take a fresh backup before restoring over a live database.

WhatsApp MCP

The whatsapp service is part of the default stack, mounted through Aura's MCP catalog. It uses an unofficial whatsmeow-based client, so it carries WhatsApp Terms of Service and account-ban risk. First pairing is headless:

docker compose logs -f whatsapp

Scan the QR code shown in the logs. Aura boot never depends on this service.

Retired Host Setup

The host needs no Python MCP runtime at all: memory is served by Aura's own ArcadeDB MCP, a Go binary in the image. Old host-level Python installs and the earlier WSL WhatsApp MCP install can be removed after migrating to the Compose appliance.

CLI

aura serve                    run the long-lived agent runtime (channels, cockpit, scheduler)
aura shell | chat <sub>       interactive REPL / chat conversations against the agent loop
aura doctor | config <sub>    environment diagnostics / effective configuration
aura agent dry-run            drive a mock LoopAgent through the Budget tree
aura tools                    print the tool manifest
aura task <sub>               operator parity with the model-facing `task` tool:
                              schedule | list | cancel | run_now | approve | runs | doctor
aura mcp <sub>                managed MCP servers: install | add | list | doctor | tools | enable | disable | remove
aura memory <sub>             ArcadeDB memory administration
aura identity <sub>           identities, capability grants, operator break-glass recovery
aura gateway grants <sub>     AG-UI gateway approval grants
aura paused-states <sub>      HITL pauses
aura skills <sub> | pack <sub> skill lifecycle · packs: list | show | install | trust
aura retention <plan|apply>   retention sweep
aura db <sub>                 Postgres lifecycle: migrate | ping | status | reset
aura objectstore <sub>        Garage object-store administration
aura web <doctor|tool ...>    web tools (search/fetch) from the CLI
aura docs <sub>               document ingestion
aura version                  build metadata

Development

For source builds, install Go from go.mod, Docker, and a POSIX shell. Linux is the supported source-build and quality-gate runtime. On Windows, use WSL; the native Windows Go binary is not a release target because Windows ACLs are not represented by POSIX FileMode bits. Docker Desktop remains supported for running the shipped Linux Compose appliance.

git clone https://github.com/chetto1983/Aura.git
cd Aura
cp .env.example .env
make tools
lefthook install
make db-migrate memory-up
go run ./cmd/aura version
go run ./cmd/aura agent dry-run --request-id auto

To run a local source build instead of a published image, build the image and point .env at it (the image builds web/ in its own stage; the committed internal/webui/dist only feeds a host go build and is refreshed from that stage, never from a host vite build):

docker build -f docker/aura/Dockerfile -t aura:local .
# then in .env:  AURA_IMAGE=aura:local

Quality gates:

make quality
make db-migrate memory-up
make quality-full

Project Layout

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/                    architecture, capabilities, release and backup guides
.planning/               GSD planning artifacts

Scope

Aura is PRD-first. Persistence is Postgres plus an ArcadeDB graph, with graph access through MCP for model-facing tools. The default packaged deployment keeps Aura socketless: no Docker socket is mounted into the Aura container. The opt-in sandbox profile reaches Docker only through a socket proxy that allows the box lifecycle verbs.

Contributing And Security

See CONTRIBUTING.md. Report vulnerabilities privately per SECURITY.md, never in a public issue.

License

MIT Copyright 2026 Davide Marchetto.