velesdb-server

HTTP/REST server that exposes a VelesDB database — vector, text, graph and VelesQL — to any language.

Objective

velesdb-core is an embedded engine: it lives inside one Rust process. As soon as a second process — a Python service, a Node worker, an agent running on another machine — needs the same data, you need a network boundary. velesdb-server is that boundary: a single self-contained binary that wraps the engine in an Axum HTTP API, adds API keys, TLS, rate limiting, health probes and Prometheus metrics, and persists everything to a data directory (WAL + mmap) that survives restarts. No JVM, no sidecar, no external dependency.

The engine behind VelesDB — the explainable, local-first memory engine for AI agents. It fuses vector + graph + columnar under VelesQL; the why() recall trail returns the evidence path behind every answer.

Use cases

• A Python or TypeScript service needs vector search, and you do not want to embed a Rust library in every runtime you ship.
• Several agents on a LAN share one memory store, authenticated with Bearer API keys over TLS.
• A local RAG prototype needs a backend that survives a laptop reboot without setting up a database cluster.
• A Kubernetes deployment needs liveness/readiness probes, /metrics, and a clean SIGTERM that flushes the write-ahead logs.
• A knowledge graph is queried with Cypher-style MATCH and vector similarity in the same request.

Prerequisites

Installation

cargo install velesdb-server

Prebuilt archives (.tar.gz, .deb, .zip), Docker, and platform-specific notes: docs/guides/INSTALLATION.md. Container and orchestrator setup: docs/guides/SERVER_DEPLOYMENT.md.

Building from a clone of this repository:

cargo build --release -p velesdb-server

First success in 60 seconds

# 1. Start the server and wait until it reports readiness
velesdb-server --port 8080 --data-dir ./velesdb_data &
until curl -sf http://localhost:8080/v1/ready > /dev/null; do sleep 1; done

# 2. Create a 4-dimensional collection
curl -sS -X POST http://localhost:8080/v1/collections \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart", "dimension": 4, "metric": "cosine"}'
echo

# 3. Insert three points
curl -sS -X POST http://localhost:8080/v1/collections/quickstart/points \
  -H "Content-Type: application/json" \
  -d '{"points": [
        {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "payload": {"title": "first"}},
        {"id": 2, "vector": [0.9, 0.4, 0.0, 0.0], "payload": {"title": "second"}},
        {"id": 3, "vector": [0.1, 0.9, 0.0, 0.0], "payload": {"title": "third"}}
      ]}'
echo

# 4. Search for the nearest two vectors
curl -sS -X POST http://localhost:8080/v1/collections/quickstart/search \
  -H "Content-Type: application/json" \
  -d '{"vector": [1.0, 0.0, 0.0, 0.0], "top_k": 2}'
echo

Expected output — three JSON lines, in this order:

{"message":"Collection created","name":"quickstart","type":"vector","warnings":["Collection dimension and metric are immutable after creation. If your embedding model changes, create a new collection and reindex data.","For first queries, start without strict filters/thresholds, then tighten progressively."]}
{"count":3,"message":"Points upserted"}
{"results":[{"id":"1","score":1.0,"payload":{"title":"first"}},{"id":"2","score":0.91381156,"payload":{"title":"second"}}]}

The code field is optional and omitted when no structured code applies. Use it for programmatic error handling (e.g., retry on VELES-006, display user hint on VELES-004). See ERROR_CODES.md for the full list.

Operations

Everything an operator configures — API keys and their rotation, TLS, the graceful-shutdown sequence and its WAL flush guarantee, the /health and /ready probes — lives in Server security, which is the canonical reference and covers each of them in more depth than a README should.

Docker, Kubernetes manifests, rate limiting, CORS and the startup update check are in Deployment.

The short version:

Configuration priority, highest first: CLI flags > environment variables > velesdb.toml > built-in defaults. Every section of the file is optional; declare only what you override.

Distance metrics accepted by the API (cosine, euclidean, dot — aliases dotproduct, inner, ip —, hamming, jaccard) are listed with their use cases in the REST tour; measured latency figures live in the benchmarks, pinned to promise-contract.json.

Examples

• REST tour — every endpoint family with runnable curl recipes: collections, quantization, points, search modes, sparse and hybrid search, VelesQL, graph, MATCH, indexes, errors.
• Deployment — Docker, Kubernetes probes, rate limiting, CORS, update check.
• Server security — API keys, key rotation, TLS, graceful shutdown, health endpoints.
• Getting started — the wider VelesDB tour, engine included.

API / commands

Routes are served under two prefixes: /v1/… is canonical, and the unversioned /… form is kept for backward compatibility — its responses carry deprecation: true and x-api-deprecated: Use /v1/ prefix.

Known limits

• One process per data directory. The engine takes an exclusive OS-level lock on <data_dir>/velesdb.lock. There is no built-in clustering, replication, or sharding: scale vertically, or shard at the application level. See CONCURRENCY_LOCKING.md.
• Authentication is a flat list of API keys. No users, no roles, no per-collection scoping. Keys are read at startup, so rotation requires a restart (both old and new key can be active during the transition).
• Rate limiting is per process and in memory. Replicas do not share a budget; put a shared limiter in front if you need a global one.
• CORS is permissive by default (allowed_origins = ["*"]); the server warns about it at startup. Restrict [cors] before exposing a browser-facing deployment.
• Swagger UI is opt-in at build time (--features swagger-ui); the released default build does not serve /swagger-ui or /api-docs/openapi.json.
• The /v1 prefix is added by the binary. Embedding velesdb_server::routes::api_routes() in your own Axum application gives you the unversioned routes; nest them yourself if you want the versioned form.
• Engine-level limits (query length caps, GROUP BY ceilings, scan caps) are listed in docs/reference/KNOWN_LIMITATIONS.md.

Compatibility

Troubleshooting

License

VelesDB Core License 1.0 — see LICENSE.

velesdb-server v5.0.0 · Last updated: 2026-08-10 · Applies to: velesdb-core 5.0.0 · Report a docs error