Code intelligence as infrastructure

Introduction

The vexp SDK is a self-hosted, machine-to-machine code-intelligence engine. It indexes hundreds of repositories into a live dependency graph and serves two things over a simple REST API: the exact context a model needs for a task, and the cross-repo blast-radius of a change. You bring the agent, bot, or pipeline; vexp gives it grounding.

It is delivered as a gateway you run on your own infrastructure plus thin clients for Python and TypeScript. There is no SaaS, no account, and no egress: indexing, serving, and license validation all happen inside your network. The engine is the same one behind the vexp VS Code extension and CLI, exposed for automation rather than a single developer.

Architecture

A deployment is one gateway fronting one or more index shards. Your repositories are distributed across shards; the gateway routes each call to the shards that own the relevant repos and merges the result into a single response. Memory tracks the active working set rather than the total repo count, so the footprint stays flat as the fleet grows: you add a worker to scale, not a bigger box.

Deploy the gateway

Run the public gateway image on a host inside your network. Give it a workspace directory (/srv/vexp below) that holds your repo checkouts plus a .vexp/ folder with workspace.json (the repos it serves, see Multi-repo workspaces) and your license.jwt.

Without a license the gateway runs as a trial: one repository and 20 lookups a day. The free Dev license from vexp.dev/sdk/dev raises that to 5 repositories and 30 lookups a day.

First, index the repos once (and again after large changes). The gateway serves the index, it does not build it on startup:

Then start the gateway. VEXP_HOME tells it where to read the license; --bearer sets the request-auth token:

Confirm it is serving and that every shard is reachable:

Authentication

Every request except GET /health is authenticated with a bearer token, sent in the Authorization header. The token is the one you set with --bearer at deploy time. A missing or wrong token returns 401.

The token is distinct from your license. The license.jwt mounted in the gateway is an offline-validated entitlement that sets your capacity tier and limits; it is never sent over the wire and nothing calls home. Webhooks can be additionally verified with an HMAC secret (see Indexing & freshness).

Tool API

The primary ingress is a single endpoint: POST /v1/tools/{tool}. You pass the tool name in the path and its parameters as a JSON body; the gateway fans the call out to the right shards and returns one merged result.

Example request

Example response

Retrieval tools return a list of pivots — the ranked code locations for the task — alongside an optional compressed output.

Python client

The Python client is dependency-free (standard library only), so it runs anywhere, including air-gapped CI.

VexpClient(base_url, token=None, timeout=60.0) also exposes health(), context_capsule(query, **kw), index_status(), and a generic call(tool, **params). Non-2xx responses raise VexpError.

TypeScript client

The TypeScript client uses the built-in fetch with a timeout and ships typed results.

new VexpClient(baseUrl, { token, timeoutMs }) also exposes health(), contextCapsule(query, params?), indexStatus(), and a generic call<T>(tool, params?). Errors throw VexpError; results are typed via PipelineResult and Pivot.

Indexing & freshness

Repos are indexed once with the bulk-index step above, then kept fresh incrementally. There are two ways to drive updates:

1. On demand

Call index_incremental from your deploy or CI step to re-index changed files. Pass mode: "full" to rebuild a repo from scratch, or a files list to scope the update.

2. From your VCS webhook

Point your provider's push / PR webhook at POST /webhook/{provider} and the gateway re-indexes the changed files automatically. Set VEXP_WEBHOOK_SECRET to verify the payload signature (GitHub uses X-Hub-Signature-256).

Multi-repo workspaces

A workspace config lists the repositories the gateway serves. Each repo gets an alias you use to scope calls (the repos parameter). The gateway distributes repos across shards for you.

Omit repos on a call to query the whole workspace, or pass a subset to scope it. Cross-repo links let blast-radius cross service boundaries, so a change in shared-lib surfaces its impact in payments-gateway and web.

Ops endpoints

Beyond the tool API, the gateway exposes standard operational endpoints for health checks, readiness gating, and metrics scraping.

Security & isolation

The SDK is built to run where your code already lives, with nothing leaving your perimeter.

Plans & limits

Capacity is shaped by repositories, not seats, and enforced from the offline license. Start free to evaluate, then size a plan against your fleet.

The Dev license is free: get it at vexp.dev/sdk/dev with your email, and come back with the same email for a new one when its 30 days are up. An expired license puts the gateway back on the trial, and /health reports the plan it serves under (unlicensed on the trial). On the trial and on Dev, only lookups count toward the daily limit (run_pipeline, get_context_capsule, get_skeleton), once per request however many shards it reaches; status, indexing and webhooks are never counted. Metered responses carry x-vexp-daily-limit and x-vexp-daily-remaining. Past the limit those tools answer 429 with Retry-After until 00:00 UTC, and everything else keeps working.

The gateway runs under SDK licenses only. A consumer license (Free, Pro, Team or an AppSumo tier) covers a person's interactive use in the editor and agent CLIs, so the gateway does not apply it and runs as the trial.