Skip to content
HyperMesh

Hosted Evaluation (Strongest IP Protection)

In a hosted evaluation, you run the engine; the client runs only a thin remote client. The client can exercise every feature — queries, analytics, ingestion — but the engine, the algorithms, and the data processing never leave your infrastructure. This is the strongest IP posture: there is no engine binary and no proprietary source on the client’s machine at all.

┌──────────────────────────┐         HTTPS + API key        ┌──────────────────────────┐
│  Client machine          │  ───────────────────────────▶  │  Your infrastructure     │
│  pip install              │                                │  hmdb serve (engine+API) │
│    hypermesh-client       │  ◀───────────────────────────  │  TPI/FMI, analytics, …   │
│  (21 KB, no engine)       │            JSON results        │  data volume             │
└──────────────────────────┘                                └──────────────────────────┘

1. The thin client (what the client installs)

Section titled “1. The thin client (what the client installs)”

A dedicated, remote-only package — hypermesh-client — lives in clients/python-thin/. It contains only the HTTP client surface; it has no hypermesh_core engine, no analytics code, and no ingestion code. The public API mirrors the full SDK, so application code is portable.

Build it:

Terminal window
./tools/build_thin_client.sh                 # → dist-client/hypermesh_client-*.whl
SOURCELESS=1 ./tools/build_thin_client.sh    # additionally strip .py → .pyc

The build script copies only the engine-free modules, fails if any forbidden import (hypermesh_core, _connection, _analytics, numpy, …) sneaks in, and verifies the wheel contains no .so/.dylib.

The client installs and uses it exactly like the full SDK:

import hypermesh as hm


db = hm.connect("https://hypermesh.yourco.com", api_key="hmdb_...")
res = db.execute("MATCH HYPEREDGE (he:CoProximity) RETURN *")
print(res.num_tuples)


db.insert(event_ts=200, members=[9, 10], weight=0.5)
db.compact()
print(db.analytics("CoProximity", "node_degree"))   # runs on the server

A filesystem path is rejected (EngineNotInstalledError) — there is no local engine to fall back to.

2. The server (what you host)

Section titled “2. The server (what you host)”

The engine + REST API ship as hmdb serve (FastAPI/uvicorn). Run it with Docker:

Terminal window
export HMDB_API_KEY="hmdb_$(openssl rand -hex 16)"     # bootstrap admin key
docker compose -f deploy/docker-compose.eval.yml up -d --build

This deployment keeps authentication on, enables rate limiting (HMDB_RATE_LIMIT_QPM), and is ready for TLS (mount certs or terminate at a proxy).

Mint a scoped, time-limited key for the client

Section titled “Mint a scoped, time-limited key for the client”
Terminal window
docker compose -f deploy/docker-compose.eval.yml exec hypermesh \
    hmdb add-key /data --role readwrite --description "ACME eval"
# → prints the plaintext key once; hand it to the client securely.

Roles: readonly < readwrite < admin. Give evaluators readonly or readwrite. Revoke when the eval ends:

Terminal window
hmdb list-keys /data
hmdb revoke-key /data <key_id>

The client authenticates via Authorization: Bearer <key> (also accepts X-API-Key). Configure via environment:

Terminal window
export HYPERMESH_URL="https://hypermesh.yourco.com"
export HYPERMESH_API_KEY="hmdb_..."

3. Security checklist for an eval tenant

Section titled “3. Security checklist for an eval tenant”
  • [] Auth on — never set HMDB_AUTH_DISABLED.
  • [] TLS — terminate at the server (--tls-cert/--tls-key) or a proxy.
  • [] Per-key rate limit — tune HMDB_RATE_LIMIT_QPM.
  • [] Least privilege — issue readonly/readwrite, not admin.
  • [] Time-bound — revoke the key at the end of the evaluation.
  • [] Network — restrict ingress (allowlist client IPs / VPC peering).
  • [] Isolate tenants — one data volume / one server per client.
  • [] Lock down unauthenticated workbench routes — some /v1/ingest/*, /v1/connectors/webhook/*, HyperDx, and workspace routes lack a role dependency; put the server behind an authenticating proxy or restrict the network if you don’t need those endpoints for the eval.

4. What the client can and cannot do

Section titled “4. What the client can and cannot do”
CapabilityHosted eval (thin client)
Query (execute)✅ runs on server
Write / delete / compact✅ (role-gated)
Analytics measures✅ runs on server
Ingestion✅ via server endpoints
Receive the engine binary❌ never shipped
Read proprietary Python❌ not shipped
Run offline / air-gapped❌ requires connectivity to your server

If the client requires local/offline use, combine this with the bytecode-only eval package instead — that ships the engine as a compiled .so with no readable source.