https://github.com/fusionaize/faigate

Local OpenAI-compatible AI gateway for OpenClaw and other AI-native clients.
https://github.com/fusionaize/faigate

fastapi foundrygate llm-gateway llm-router multi-provider openai-compatible openclaw self-hosted

Last synced: about 1 month ago
JSON representation

Local OpenAI-compatible AI gateway for OpenClaw and other AI-native clients.

Host: GitHub
URL: https://github.com/fusionaize/faigate
Owner: fusionAIze
License: apache-2.0
Created: 2026-02-27T22:16:07.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-04-02T15:20:53.000Z (2 months ago)
Last Synced: 2026-04-03T00:39:26.748Z (2 months ago)
Topics: fastapi, foundrygate, llm-gateway, llm-router, multi-provider, openai-compatible, openclaw, self-hosted
Language: Python
Homepage: https://fusionaize.com
Size: 2.3 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 10
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md

Awesome Lists containing this project

README

# fusionAIze Gate

[![CI](https://github.com/fusionAIze/faigate/actions/workflows/ci.yml/badge.svg)](https://github.com/fusionAIze/faigate/actions/workflows/ci.yml)
[![CodeQL](https://github.com/fusionAIze/faigate/actions/workflows/codeql.yml/badge.svg)](https://github.com/fusionAIze/faigate/actions/workflows/codeql.yml)
[![Release](https://img.shields.io/github/v/release/fusionAIze/faigate?display_name=tag)](https://github.com/fusionAIze/faigate/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
[![OpenAI-compatible](https://img.shields.io/badge/OpenAI-compatible-0ea5e9.svg)](./docs/API.md)
[![OpenClaw-friendly](https://img.shields.io/badge/OpenClaw-friendly-111827.svg)](https://openclaw.ai/)
[![Workstations](https://img.shields.io/badge/workstations-linux%20%7C%20macOS%20%7C%20windows-0f766e.svg)](./docs/WORKSTATIONS.md)
[![Homebrew](https://img.shields.io/badge/homebrew-formula-fbbf24?logo=homebrew&logoColor=black)](https://github.com/fusionAIze/homebrew-tap)
[![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)](./Dockerfile)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](./pyproject.toml)

Local OpenAI-compatible AI gateway for 🦞 [OpenClaw](https://openclaw.ai/) and other AI-native clients.

fusionAIze Gate gives OpenClaw, n8n, CLI tools, and custom apps one local endpoint and routes each request to the best configured provider or local worker. It keeps routing, fallback, onboarding, and operator visibility under your control instead of scattering provider logic across every client.

Runs locally on Linux, macOS, and Windows, with first-class workstation guidance for `systemd`, `launchd`, Task Scheduler, and Homebrew-driven macOS installs.

## Quick Navigation

- [Quickstart](#quickstart)
- [Why fusionAIze Gate](#why-fusionaize-gate)
- [How It Works](#how-it-works)
- [Anthropic Bridge](#anthropic-bridge-optional)
- [API Surface](#api-surface)
- [How fusionAIze Gate Compares](#how-fusionaize-gate-compares)
- [Deployment](#deployment)
- [More Resources](#more-resources)
- [Community And Security](#community-and-security)

## Why fusionAIze Gate

- Single local endpoint for many upstreams: cloud providers, proxy providers, and local workers can sit behind the same base URL.
- OpenAI-compatible runtime: chat completions, model discovery, image generation, and image editing use familiar OpenAI-style paths.
- Better routing than simple first-match proxying: policies, static rules, heuristics, client profiles, hooks, and route-fit scoring all participate.
- Strong operator visibility: `/health`, provider inventory, route previews, traces, stats, update checks, and dashboard views are built in, including per-client usage highlights.
- Practical rollout controls: fallback chains, maintenance windows, rollout rings, provider scopes, and post-update verification gates are already there.
- Copy/paste onboarding: OpenClaw, n8n, CLI, delegated-agent traffic, provider templates, and env starter files ship with the repo.
- Shell parity & intelligence: CLI deep‑links, suggestions, and safe config workflows keep dashboard and shell views synchronized (v2.0.0+).
- Curated provider-catalog checks catch stale model choices, volatile free-tier picks, and source-confidence gaps before local configs quietly age out.
- Provider discovery can stay transparent: catalog entries can expose official or operator-configured signup links, while recommendation ranking stays performance-led and link-neutral.
- The onboarding report and doctor CLI can surface those links with disclosure, so operators can share a signup path without turning discovery into biased ranking.

## Quickstart

The fastest local path is the helper-driven bootstrap.

Platform quick starts:

- Linux or generic source checkout: use the helper/bootstrap flow below, then `systemd` if you want a long-running service.
- macOS workstation: use the helper flow below or jump to [Homebrew](./docs/WORKSTATIONS.md#homebrew-on-macos) for `brew services`.
- Windows workstation: use the source checkout flow below, then the PowerShell and Task Scheduler examples in [docs/WORKSTATIONS.md](./docs/WORKSTATIONS.md).

```bash
git clone https://github.com/fusionAIze/faigate.git faigate
cd faigate
cp .env.example .env
./scripts/faigate-bootstrap
$EDITOR .env
./scripts/faigate-doctor
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m faigate
```

In another terminal:

```bash
curl -fsS http://127.0.0.1:8090/health
curl -fsS http://127.0.0.1:8090/v1/models
```

Then use the onboarding helpers to move from “the server starts” to “real clients are ready”:

```bash
./scripts/faigate-provider-catalog --refresh
./scripts/faigate-doctor --refresh-catalog
./scripts/faigate-provider-probe --refresh-catalog
```

`faigate-provider-catalog` mirrors selected official provider sources into the
local Gate DB so operators can compare global model/pricing snapshots against
local key and route readiness. The same summary now shows up in Dashboard and
Quick Setup, and Gate can re-check due sources on a conservative background
interval.

Gate v1.16+ extends the metadata system with additional catalogs for **offerings**
(model-provider-price mappings) and **packages** (provider credit packages, quotas,
and subscriptions). These enable cost-aware routing decisions and operator alerts
for expiring credits. Catalogs are loaded from the external `fusionaize-metadata`
repository and cached locally.

```bash
./scripts/faigate-menu
./scripts/faigate-config-wizard --help
./scripts/faigate-config-wizard --purpose general --client generic > config.yaml
./scripts/faigate-onboarding-report
./scripts/faigate-provider-discovery
./scripts/faigate-provider-discovery --json --offer-track free
./scripts/faigate-onboarding-validate
```

`./scripts/faigate-menu` now also gives you one Gate-native shell entrypoint for `Quick Setup`, the performance `Dashboard`, provider setup, API keys, HTTP settings, routing modes, client quickstarts, client-scoped wizard flows, validation helpers, service control, and update checks.

The main menu now starts with compact summary cards for gateway, config, providers, and clients so the current local state is readable before you drill into any helper. Once live traffic exists, the new `Dashboard` view gives you the first operator-facing view of requests, success rate, latency, spend, token volume, provider hotspots, client hotspots, and actionable alerts.

The `Client Scenarios` layer now also explains each template in more human terms:

- `budget` posture
- `best when` guidance
- `tradeoff` to expect

That keeps the choice closer to real operator intent such as “opencode but cheaper” or “n8n but more reliable” instead of only exposing raw routing-mode names.

Inside `Configure`, the control center now follows a clearer split:

- `Current Config` for a concise Gate snapshot
- `Guided Setup` for full or client-scoped wizard flows
- `Direct Settings` for API keys, bind settings, and routing defaults

`Quick Setup` is now the fastest happy path for first use:

- Provider Setup
- Provider Probe
- API Keys
- Full Config Wizard
- Validate
- Client Scenarios
- Restart + Verify
- Client Quickstarts

`Provider Setup` is the new source-onboarding layer in that flow:

- `Known Providers` lets you add curated providers from the catalog and optionally capture keys or upstream overrides right there
- `Custom Provider` adds an OpenAI-compatible upstream that is not in the curated list yet
- `Local Worker` adds a local or LAN worker with `contract: local-worker` so the rest of Gate can route against it like any other source

Right after that, `Provider Probe` gives one compact readiness view over:

- config present vs missing
- key/env coverage
- current `/health` state when the gateway is already running
- common failure classes such as missing key, unhealthy, rate-limited, quota-exhausted, or model-unavailable

`Client Scenarios` then turns the next decision into named templates such as:

- `opencode / eco`
- `opencode / balanced`
- `opencode / quality`
- `opencode / free`

The main menu and the service/config submenus now also show compact runtime snapshots plus short inline tips, so the shell UX stays orienting even before you drill into a helper.

If you want the client quickstarts or the current profile matrix without stepping through the full menu, use:

```bash
./scripts/faigate-client-integrations
./scripts/faigate-client-integrations --recommended
./scripts/faigate-client-integrations --matrix
./scripts/faigate-client-integrations --json --client openclaw
./scripts/faigate-client-integrations --client opencode
./scripts/faigate-config-overview
./scripts/faigate-config-overview --json
```

For service operations, the control-center flow now matches the standalone helpers more closely:

```bash
./scripts/faigate-status
./scripts/faigate-logs --lines 80
./scripts/faigate-logs --follow
./scripts/faigate-restart --timeout 15
```

To review and selectively adopt multiple candidates during first setup or a later update:

```bash
./scripts/faigate-config-wizard --purpose free --client n8n --list-candidates
./scripts/faigate-config-wizard --current-config config.yaml --purpose free --client n8n
./scripts/faigate-config-wizard --purpose free --client n8n \
--select kilocode,blackbox-free,gemini-flash-lite > config.yaml
./scripts/faigate-config-wizard --current-config config.yaml --merge-existing \
--select openrouter-fallback,anthropic-claude --write config.yaml
./scripts/faigate-config-wizard --current-config config.yaml --purpose free --client n8n \
--apply recommended_add,recommended_replace,recommended_mode_changes \
--select kilocode,openrouter-fallback --select-profiles n8n --write config.yaml
./scripts/faigate-config-wizard --current-config config.yaml --purpose free --client n8n \
--apply recommended_add,recommended_replace,recommended_mode_changes \
--select kilocode,openrouter-fallback --select-profiles n8n --dry-run-summary
./scripts/faigate-config-wizard --current-config config.yaml --purpose free --client n8n \
--apply recommended_add,recommended_replace,recommended_mode_changes \
--select kilocode,openrouter-fallback --select-profiles n8n \
--write config.yaml --write-backup --backup-suffix .before-wizard
```

If you prefer a packaged or service-driven install, jump to [Deployment](#deployment) or the fuller [Operations guide](./docs/OPERATIONS.md).

Minimal Homebrew flow on macOS:

```bash
brew tap fusionAIze/homebrew-tap https://github.com/fusionAIze/homebrew-tap
brew install fusionAIze/homebrew-tap/faigate
# or, after the tap is present:
brew install faigate
brew services start fusionAIze/homebrew-tap/faigate
```

If you already have an active Python virtualenv, check which binary you are calling before testing the Brew install:

```bash
which -a faigate
/opt/homebrew/bin/faigate --version
/opt/homebrew/bin/faigate-menu --help
```

## How It Works

```text
fusionAIze Gate

+----------------------------------------------------------------------+
| Stable session continuity |
| |
| Keep one local endpoint across Claude-native, OpenAI-native, and |
| automation-driven workflows. When Anthropic quota, one provider |
| account, or one route path is exhausted, Gate can continue through |
| another healthy direct route, aggregator route, or local worker |
| without retooling clients. Hooks, health checks, readiness, and |
| fallback stay in one gateway core. |
+----------------------------------------------------------------------+
```

Routing is layered on purpose:

1. Policies can enforce locality, capability, cost, or compliance preferences.
2. Static and heuristic rules catch known patterns without needing a classifier call.
3. Request hooks can inject bounded routing hints before the final decision.
4. Routing modes expose stable virtual model ids like `auto`, `eco`, `premium`, or custom names.
5. Client profiles can choose their own default routing mode before the final scoring step.
6. Provider scoring considers health, latency, context headroom, token limits, cache hints, and recent failures.

For OpenClaw specifically, both one-agent and many-agent traffic can use the same endpoint. fusionAIze Gate can distinguish delegated traffic through request headers such as `x-openclaw-source` when they are present.

## Anthropic Bridge (Optional)

fusionAIze Gate can also expose a small Anthropic-/Claude-compatible bridge surface for clients that speak `POST /v1/messages` instead of OpenAI chat completions.

The bridge stays intentionally narrow:

- it validates and normalizes Anthropic-style requests
- it maps them into Gate's internal canonical request model
- the existing Gate core still owns hooks, policies, routing, health checks, and fallback
- responses are mapped back into Anthropic-compatible message envelopes

That makes the bridge useful when a Claude-oriented client should keep one stable local endpoint while Gate decides whether the request should stay on a direct Anthropic route, move to an Anthropic-capable aggregator, or step sideways to a similar coding-capable route or local worker.

Operationally, this helps in two common cases:

- Anthropic subscription or account limits are exhausted, but you still want the session to continue through another route with similar coding or context characteristics.
- Anthropic-capable aggregator routes such as Kilo or BLACKBOX are available, but you want Gate health checks and fallback rules to decide whether they are actually usable.

Do not assume every aggregator route escapes Anthropic limits. Some routes may still rely on a BYOK Anthropic key from the same account. Keep those paths probeable, degradeable, and out of the top fallback position if they share the same exhausted quota domain.

The same pattern also helps when the best fallback is not Anthropic at all. Gate can route the same Claude-oriented session toward a coding-capable OpenAI-, Gemini-, DeepSeek-, or local-worker lane when that is the healthiest path with acceptable context and tool fit.

Minimal bridge config:

```yaml
api_surfaces:
anthropic_messages: true

anthropic_bridge:
enabled: true
allow_claude_code_hints: true
model_aliases:
claude-code: auto
claude-code-fast: eco
claude-code-premium: premium
```

Known v1 limits:

- non-streaming only
- text blocks plus basic `tool_use` / `tool_result`
- `count_tokens` is a local estimate, not provider-exact accounting
- the optional `claude-code-router` hook only adds routing hints; it is not the protocol bridge

Local smoke test:

```bash
./docs/examples/anthropic-bridge-smoke.sh
```

Client-near validation before release:

```bash
./docs/examples/anthropic-bridge-validation.sh
```

For a fuller operator view, see [docs/anthropic-bridge.md](./docs/anthropic-bridge.md) and [docs/API.md](./docs/API.md).

Local Claude Code testing, where the client supports Anthropic gateway overrides, follows the same pattern Anthropic documents for LLM gateways:

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:8090
export ANTHROPIC_AUTH_TOKEN=dummy-local-token
```

Keep the model alias stable and let Gate move the real route behind it. If your local Gate does not enforce auth, the token can be a harmless placeholder. If your setup does enforce client auth, use the token expected by that layer instead.

## API Surface

fusionAIze Gate keeps the primary surface compact and OpenAI-compatible. The full endpoint reference lives in [docs/API.md](./docs/API.md).

| Endpoint | Purpose |
| --- | --- |
| `GET /health` | Service health, provider status, and capability coverage |
| `GET /v1/models` | OpenAI-compatible model list |
| `POST /v1/chat/completions` | OpenAI-compatible chat routing |
| `POST /v1/messages` | Optional Anthropic-/Claude-compatible bridge route |
| `POST /v1/messages/count_tokens` | Optional Anthropic-compatible token estimate |
| `POST /v1/images/generations` | OpenAI-compatible image generation |
| `POST /v1/images/edits` | OpenAI-compatible image editing |
| `POST /api/route` | Chat routing dry-run with decision details |
| `POST /api/route/image` | Image routing dry-run |
| `GET /api/providers` | Provider inventory and filterable coverage view |
| `GET /api/update` | Update status, guardrails, and rollout advice |

Quick checks:

```bash
curl -fsS http://127.0.0.1:8090/health
curl -fsS http://127.0.0.1:8090/v1/models
curl -fsS http://127.0.0.1:8090/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Summarize why a local AI gateway is useful."}
]
}'
```

## How fusionAIze Gate Compares

The useful comparison is not “router vs router”, but how much routing and operator burden each approach leaves with you.

| Capability | Direct provider wiring | Hosted remote router | fusionAIze Gate |
| --- | --- | --- | --- |
| One local endpoint for many clients | No | Varies | Yes |
| Local workers and cloud providers in one route set | Manual | Varies | Yes |
| Policy routing, client profiles, and hooks | Manual | Varies | Yes |
| Operator-owned health, traces, and update controls | Partial | Varies | Yes |
| Can stay fully under local operator control | Yes | Varies | Yes |
| Copy/paste onboarding for OpenClaw, n8n, and CLI tools | Manual | Varies | Yes |

fusionAIze Gate is a local-first gateway. That means you can keep traffic, fallback policy, rollout controls, and provider selection logic close to the clients that actually depend on them.

## Deployment

fusionAIze Gate can stay small in development and still scale into a more repeatable operator setup:

- Local Python run: quickest path for development and testing.
- `systemd` on Linux: recommended for long-running generic host installs.
- Workstation runtimes: macOS `launchd`, Linux `systemd`, and Windows task-scheduler style installs are documented separately.
- Homebrew path: the project-owned tap formula now lives in [`fusionAIze/homebrew-tap`](https://github.com/fusionAIze/homebrew-tap) for macOS-oriented installs and `brew services`.
- Docker and GHCR path: tagged releases build container artifacts through the release workflow.
- Python package path: release workflows build `sdist` and `wheel`.
- Separate npm CLI package: `packages/faigate-cli` gives CLI-facing environments a small Node entry point without changing the Python service runtime.

Start here for the deeper deployment details:

- [Configuration reference](./docs/CONFIGURATION.md)
- [Operations guide](./docs/OPERATIONS.md)
- [Workstations guide](./docs/WORKSTATIONS.md)
- [Publishing and release flow](./docs/PUBLISHING.md)

## More Resources

- [Architecture](./docs/ARCHITECTURE.md)
- [AI-native client matrix](./docs/AI-NATIVE-MATRIX.md)
- [API reference](./docs/API.md)
- [Configuration reference](./docs/CONFIGURATION.md)
- [Operations guide](./docs/OPERATIONS.md)
- [Workstations guide](./docs/WORKSTATIONS.md)
- [Homebrew tap](https://github.com/fusionAIze/homebrew-tap)
- [Homebrew formula directory](https://github.com/fusionAIze/homebrew-tap/tree/main/Formula)
- [Integrations](./docs/INTEGRATIONS.md)
- [Onboarding](./docs/ONBOARDING.md)
- [Examples](./docs/examples)
- [macOS LaunchAgent example](./docs/examples/com.fusionaize.faigate.plist)
- [OpenClaw integration starter](./openclaw-integration.jsonc)
- [Full OpenClaw example](./docs/examples/openclaw-faigate-full.jsonc)
- [Multi-provider stack example](./docs/examples/faigate-multi-provider-stack.yaml)
- [First-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#first-wave-template-set-for-v110)
- [Second-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#second-wave-template-set)
- [Third-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#third-wave-template-set)
- [Security review for `v1.0.0`](./docs/SECURITY-REVIEW-v1.0.0.md)
- [Publishing](./docs/PUBLISHING.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)
- [Adaptive model orchestration](./docs/ADAPTIVE-ORCHESTRATION.md)
- [Dashboard IA](./docs/DASHBOARD-IA.md)
- [Roadmap](./docs/FAIGATE-ROADMAP.md)
- [Implementation plan](./docs/IMPLEMENTATION-PLAN.md)
- [Claude Desktop feasibility](./docs/CLAUDE-DESKTOP-FEASIBILITY.md)
- [Releases](./RELEASES.md)

## Community And Security

- [Contributing](./CONTRIBUTING.md)
- [Security policy](./SECURITY.md)
- [Code of conduct](./CODE_OF_CONDUCT.md)
- [Repo safety and CI](./.github/workflows)

fusionAIze Gate ships with repo-safety checks for `.ssh/`, `*.db*`, `*.sqlite*`, and `*.log`, plus CodeQL, Dependabot, secret scanning, and documented release review steps.

## License

Apache-2.0. See [LICENSE](./LICENSE).

⭐ If fusionAIze Gate saves you time or money, feel free to star the repo. ❤️

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/fusionaize/faigate

Awesome Lists containing this project

README