ares-server 0.10.0

A.R.E.S (Agentic Runtime Extensible Server) is a composable AI agent runtime in Rust, built on the Cordis framework. Features include multi-provider LLM routing, structured tool calling, RAG, MCP integration, multi-tenant auth, and workflow orchestration. You embed the library facade of the ares-server package (Context, Execute, Tools, Llm). The ares-server binary serves the Axum HTTP layer.

Built by DIRMACS. Documentation

Features

Multi-provider LLM: Ollama, OpenAI, Anthropic Claude, LlamaCpp (direct GGUF loading)
TOML configuration: declarative, hot-reloading
Configurable agents: defined via TOON with custom models, tools, and prompts
Workflow engine: declarative execution with agent routing
Tool calling: type-safe function calling with automatic schema generation
ToolCoordinator: provider-agnostic multi-turn tool calling for all LLM clients
Per-agent tool filtering: each agent sees only its allowed tools
Streaming: real-time responses from all providers
Auth: JWT with Argon2 password hashing
Database: PostgreSQL with multi-tenant isolation, optional vector stores (ares-vector, Qdrant, LanceDB)
MCP: pluggable Model Context Protocol server integration
Multi-agent orchestration: specialized agent routing
RAG: pure-Rust vector store, multi-strategy search (semantic, BM25, fuzzy, hybrid), reranking
Memory: user personalization and context management
Deep research: multi-step research with parallel subagents
Web search: built-in via daedra
OpenAPI: automatic documentation generation
Configuration validation: circular reference detection and warnings for unused items
Loop detection: 3-tier escalation (warn, force alternative, halt) for repetitive outputs
Crash recovery: checkpoint serialization, save agent state at each step, restore on restart
Service-based architecture: services register with ctx.plugin() or ctx.provide(). Handlers pull dependencies with ctx.get::<T>() on a typed Context. Fiber::refresh recomputes the dependency epoch and reruns plugin apply.
Unified execution: single Execute handles resolve, create, and execute for chat, v1 API, JWT chat, MCP, scheduler, pipeline, and trigger. Scheduler, pipeline, and trigger domain loops remain native ARES engines behind Execute.
Event-first skills: Context::inject waits on the ReflectService TypeId notifier (ensure_notifier + changed). A 5ms poll runs only when the notifier is unavailable. Skills carry the request Context, isolate tools with ctx.isolate::<Tools>(tenant_id), and call Tools::execute on that tenant isolate. Skill LlmCall steps strictly use Llm::complete through llm.complete, with no direct provider generate_with_history fallback. Tools, Llm, Execute, and skills stay event-first on EventsService waterfalls.
Quota: agent.admit (Dispatch::Bail) is the shared gate for Execute, JWT chat, API-key middleware, and MCP.
Store / Overlay / realms: Store factory runs migrations and seeds templates. Overlay fills empty loader configurations from ares.toml. TOON changes notify Tools and Execute. TenantRealms open-then-intercept on request paths and dispose on tenant delete.
Hot-reload: a file watch triggers automatic service refresh without restart. When the epoch changes, Fiber::refresh reruns plugin apply.
Circuit breaker: LLM provider health tracked per-endpoint with automatic failover

Installation

You can run ARES as a standalone server. You can also use it as a library in your Rust project.

As a library

Add this dependency to your project:

[dependencies]
ares-server = "0.9"

Basic usage:

use ares_server::{Context, Execute, Tools, Llm};

The default features of ares-server are postgres, openai, ares-vector, mcp, inventory, and rhai-policy. Embed-only builds pass --no-default-features --features openai,postgres,mcp to Cargo. ProviderRegistry remains on the constructor path for AgentRegistry / Llm until those take Llm only.

As a binary

# Install from crates.io
cargo install ares-server --version 0.10.0

# Install with embedded Web UI
cargo install ares-server --version 0.10.0 --features ui

# Initialize a new project (creates ares.toml and config files)
ares-server init

# Run the server
ares-server

CLI commands

The CLI gives full-featured commands with colored output:

# Initialize a new project with all configuration files
ares-server init

