Setup & Configuration

Goal: get an Ahnlich AI proxy running and connected to Ahnlich DB. The AI proxy turns your raw text, images, and audio into vectors, then hands them to the database — so it always runs alongside an Ahnlich DB server (via --db-url).

Install it the same three ways as the database:

However you install it, you finish the same way: a server running on your machine that answers PING. From there every command works the same.

First time here?

Install and start Ahnlich DB first — the AI proxy needs a database to talk to. The Docker Compose example below starts both together.

Installation

1. Download Binaries

Prebuilt binaries are available from GitHub Releases. Pick the file that matches your OS and chip (on macOS, run uname -m — arm64 = Apple Silicon, x86_64 = Intel).

Download the binary (macOS Apple Silicon shown):

$curl -L -O "https://github.com/deven96/ahnlich/releases/download/bin%2Fai%2F0.3.0/aarch64-apple-darwin-ahnlich-ai.tar.gz"

Extract the archive:

$tar -xvzf *-ahnlich-ai.tar.gz

Run the binary:

$./ahnlich-ai

On macOS, if Gatekeeper blocks the unsigned binary, clear the quarantine flag first: xattr -d com.apple.quarantine ./ahnlich-ai

2. Using Docker

Ahnlich AI also ships as a Docker image:

docker pull ghcr.io/deven96/ahnlich-ai:latest

Run with:

docker run --rm -p 1370:1370 \
  --network ahnlich-net \
  --name ahnlich-ai \
  ghcr.io/deven96/ahnlich-ai:latest \
  ahnlich-ai run --port 1370 --db-url http://ahnlich-db:1369

3. Example Docker Compose

Ahnlich AI can be orchestrated with docker-compose, typically alongside Ahnlich DB.

services:
ahnlich_ai:
  image: ghcr.io/deven96/ahnlich-ai:latest
  command: >
    "ahnlich-ai run --host 0.0.0.0
    --db-url http://ahnlich_db:1369
    --enable-tracing
    --otel-endpoint http://jaeger:4317"
  ports:
    - "1370:1370"

ahnlich_db:
  image: ghcr.io/deven96/ahnlich-db:latest
  command: >
    "ahnlich-db run --host 0.0.0.0 --enable-tracing"
  ports:
    - "1369:1369"

Optional Jaeger service for tracing

  jaeger:
    image: jaegertracing/all-in-one:${JAEGER_VERSION:-latest}
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"

Configuration Options

Ahnlich AI can be customized using runtime flags:

• --host <ip> – Specify listening host (default: 0.0.0.0).

• --port <port> – Specify server port (default: 1370).

• --enable-tracing – Enable telemetry tracing with OpenTelemetry.

• --otel-endpoint <url> – OpenTelemetry endpoint (e.g., Jaeger).

• CREATESTORE my_store QUERYMODEL all-minilm-l6-v2 INDEXMODEL all-minilm-l6-v2

Quick Start Example

Start Ahnlich AI (with a linked DB):

./ahnlich-ai run --host 0.0.0.0 --port 1370 --db-url http://localhost:1369

Create a model-aware store:

CREATESTORE my_store QUERYMODEL all-minilm-l6-v2 INDEXMODEL all-minilm-l6-v2

Insert raw input (text, image, or audio):

INSERT "The rise of renewable energy storage solutions" INTO my_store

Run a semantic query:

SEARCH "climate change effects on agriculture" IN my_store