Getting started

Front one API through Orb and read it with a key.

Orb is not packaged for install yet. The scripts in the repository were written for one machine: they call Homebrew’s Caddy and a specific launchd job. Running it yourself means assembling the pieces below and changing the paths you find.

1. Install the pieces

You need Caddy, PocketBase (0.41.x is what this was written against), Node 20 or newer for the CLI, and Python 3 for the sync script. Nothing uses npm or pip.

brew install caddy pocketbase

2. Pick one HTTP API

Start with a simple JSON API that answers on 127.0.0.1:<port>. Orb proxies loopback upstreams: the sync script rejects any upstream that is not 127.0.0.1:<port>, so a public API needs a local proxy in front of it. Check that the service’s auth fits the two modes in Adding your own API before you add it, and leave out anything that streams responses.

3. Declare it

Add an entry to services.json in the gateway checkout:

{
  "name": "weather",
  "path": "/weather",
  "upstream": "127.0.0.1:8800",
  "scopes": ["read"],
  "upstream_auth": { "mode": "strip" }
}

name is also the scope prefix, so this service answers at /weather/... to a key that carries weather:read.

4. Apply it

python3 bin/sync-services.py

The script regenerates the Caddy routes, validates and reloads Caddy, then restarts PocketBase so the new scope appears in the admin form. --check prints the generated routes and changes nothing.

Two lines assume this machine: /opt/homebrew/bin/caddy and launchctl kickstart gui/$(id -u)/com.noah.api-gateway.pocketbase. Install that launchd job from launchd/ or edit those lines. Caddy must already be running, because the script reloads it.

5. Request through it

Create a key (see Creating API keys), then:

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8480/weather/forecast"

When the response is your API’s response, Orb is working. Add more services the same way. GET /health on the gateway needs no token.