# Initialize with custom options
ares-server init --provider openai --port 8080 --host 0.0.0.0

# Initialize with minimal configuration
ares-server init --minimal

# View configuration summary
ares-server config

# Validate configuration
ares-server config --validate

# List all configured agents
ares-server agent list

# Show details for a specific agent
ares-server agent show orchestrator

# Start the server
ares-server

# Start with verbose logging
ares-server --verbose

# Use a custom config file
ares-server --config custom.toml

# Disable colored output
ares-server --no-color init

Init command options

Option	Description
`--force, -f`	Overwrite existing files
`--minimal, -m`	Create minimal configuration
`--no-examples`	Skip creating TOON example files
`--provider <NAME>`	LLM provider: `ollama`, `openai`, or `both`
`--host <ADDR>`	Server host address (default: 127.0.0.1)
`--port <PORT>`	Server port (default: 3000)

Quick start (development)

Prerequisites

Rust 1.98 or later. Install via rustup
Ollama for local LLM inference (recommended). See Install Ollama
just as the command runner (recommended). See Install just

1. Clone and setup

git clone https://github.com/dirmacs/ares.git
cd ares
cp .env.example .env

# Or use just to set up everything:
just setup

2. Start Ollama (recommended)

# Install a model
ollama pull ministral-3:3b
# Or: just ollama-pull

# Ollama runs automatically as a service, or start manually:
ollama serve

3. Build and run

# Build with default features (local-db + ollama)
cargo build
# Or: just build

# Run the server
cargo run
# Or: just run

The server runs on http://localhost:3000

Feature flags

ARES uses Cargo features for conditional compilation:

LLM providers

Feature	Description	Default
`ollama`	Ollama local inference	Yes
`openai`	OpenAI API (and compatible)	No
`anthropic`	Anthropic Claude API	No
`llamacpp`	Direct GGUF model loading	No
`llamacpp-cuda`	LlamaCpp with CUDA	No
`llamacpp-metal`	LlamaCpp with Metal (macOS)	No
`llamacpp-vulkan`	LlamaCpp with Vulkan	No

Database & vector stores

Feature	Description	Default
`postgres`	PostgreSQL database	Yes
`ares-vector`	Pure-Rust embedded HNSW vector store	Yes
`qdrant`	Qdrant vector database	No
`pgvector`	PostgreSQL pgvector extension	No
`chromadb`	ChromaDB embedding database	No
`pinecone`	Pinecone managed vector database	No
`lancedb`	LanceDB vector database	No

UI & documentation

Feature	Description	Default
`ui`	Embedded Leptos web UI served from backend	No
`swagger-ui`	Interactive API documentation at `/swagger-ui/`	No

Note: v0.2.5 made swagger-ui optional. This change reduces the binary size and the build time. The feature needs network access during the build to download the Swagger UI assets.

Embeddings

Feature	Description	Default
`local-embeddings`	Local ONNX embedding models via fastembed	No

Warning: The local-embeddings feature does not work on Windows MSVC. Cause: ort-sys linker errors. Use WSL, Linux, macOS, or remote embedding APIs instead.

Feature bundles

Feature	Includes
`all-llm`	ollama + openai + llamacpp + anthropic
`all-db`	postgres + all vector stores
`full`	All optional features (except UI and local-embeddings): ollama, openai, llamacpp, anthropic, postgres, qdrant, ares-vector, mcp, swagger-ui
`full-ui`	All optional features + UI (except local-embeddings)
`full-local-embeddings`	Full + local-embeddings (Linux/macOS only)
`full-ui-local-embeddings`	Full + UI + local-embeddings (Linux/macOS only)
`minimal`	No optional features

Note: The full and full-ui bundles exclude local-embeddings because of Windows MSVC compatibility issues. On Linux and macOS use full-local-embeddings or full-ui-local-embeddings.

Building with features

# Default (ollama + local-db)
cargo build
# Or: just build

# With OpenAI support
cargo build --features "openai"
# Or: just build-features "openai"

# With direct GGUF loading
cargo build --features "llamacpp"

# With CUDA GPU acceleration
cargo build --features "llamacpp-cuda"

