Running a binary needs a config — see the quickstart guide and Configuration. To try AURA with no setup, use the Quick Start below.

Quick Start

cp .env.example .env                                                  # set your LLM provider, model, and API key
docker compose up -d                                                  # starts Aura (orchestrator mode) + LibreChat + Phoenix
docker compose exec -it aura ./aura --api-url http://localhost:8080   # chat with the orchestrator from your terminal

Aura boots in orchestrator mode: a coordinator routes each request — answering simple ones directly and decomposing complex ones across specialized workers. The bundled aura connects to the in-container server automatically and renders the coordinator's plan and worker activity as it streams.

Prefer a browser? Open http://localhost:3080 to chat in LibreChat, or http://localhost:6006 to inspect traces in Phoenix.

Full quickstart guide — provider setup (OpenAI, Anthropic, Ollama, llama-server), adding MCP tools, enabling vector search, serving multiple agents, and troubleshooting.

More Quickstarts

• Orchestration — Math MCP — Multi-agent orchestration with coordinator/worker architecture
• Kubernetes SRE — AI-powered SRE agent on KIND with Kubernetes and Prometheus MCP servers
• Example Configs — Minimal per-provider configs and complete agent compositions

Usage

Web API Server

Run the web server (to build and run from source, see DEVELOPMENT.md):

# Default: reads config.toml
cargo run --bin aura-web-server

# Custom config file
CONFIG_PATH=my-config.toml cargo run --bin aura-web-server

# Config directory (serves multiple agents)
CONFIG_PATH=configs/ cargo run --bin aura-web-server

# Host/port override
HOST=0.0.0.0 PORT=3000 cargo run --bin aura-web-server

# Enable Aura custom SSE events
AURA_CUSTOM_EVENTS=true cargo run --bin aura-web-server

# Kitchen sink: all options
CONFIG_PATH=configs/ \
  HOST=0.0.0.0 PORT=8080 \
  AURA_CUSTOM_EVENTS=true \
  AURA_EMIT_REASONING=true \
  TOOL_RESULT_MODE=aura \
  OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
  cargo run --bin aura-web-server -- --verbose

Core server options:

Tool result modes:

• none: spec-compliant; tool results appear only in model summary.
• open-web-ui: tool results emitted through tool_calls for OpenWebUI compatibility.
• aura: tool results emitted via aura.tool_complete events.

API examples:

# Health
curl http://localhost:8080/health

# List available models (agents)
curl http://localhost:8080/v1/models

# OpenAI-compatible chat completion
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

# Select a specific agent by name or alias via the model field
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "my-agent", "messages": [{"role": "user", "content": "Hello"}]}'

# Streaming response
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}], "stream": true}'

SSE protocol details, event types, custom events, and client handling are documented in docs/streaming-api-guide.md.

A2A Protocol

Disabled by default. A2A endpoints are only activated when the server is started with --enable-a2a (or AURA_ENABLE_A2A=true). Omitting the flag means no A2A routes are registered and the agent card is not served.

Aura exposes A2A protocol endpoints for agent-to-agent interoperability. This allows other A2A-compatible agents and clients to discover and interact with Aura agents using a standardized protocol.

# Agent card (capability discovery)
curl http://localhost:8080/.well-known/agent-card.json

# Send a message via REST
curl -X POST http://localhost:8080/a2a/v1/message:send \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{"message": {"messageId": "msg-001", "role": "ROLE_USER", "parts": [{"text": "Hello"}]}}'

# Send a message via JSON-RPC
curl -X POST http://localhost:8080/a2a/v1/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "SendMessage", "params": {"message": {"messageId": "msg-002", "role": "ROLE_USER", "parts": [{"text": "Hello"}]}}, "id": 1}'

Set AURA_SERVER_URL when running behind a proxy, load balancer, or in Kubernetes. The agent card must advertise absolute endpoint URLs, and A2A clients use those URLs directly — a relative or wrong-host URL makes message:send fail even though the card itself loads. Aura builds the card's URLs from AURA_SERVER_URL (or --server-url); set it to the externally-reachable origin clients use (e.g. https://aura.example.com). When unset, it falls back to the bind host/port, which is only correct for direct local access.

A2A endpoints, transport modes, the agent card URL, task lifecycle, and testing examples are documented in docs/a2a-implementation.md.

Client-Side Tools

---

USE AT YOUR OWN RISK

---

Setting enable_client_tools = true on an agent grants the LLM the ability to call tools that execute on the client's machine. When clients (e.g. aura) advertise tools like Shell, Read, or Update, the LLM can invoke them and the client will execute them with the privileges of the user running the client. This is functionally equivalent to giving the model a shell prompt on every connecting client.

The risks are real:

• Prompt injection. Anything the model reads — a file, an MCP tool output, a vector-store hit, a URL — can contain instructions that hijack the model into running destructive commands. The server cannot tell a legitimate request from an injected one.
• Hallucination. The model can confidently call the wrong tool with the wrong arguments. There is no undo for a Shell("rm -rf ...") invocation.
• No server-side sandbox. The server only forwards tool calls; execution happens client-side with full host privileges. Whatever sandboxing exists is the client's responsibility.
• Per-agent permission filters reduce blast radius but are not a security boundary. client_tool_filter controls which tools the model can ask for, not what they do once invoked.

Only enable on agents where:

• You trust the model, the provider, and every data source the model can read (configs, MCP servers, vector stores, web fetches).
• You trust every client that will connect with --enable-client-tools and the user account it runs under.
• You and your users accept that worst-case loss (deleted files, leaked credentials, modified source) is acceptable or recoverable.

Disabled by default. Opting a