Quickstart

From zero to your first open-data charging-site search in five minutes.

1. Prerequisites

• Node.js 22 or newer
• npm (the repo uses npm workspaces)
• No API keys, no accounts, no cloud bindings for this guide

2. Install and verify

git clone <your-voltbase-mirror> voltbase
cd voltbase
npm ci
npm run verify   # typecheck, lint, build, test, smoke -> VERIFY OK stage=8

3. Run the Worker locally

npm run dev
# GET /healthz answers {"ok":true,"stage":8}

4. First search (open data only)

curl 'http://localhost:8787/api/v1/sites?connector=CCS2&minPower=50&limit=5&offset=0'

The response carries data, page info (limit, offset, total) and per-partition attribution. Try a known open row next:

curl 'http://localhost:8787/api/v1/sites/OCM%3A900000'
curl 'http://localhost:8787/api/v1/status/OCM%3A900000'

IDs use a source prefix (OCM:, OSM:); the colon must be URL-encoded as %3A. Unknown or closed ids answer typed NOT_FOUND — never a closed signal.

5. Try the CLI

node packages/cli/bin/voltbase.js --help
node packages/cli/bin/voltbase.js search --connector CCS2 --limit 5

Next steps

• API reference — every route, filter and error code
• MCP onboarding — the same tools for agents over stdio and HTTP
• Providers / BYOK — when you need your own OCM key