# Full feature set
cargo build --features "full"
# Or: just build-all

# With embedded Web UI
cargo build --features "ui"

# With Swagger UI (interactive API docs)
cargo build --features "swagger-ui"

# Full feature set with UI
cargo build --features "full-ui"

# Release build
cargo build --release
# Or: just build-release

Configuration

ARES reads a TOML configuration file (ares.toml) with declarative configuration for all components. The server requires this file at startup.

Quick start

# Copy the example config
cp ares.example.toml ares.toml

# Set required environment variables
export JWT_SECRET="your-secret-key-at-least-32-characters"
export API_KEY="your-api-key"

Configuration file (ares.toml)

The configuration file defines providers, models, agents, tools, and workflows:

# Server settings
[server]
host = "127.0.0.1"
port = 3000
log_level = "info"

# Authentication (secrets loaded from env vars)
[auth]
jwt_secret_env = "JWT_SECRET"
api_key_env = "API_KEY"

# Database
[database]
url = "./data/ares.db"

# LLM Providers (define named providers)
[providers.ollama-local]
type = "ollama"
base_url = "http://localhost:11434"
default_model = "ministral-3:3b"

[providers.openai]  # Optional
type = "openai"
api_key_env = "OPENAI_API_KEY"
default_model = "gpt-4"

# Models (reference providers, set parameters)
[models.fast]
provider = "ollama-local"
model = "ministral-3:3b"
temperature = 0.7
max_tokens = 256

[models.balanced]
provider = "ollama-local"
model = "ministral-3:3b"
temperature = 0.7
max_tokens = 512

[models.smart]
provider = "ollama-local"
model = "qwen3-vl:2b"
temperature = 0.3
max_tokens = 1024

# Tools (define available tools)
[tools.calculator]
enabled = true
timeout_secs = 10

[tools.web_search]
enabled = true
timeout_secs = 30

# Agents (reference models and tools)
[agents.router]
model = "fast"
system_prompt = "You route requests to specialized agents..."

[agents.product]
model = "balanced"
tools = ["calculator"]                     # Tool filtering: only calculator
system_prompt = "You are a Product Agent..."

[agents.research]
model = "smart"
tools = ["web_search", "calculator"]       # Multiple tools
system_prompt = "You conduct research..."

# Workflows (define agent routing)
[workflows.default]
entry_agent = "router"
fallback_agent = "product"
max_depth = 5

[workflows.research_flow]
entry_agent = "research"
max_depth = 10

Per-agent tool filtering

Each agent can specify which tools it has access to:

[agents.restricted]
model = "balanced"
tools = ["calculator"]  # Only calculator, no web search

[agents.full_access]
model = "balanced"
tools = ["calculator", "web_search"]  # Both tools

If tools is empty or omitted, the agent has no tool access.

Configuration validation

The server validates the configuration on load:

Reference checks: Models must reference valid providers, and agents must reference valid models
Circular reference detection: Workflows cannot have circular agent references
Environment variables: All referenced environment variables must be set

The validate_with_warnings() method reports unused configuration items (providers, models, and tools with no references).

Hot reloading

The server detects configuration changes automatically and applies them without restart. Edit ares.toml. The loader picks up the changes within 500ms.

Environment variables

These environment variables must be set because ares.toml references them:

# Required
JWT_SECRET=your-secret-key-at-least-32-characters
API_KEY=your-api-key

# Optional (for OpenAI provider)
OPENAI_API_KEY=sk-...

Provider priority

When multiple providers are configured, they are selected in this order:

LlamaCpp when LLAMACPP_MODEL_PATH is set
OpenAI when OPENAI_API_KEY is set
Ollama as the default fallback (no API key required)

Dynamic configuration (TOON)

ARES also supports TOON (Token Oriented Object Notation) files for behavioral configuration with hot-reload support. These files complement ares.toml.

config/
 agents/
    router.toon
    orchestrator.toon
    product.toon
 models/
    fast.toon
    balanced.toon
 tools/
    calculator.toon
 workflows/
    default.toon
 mcps/
     filesystem.toon

Example TOON agent config (config/agents/router.toon):

