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.
The SDK is REST / M2M only. The MCP interface used by the editor and CLI is deliberately not exposed here, so the SDK complements your per-seat tools rather than replacing them.
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.
| Piece | What it is | Where it runs |
|---|---|---|
gateway | REST ingress, auth, routing, metrics | Your network |
shards | Indexed repositories + graph | Your network |
clients | Python / TypeScript wrappers over REST | Your machines |
license.jwt | Offline-validated capacity entitlement | Mounted in the gateway |
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.
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.
| Tool | Purpose | Key params |
|---|---|---|
run_pipeline | Context + impact + memory in one call | task, repos?, preset?, max_tokens? |
get_context_capsule | Retrieve the relevant code for a query | query, repos? |
get_impact_graph | Cross-repo blast-radius of a symbol | symbol_fqn |
index_incremental | Re-index changed files | repo?, files?, mode |
index_status | Index health and stats | — |
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.
| Endpoint | Auth | Returns |
|---|---|---|
GET /health | No | Liveness + shard count |
GET /ready | Yes | 200 when all shards reachable, else 503 |
GET /metrics | Yes | Prometheus exposition (requests, errors, per-tool latency) |
Use /ready as your load-balancer readiness probe so traffic only reaches a gateway whose shards are all serving. Scrape /metrics into Prometheus for per-tool request, error, and latency series.
Security & isolation
The SDK is built to run where your code already lives, with nothing leaving your perimeter.
| Property | How |
|---|---|
| Self-hosted | Runs on your servers; one container or many. |
| Air-gapped ready | Indexes, serves, and validates the license fully offline. |
| No egress | Your code and queries never leave your network. |
| On-prem model | The optional AI layer runs locally; no third-party AI calls. |
| REST only | No MCP surface, so it cannot be wired into editors as a seat bypass. |
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.
| Plan | Repos | Calls | For |
|---|---|---|---|
| Dev | Up to 5 | 30 / day | Evaluation and prototyping (30-day) |
| Startup | Up to 10 | Unlimited | Small fleets in production |
| Enterprise | Hundreds+ | Unlimited | Fleet-scale, capacity license |
Sizing is by repositories under index. Talk to us with your repo count and we will size a capacity plan to fit.