Spend Brake

Hard dollar caps, enforced in real time, for every paid API your apps, test suites and AI agents call. Spend Brake is a self-hosted egress proxy: swap one base URL and one key, and every request is priced before it leaves, checked against your caps in one atomic step, and refused with a clear 402 once a cap would be crossed. Built in: Google Maps Platform (Places, Geocoding, Routes), Twilio Messaging and Verify, Mapbox, HERE, and the agent search APIs Tavily, Exa, Brave and SerpApi; any other API can be added as a custom API, priced per request or at the cost it reports.

You keep your provider account and your own key. The real key never leaves Spend Brake; clients only ever hold revocable virtual keys.

Documentation: docs.spendbrake.dev. Hosted service: spendbrake.dev.

5-minute quickstart

For a production install (HTTPS, published images, backups, upgrades, scaling), see Self-hosting (docs/self-hosting.md in this repo). To use the hosted service instead, see the Quickstart.

Requirements: Docker, Node 22+ (for the CLI), a Google Maps Platform key.

git clone https://github.com/KIvanow/spend-brake && cd spend-brake
cp infra/.env.example infra/.env
# fill in the secrets, e.g.:
sed -i "s|^BRAKE_MASTER_KEY=.*|BRAKE_MASTER_KEY=$(openssl rand -base64 32)|; \
        s|^BRAKE_ACTION_SECRET=.*|BRAKE_ACTION_SECRET=$(openssl rand -base64 32)|; \
        s|^BRAKE_SETUP_TOKEN=.*|BRAKE_SETUP_TOKEN=$(openssl rand -hex 24)|; \
        s|^VALKEY_PASSWORD=.*|VALKEY_PASSWORD=$(openssl rand -hex 24)|; \
        s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 24)|" infra/.env

export BRAKE_VERSION=0.4.0   # the published images to run
docker compose -f infra/docker-compose.yml -f infra/docker-compose.release.yml up -d --wait

That starts the proxy (:8080), admin API (:8081), notifier (:8082), dashboard (:3000), worker, Valkey and Postgres, listening on 127.0.0.1 only. Then set up your org, store the Google key and get a virtual key:

npm install -g @spend-brake/cli   # or run it without installing: npx @spend-brake/cli

# Secrets from the environment (or omit them to be prompted): flags would land in shell history.
export BRAKE_SETUP_TOKEN="$(grep BRAKE_SETUP_TOKEN infra/.env | cut -d= -f2)"
read -rs GOOGLE_MAPS_KEY && export GOOGLE_MAPS_KEY
brake init --api-url http://localhost:8081 --proxy-url http://localhost:8080 \
  --org acme --day-cap 5 --month-cap 50

To build the images and the CLI from source instead, leave out the release file and add --build (docker compose -f infra/docker-compose.yml up -d --build --wait), then pnpm install && pnpm --filter @spend-brake/cli build and use node apps/cli/dist/brake.cjs.

init prints the owner token once (keep it in a password manager) and saves an admin token for the CLI. Valkey and Postgres are only reachable from the other containers.

brake init prints your virtual key once, checks whether the Google key is restricted, and prints the exact Google Cloud steps (console and gcloud) to restrict the real key to the proxy's egress IPs and the Maps APIs, so the proxy is the only path to spend. Then swap the base URL and key in your app:

- https://maps.googleapis.com/maps/api/geocode/json?address=Sofia&key=AIza…
+ http://localhost:8080/google-maps/maps/api/geocode/json?address=Sofia&key=sb_live_…

- https://places.googleapis.com/v1/places:searchText     X-Goog-Api-Key: AIza…
+ http://localhost:8080/google-places/v1/places:searchText    X-Goog-Api-Key: sb_live_…

Every response carries X-Brake-Cost-Micros and X-Brake-Remaining-Micros. Past a cap:

HTTP/1.1 402 Payment Required
{"error":"budget_exceeded","message":"Spend cap reached for org. Stop and ask the user to raise the cap.",
 "scope":"org","window":"d:20261029","cap":5000000,"sp

... [View full README on GitHub](https://github.com/kivanow/spend-brake#readme)