name: router
model: fast
max_tool_iterations: 5
parallel_tools: false
tools[0]:
system_prompt: |
  You are a router agent that directs requests to specialized agents.

Enable TOON configuration in ares.toml:

[config]
agents_dir = "config/agents"
models_dir = "config/models"
tools_dir = "config/tools"
workflows_dir = "config/workflows"
mcps_dir = "config/mcps"
hot_reload = true

The server hot-reloads TOON files automatically after a change.

User-created agents API

Users can create custom agents in the database. Import and export use the TOON format:

# Create a custom agent
curl -X POST http://localhost:3000/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "model": "balanced",
    "system_prompt": "You are a helpful assistant.",
    "tools": ["calculator"]
  }'

# Export as TOON
curl http://localhost:3000/api/agents/{id}/export \
  -H "Authorization: Bearer $TOKEN"

# Import from TOON
curl -X POST http://localhost:3000/api/agents/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  -d 'name: imported-agent
model: fast
system_prompt: |
  You are an imported agent.'

Extending ARES

ARES works as a library. The ares_server lib injects Execute, Tools, and Llm on a Cordis Context. An agent runs with no HTTP service on the graph. The Axum routes live in the ares-http package.

Library (no axum)

use ares_server::{Context, Execute, Tools, Llm, register_plugins};
use cordis::PluginRegistry;

let ctx = Context::new_root();
let reg = PluginRegistry::new();
register_plugins(&reg);
// provide in-memory or real Execute + Tools + Llm, then Execute::run(&req, &ctx)

Custom routes (feature `http`)

use std::sync::Arc;
use cordis::Context;
use ares_http::Http;

let ctx: Arc<Context> = /* your configured context with Http provided */;
// Http::apply builds the Axum router; the ares-server binary binds it.

Custom context provider

The trait now lives in ares-agent (ares_agent::context_provider::ContextProvider). It injects external context into agent calls before LLM invocation. This is one focused hook, not the general extension mechanism; for broader extension, write a plugin or a loader entry (see ARCHITECTURE.md).

use ares::agents::context_provider::ContextProvider;
use async_trait::async_trait;

struct MyContextProvider { /* your state */ }

#[async_trait]
impl ContextProvider for MyContextProvider {
    async fn get_context(&self, agent_name: &str, tenant_id: &str) -> Option<String> {
        Some("Relevant context for this agent...".to_string())
    }
}

By default ARES uses NoOpContextProvider, which returns None.

Architecture

Composition is a Cordis Context plus loader entries. Components register into a typed Context. Handlers and engines pull Execute, Tools, Llm, and Store at call time. The ares_server lib has no axum on its graph. The kernel follows the hardening rules of the Cordis model. Guarded withdrawal protects providers against removal under active consumers. Verified hot-swap and drain-and-shift replacement give zero-downtime rebuilds through POST /admin/cordis/services/{name}/replace. Peer-dependency versioning uses provide_versioned/declare_inject_versioned. Incompatible versions leave dependents Inactive instead of a silent bind. Inject reconciliation runs eagerly. Cycle detection at load reports rings through GET /admin/cordis/entries. A metatheory property suite proves quiescence, confluence, LIFO, and reactive invariants. RhaiPolicy scripting ships default-on. TOML entries attach sandboxed script gates to capability events with fail-closed semantics. The 0.10 kernel adds: intercept meta-events (internal/get|set|config|update|listener) that veto or rewrite kernel operations; readiness barriers that rest fibers in inspectable Pending until watched providers settle; name-keyed computed properties (register_accessor) and layered intercept chains; identity-preserving entry moves with rename cascades through POST /admin/cordis/entries/{id}/move; a module graph that reloads each affected plugin exactly once per debounced batch; an in-kernel logger, fiber-scoped timers, and wired per-subtask cancellation. docs/cordis-mapping.md documents the full Cordis surface (§10–§19).

request / job
  -> TenantRealms.open then intercept (HTTP/MCP/JWT) or isolate only (background)
  -> agent.admit (Execute, JWT chat, API-key middleware, MCP)
  -> Execute::run
  -> Tools / Llm / skills via EventsService waterfalls
  -> response

