ToolRelay

ToolRelay is a Hono backend for a paid multi-provider API relay for AI agents. It implements the V1 capability-first surface:

• One bearer API key for all agent calls.
• Hosted capabilities through GET /v1/capabilities.
• Upstream provider discovery through GET /v1/providers.
• Capability execution through POST /v1/relay.
• Compatibility execution through POST /v1/capabilities/execute.
• Credits, usage ledger, top-up order, and idempotent payment webhook flow.
• OpenAPI documentation at /openapi.json and Scalar docs at /docs.

Run Locally

Backend API (Hono)

pnpm install
pnpm dev

Listens on http://localhost:3000 by default. OpenAPI at /openapi.json, Scalar docs at /docs.

The server loads .env automatically. To use another port, set PORT in .env, prefix the command, or pass --port:

PORT=3300 pnpm dev
pnpm dev --port 3300

Frontend (Next.js, optional)

The web dashboard lives under toolrelay-web/. It is a stripped-down Next.js app derived from a third-party template; the backend was removed and auth/data calls are wired to the Hono API above.

cd toolrelay-web
pnpm install
pnpm dev

Listens on http://localhost:3001.

For OAuth login, configure the Hono API process:

BETTER_AUTH_URL=http://localhost:3000
TOOLRELAY_WEB_URL=http://localhost:3001
BETTER_AUTH_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

OAuth callbacks are served by Hono:

• http://localhost:3000/api/auth/callback/google
• http://localhost:3000/api/auth/callback/github

Verify

pnpm check

This runs TypeScript build and the Vitest integration suite.

For production package verification:

pnpm build:package
pnpm start

pnpm start runs the built Hono API from dist/src/server.js.

CLI

npx -y toolrelay login -k tr_live_xxx
npx -y toolrelay install codex
npx -y toolrelay capabilities
npx -y toolrelay run web.read --url https://example.com

The npm package exposes the toolrelay binary after build. It reads TOOLRELAY_API_KEY and TOOLRELAY_BASE_URL first, then falls back to ~/.config/toolrelay/credentials.json. The default hosted API URL is https://api.toolrelay.dev; for local development, set TOOLRELAY_BASE_URL or run toolrelay login -k tr_live_xxx --base-url http://localhost:3000.

Agent skill install commands:

toolrelay install codex   # writes ~/.codex/skills/toolrelay/SKILL.md
toolrelay install claude  # writes ~/.claude/skills/toolrelay/SKILL.md

Core API

Account and billing:

• POST /v1/keys
• GET /v1/account
• GET /v1/usage
• POST /v1/billing/checkout
• POST /v1/billing/webhooks/mock

ToolRelay capability relay:

• GET /v1/capabilities
• GET /v1/providers
• POST /v1/relay
• POST /v1/capabilities/execute

System:

• GET /health
• GET /v1/discovery
• GET /openapi.json
• GET /docs

Deploy

Deployment notes and Docker Compose smoke-run instructions are in docs/deploy.md.

The API uses PostgreSQL when DATABASE_URL is set. In production (NODE_ENV=production), missing DATABASE_URL, public service URLs, or BETTER_AUTH_SECRET fails startup instead of falling back to in-memory state. For local in-memory testing, run without DATABASE_URL or point DOTENV_CONFIG_PATH at an empty env file.