Fiber, events, and capabilities

Fiber::refresh recomputes the dependency epoch. It reruns plugin apply when the epoch changed or when the fiber is not already Active with satisfied dependencies. Dispose still undoes effects in LIFO order.

EventsService dispatch modes: Emit returns JSON null. Parallel joins every handler and returns JSON null on success. Handler values are discarded, and the first join or handler error propagates. Serial (same path as Bail) stops at the first non-null handler result. Waterfall is around-middleware with next.

Tools, Llm, Execute, and skills remain event-first. Public methods run through waterfall_around when EventsService is on ctx.

agent.admit is the shared quota gate for Execute::run, JWT /api/chat, API-key middleware, and MCP. Deny maps to HTTP 429 or an MCP tool error.

Store, Overlay, realms, boot

The Store loader factory connects, runs SQL migrations, and seeds default agent templates. Overlay copies ares.toml sections into loader entries only when entry.config is empty. TOON reloads call ReflectService::notify for Tools and Execute.

TenantRealms open-then-intercept on request paths. Background jobs open/isolate only. Admin tenant delete calls dispose then SQL delete.

run_server composes the entries program at boot (@include splice, @group flatten, ${rhai: …} configuration interpolation — fail-open). It re-composes on every watched reload and applies the diff through the loader journal. Verified hot-swap handles same-provider rebuilds, and guarded withdrawal handles retire. Inventory-collected factories are the primary registration path (manual chains are the no-default-features fallback). Scheduler, pipeline, and trigger domain loops remain native ARES engines behind Execute. They emit boundary events on the typed catalog.

Key services

Service	What it does
`Execute`	Single entry point for agent runs. Chat, v1, JWT, MCP, scheduler, pipeline, and trigger delegate here after `agent.admit`.
`Resolver`	Crate-private three-tier agent resolution: tenant DB, community, system configuration.
`Llm`	Provider clients with a circuit breaker. `ProviderRegistry` remains a constructor input.
`Tools`	Merges static tools, runtime DB tools, and MCP tools. Tenant isolation via `isolate::<Tools>`.
`Store`	Postgres client with migrations, template seed, and tenant DB.
`EventsService`	Typed event bus. Product paths stay event-first.
`Overlay`	`ares.toml` overlay. Fills empty loader configurations. TOON notifies Tools/Execute.
`TenantRealms`	Per-tenant child contexts. Open-then-intercept on request paths. Dispose runs on tenant delete.
`ReflectService`	Hot-reload coordination. File changes propagate without restart.

Adding a service

// Register in a plugin apply / loader factory
root_ctx.provide(Execute::new()
    .with_agent_registry(registry)
    .with_run_tracker(active_runs));

// Use from a handler or engine (HTTP types require feature `http`)
async fn my_handler(State(ctx): State<Arc<Context>>) -> Result<Response> {
    let exec = ctx.get::<Execute>().expect("not provided");
    let result = exec.run(&req, &ctx).await?;
    Ok(Json(result.response).into_response())
}

See ARCHITECTURE.md for full details.

API documentation

The interactive Swagger UI is available at http://localhost:3000/swagger-ui/

Note: The build must enable the swagger-ui feature:

cargo build --features "swagger-ui"
# Or use the full bundle:
cargo build --features "full"

Authentication

Register

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password",
    "name": "John Doe"
  }'

Login

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password"
  }'

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900
}

Chat

curl -X POST http://localhost:3000/api/chat \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do we have?",
    "agent_type": "product"
  }'

Deep research

curl -X POST http://localhost:3000/api/research \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze market trends in renewable energy",
    "depth": 3,
    "max_iterations": 5
  }'

Workflows

Workflows give multi-agent orchestration. Define workflows in ares.toml:

[workflows.default]
entry_agent = "router"           # Starting agent
fallback_agent = "orchestrator"  # Used if routing fails
max_depth = 5                    # Maximum agent chain depth
max_iterations = 10              # Maximum total iterations

List available workflows

curl http://localhost:3000/api/workflows \
  -H "Authorization: Bearer <access_token>"

Response:

["default", "research"]

Execute a workflow

curl -X POST http://localhost:3000/api/workflows/default \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are our Q4 product sales figures?"
  }'

Response:

{
  "final_response": "Based on the Q4 data, our product sales were...",
  "steps_executed": 3,
  "agents_used": ["router", "sales", "product"],
  "reasoning_path": [
    {
      "agent_name": "router",
      "input": "What are our Q4 product sales figures?",
      "output": "sales",
      "timestamp": 1702500000,
      "duration_ms": 150
    },
    {
      "agent_name": "sales",
      "input": "What are our Q4 product sales figures?",
      "output": "For Q4 sales data, I'll need to check...",
      "timestamp": 1702500001,
      "duration_ms": 800
    },
    {
      "agent_name": "product",
      "input": "What are our Q4 product sales figures?",
      "output": "Based on the Q4 data, our product sales were...",
      "timestamp": 1702500002,
      "duration_ms": 650
    }
  ]
}

Workflow with Context

curl -X POST http://localhost:3000/api/workflows/default \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the sales figures?",
    "context": {
      "department": "electronics",
      "quarter": "Q4"
    }
  }'

Admin & deployment API

Admin endpoints require the X-Admin-Secret header.

Trigger deploy

curl -X POST http://localhost:3000/api/admin/deploy \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"target": "ares"}'

Response:

{"id": "deploy-abc123", "status": "running", "message": "Deploy started"}

Check deploy status

curl http://localhost:3000/api/admin/deploy/deploy-abc123 \
  -H "X-Admin-Secret: $ADMIN_SECRET"

List recent deploys

curl http://localhost:3000/api/admin/deploys \
  -H "X-Admin-Secret: $ADMIN_SECRET"

Service health

curl http://localhost:3000/api/admin/services \
  -H "X-Admin-Secret: $ADMIN_SECRET"

Response:

{
  "ares": {"status": "active", "pid": "12345", "port": 3000},
  "postgresql": {"status": "active", "pid": "456", "port": 5432}
}

Service logs

curl http://localhost:3000/api/admin/services/ares/logs \
  -H "X-Admin-Secret: $ADMIN_SECRET"

RAG (retrieval augmented generation)

ARES includes a complete RAG system with a pure-Rust vector store. It requires the ares-vector feature. For local files use the generic Rust CLI, and pass every deployment-specific path or collection explicitly:

ares-server rag ingest-dir \
  --host http://localhost:3000 \
  --token "$ARES_TOKEN" \
  --collection docs \
  --docs-path ./docs \
  --chunking-strategy word \
  --tag documentation


ares-server rag search \
  --host http://localhost:3000 \
  --token "$ARES_TOKEN" \
  --collection docs \
  --query "What is the architecture?" \
  --top-k 5

Ingest documents

curl -X POST http://localhost:3000/api/rag/ingest \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "docs",
    "content": "Your document content here...",
    "title": "Manual note",
    "source": "manual",
    "tags": ["technical"],
    "chunking_strategy": "word"
  }'

Search documents

curl -X POST http://localhost:3000/api/rag/search \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "docs",
    "query": "What is the architecture?",
    "strategy": "hybrid",
    "limit": 5,
    "rerank": true
  }'

Search strategies:

semantic: Vector similarity search
bm25: Traditional keyword matching
fuzzy: Typo-tolerant search
hybrid: Weighted combination of semantic + BM25

List collections

curl http://localhost:3000/api/rag/collections \
  -H "Authorization: Bearer <access_token>"

Tool calling

ARES supports tool calling with all LLM providers that support function calling (OpenAI, Anthropic, and Ollama with ministral-3:3b or later):

Built-in tools

calculator: Basic arithmetic operations
web_search: Web search via DuckDuckGo (no API key required)

Unified ToolCoordinator

The ToolCoordinator handles multi-turn tool calling with any LLMClient in a provider-agnostic way:

use ares::llm::{Provider, ToolCoordinator, ToolCallingConfig};
use ares::tools::ToolRegistry;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create an LLM client (works with any provider)
    let provider = Provider::from_env()?;
    let client = provider.create_client().await?;

    // Set up tool registry with built-in tools
    let registry = Arc::new(ToolRegistry::new());

    // Create the unified coordinator
    let coordinator = ToolCoordinator::new(
        client,
        registry,
        ToolCallingConfig::default(),
    );

    // Execute a tool-calling conversation
    let result = coordinator.execute(
        Some("You are a helpful assistant with access to tools."),
        "What is 25 * 4?"
    ).await?;

    println!("Response: {}", result.content);
    println!("Tool calls made: {}", result.tool_calls.len());
    println!("Iterations: {}", result.iterations);

    Ok(())
}

Toolcallingconfig options

Option	Default	Description
`max_iterations`	10	Maximum LLM round-trips before stopping
`parallel_execution`	true	Runs multiple tool calls in parallel
`tool_timeout`	30s	Timeout for individual tool execution
`include_tool_results`	true	Include tool results in final context
`stop_on_error`	false	Stop on first tool error vs continue

Testing

ARES has complete test coverage with mocked tests and live tests.

Unit & integration tests (mocked)

# Run all tests (no external services required)
cargo test
# Or: just test

# Run with verbose output
cargo test -- --nocapture
# Or: just test-verbose

Live Ollama tests

Tests that connect to a real Ollama instance exist, and the default run ignores them.

Prerequisites

An Ollama server runs at http://localhost:11434
A model is installed. Example: ollama pull ministral-3:3b

Running live tests

# Set the environment variable and run ignored tests
OLLAMA_LIVE_TESTS=1 cargo test --test ollama_live_tests -- --ignored
# Or: just test-ignored

# All tests (normal + ignored)
just test-all

# With verbose output
just test-all-verbose

# With custom Ollama URL or model
OLLAMA_URL=http://192.168.1.100:11434 OLLAMA_MODEL=mistral OLLAMA_LIVE_TESTS=1 \
  cargo test --test ollama_live_tests -- --ignored

Alternatively, add OLLAMA_LIVE_TESTS=1 to your .env file.

API tests (hurl)

End-to-end API tests use Hurl:

# Install Hurl
brew install hurl  # macOS

# Run API tests (server must be running)
just hurl

# Run with verbose output
just hurl-verbose

# Run specific test group
just hurl-health
just hurl-auth
just hurl-chat

See CONTRIBUTING.md for more details on testing.

Common commands (just)

ARES uses just as the command runner. Run just --list to see all available commands:

# Show all commands
just --list

# Build & Run
just build          # Build (debug)
just build-release  # Build (release)
just build-ui       # Build with embedded UI
just run            # Run server
just run-ui         # Run with embedded UI
just run-debug      # Run with debug logging

# CLI Commands
just init           # Initialize project (ares-server init)
just init-openai    # Initialize with OpenAI provider
just config         # Show configuration summary
just agents         # List all agents
just agent <name>   # Show agent details

# Testing
just test           # Run tests
just test-verbose   # Run tests with output
just test-ignored   # Run live Ollama tests
just test-all       # Run all tests
just hurl           # Run API tests

# Code Quality
just lint           # Run clippy
just fmt            # Format code
just quality        # Run all quality checks

# Docker
just docker-up      # Start dev services
just docker-down    # Stop services
just docker-logs    # View logs

# UI Development
just ui-setup       # Install UI dependencies
just ui-dev         # Run UI dev server
just ui-build       # Build UI for production
just dev            # Run backend + UI together

# Ollama
just ollama-pull    # Pull default model
just ollama-status  # Check if running

# Info
just info           # Show project info
just status         # Show environment status

Troubleshooting

Configuration file not found

# Error: Configuration file 'ares.toml' not found!

# Solution: Initialize a new project
ares-server init

Port already in use

# Error: Address already in use (os error 48)

# Find the process using port 3000
lsof -i :3000          # Linux/macOS
netstat -ano | findstr :3000  # Windows

# Kill the process
kill -9 <PID>          # Linux/macOS
taskkill /PID <PID> /F # Windows

Ollama connection failed

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

# Or start via Docker
just docker-services

Missing environment variables

# Error: MissingEnvVar("JWT_SECRET")

# Solution: Set up environment variables
cp .env.example .env
# Edit .env and set JWT_SECRET (min 32 characters) and API_KEY

UI build errors (node.js runtime required)

# Error: npx: command not found

# Solution: Install a Node.js runtime
# Option 1: Install Bun (recommended)
curl -fsSL https://bun.sh/install | bash

# Option 2: Install Node.js
brew install node  # macOS
# or download from https://nodejs.org

WASM build errors

# Error: target `wasm32-unknown-unknown` not found

# Solution: Add the WASM target
rustup target add wasm32-unknown-unknown

# Install trunk
cargo install trunk --locked

Requirements

Minimum requirements

Rust: 1.98 or later
Operating System: Linux, macOS, or Windows
Memory: 2GB RAM (4GB or more for larger models)

Optional requirements

Ollama: for local LLM inference (recommended)
Node.js runtime: Bun, npm, or Deno (required for UI development)
Docker: For containerized deployment
GPU: NVIDIA (CUDA) or Apple Silicon (Metal) for accelerated inference

Security considerations

JWT_SECRET: must have at least 32 characters. Generate it with openssl rand -base64 32
API_KEY: unique per deployment
Environment variables: never commit .env files to version control
HTTPS: use HTTPS in production (configure through a reverse proxy)
Rate limiting: production deployments need rate limiting at the proxy layer

Contributing

We welcome contributions. See CONTRIBUTING.md for the guidelines.

Quick contribution guide

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/ares.git
cd ares

# 2. Create a feature branch
git checkout -b feature/my-feature

# 3. Make your changes and run tests
cargo fmt
cargo clippy
cargo test

# 4. Commit and push
git commit -m "feat: add my feature"
git push origin feature/my-feature

# 5. Open a Pull Request

Development setup

# Install development dependencies
just setup

# Run pre-commit checks before pushing
just pre-commit

Changelog

See CHANGELOG.md for a list of changes in each version.

Acknowledgments

Ollama - Local LLM inference
llama.cpp - GGUF model support
Axum - Web framework
Leptos - Reactive web UI framework
TOON Format - Token-optimized configuration format

Ecosystem

Project	What
pawan	Self-healing CLI coding agent (29 tools, streaming TUI)
daedra	Web search MCP server (7 backends, automatic fallback)
thulp	Execution context engineering (11 crates, tool abstraction)
lancor	llama.cpp toolkit (API client, HF Hub, server orchestration)
eruka	Context intelligence engine (knowledge graph, memory tiers)

License

MIT

ares-server 0.10.0

Features

Installation

As a library

As a binary

CLI commands

Init command options

Quick start (development)

Prerequisites

1. Clone and setup

2. Start Ollama (recommended)

3. Build and run

Feature flags

LLM providers

Database & vector stores

UI & documentation

Embeddings

Feature bundles

Building with features

Configuration

Quick start

Configuration file (ares.toml)

Per-agent tool filtering

Configuration validation

Hot reloading

Environment variables

Provider priority

Dynamic configuration (TOON)

User-created agents API

Extending ARES

Library (no axum)

Custom routes (feature http)

Custom context provider

Architecture

Fiber, events, and capabilities

Store, Overlay, realms, boot

Key services

Adding a service

API documentation

Authentication

Register

Login

Chat

Deep research

Workflows

List available workflows

Execute a workflow

Workflow with Context

Admin & deployment API

Trigger deploy

Check deploy status

List recent deploys

Service health

Service logs

RAG (retrieval augmented generation)

Ingest documents

Search documents

List collections

Tool calling

Built-in tools

Unified ToolCoordinator

Toolcallingconfig options

Testing

Unit & integration tests (mocked)

Live Ollama tests

Prerequisites

Running live tests

API tests (hurl)

Common commands (just)

Troubleshooting

Configuration file not found

Port already in use

Ollama connection failed

Missing environment variables

UI build errors (node.js runtime required)

WASM build errors

Requirements

Minimum requirements

Optional requirements

Security considerations

Custom routes (feature `http`)