ferrogw 1.4.4 → 1.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +49 -40
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -43,51 +43,49 @@
43
43
 
44
44
  ## Quick Start
45
45
 
46
- Get from zero to first request in under 2 minutes.
46
+ Under two minutes from install to first response.
47
47
 
48
- ### Option A — Binary (fastest)
48
+ | Platform / tool | Install |
49
+ |:---|:---|
50
+ | macOS, Linux | `curl -fsSL https://get.ferrolabs.ai \| sh` |
51
+ | Windows | `irm https://get.ferrolabs.ai/install.ps1 \| iex` |
52
+ | Homebrew | `brew install ferro-labs/tap/ferrogw` |
53
+ | Scoop | `scoop bucket add ferrolabs https://github.com/ferro-labs/homebrew-tap` then `scoop install ferrogw` |
54
+ | npm | `npm install -g ferrogw` |
55
+ | Python | `uv tool install ferrogw` |
56
+ | Docker | `docker run -p 8080:8080 ghcr.io/ferro-labs/ai-gateway:latest` |
57
+ | Go | `go install github.com/ferro-labs/ai-gateway/cmd/ferrogw@latest` — builds from source, without the dashboard |
58
+ | Debian, RPM, Alpine | `.deb`, `.rpm` and `.apk` packages on the [releases page](https://github.com/ferro-labs/ai-gateway/releases/latest) |
59
+
60
+ Then go from nothing to a served request:
49
61
 
50
62
  ```bash
51
- VER=$(curl -fsSL https://api.github.com/repos/ferro-labs/ai-gateway/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
52
- curl -fsSL "https://github.com/ferro-labs/ai-gateway/releases/download/${VER}/ferrogw_${VER#v}_linux_amd64.tar.gz" | tar xz
53
- chmod +x ferrogw
54
- ./ferrogw init # generates config.yaml + MASTER_KEY
63
+ export OPENAI_API_KEY=sk-your-key # ferrogw init detects this and writes the matching target
64
+ ferrogw init # writes config.yaml, prints your master key
55
65
  export GATEWAY_CONFIG=./config.yaml # the server reads a config file only when this is set
56
- export OPENAI_API_KEY=sk-your-key # providers are registered at startup, so export before starting
57
66
  export MASTER_KEY=fgw_your-master-key # the key ferrogw init printed
58
- ./ferrogw # starts the server
67
+ ferrogw serve # starts the server on :8080
59
68
  ```
60
69
 
61
- Releases are signed and ship SBOMs — verification steps are in
62
- [SECURITY.md](SECURITY.md#verifying-releases).
63
-
64
- ### Option B — Docker
65
-
66
- ```bash
67
- docker pull ghcr.io/ferro-labs/ai-gateway:latest
68
- docker run -p 8080:8080 \
69
- -e OPENAI_API_KEY=sk-your-key \
70
- -e MASTER_KEY=fgw_your-master-key \
71
- ghcr.io/ferro-labs/ai-gateway:latest
72
- ```
70
+ `ferrogw init` prints the master key **once** and never writes it to disk — save
71
+ it yourself, in your `.env` file or a secret manager.
73
72
 
74
- ### Option C — Go
73
+ Docker runs the server itself, so there is no `ferrogw init` to print a master
74
+ key — choose your own. Pass both variables by name so their values stay off the
75
+ command line, where `ps` would show them:
75
76
 
76
77
  ```bash
77
- go install github.com/ferro-labs/ai-gateway/cmd/ferrogw@latest
78
- ferrogw init # first-run setup
79
- export GATEWAY_CONFIG=./config.yaml # the server reads a config file only when this is set
80
- export OPENAI_API_KEY=sk-your-key # providers are registered at startup, so export before starting
81
- export MASTER_KEY=fgw_your-master-key # the key ferrogw init printed
82
- ferrogw # start the server
78
+ export OPENAI_API_KEY=sk-your-key
79
+ export MASTER_KEY=fgw-any-strong-secret-you-choose
80
+ docker run -p 8080:8080 -e OPENAI_API_KEY -e MASTER_KEY ghcr.io/ferro-labs/ai-gateway:latest
83
81
  ```
84
82
 
85
- `ferrogw init` generates the master key and writes a minimal `config.yaml`. The
86
- key is shown **once** and never written to disk — store it in your `.env` file
87
- or secret manager.
83
+ Passing them by name keeps the values out of process arguments only — they are
84
+ still readable in the container's environment and through `docker inspect`, so
85
+ use Docker secrets or your platform's secret storage in production.
88
86
 
89
87
  <div align="center">
90
- <img src="docs/demo.gif" alt="Ferro Labs AI Gateway — Quick Start Demo" width="720" />
88
+ <img src="docs/demo.gif" alt="Installing Ferro Labs AI Gateway with one command, running ferrogw init, starting the server, and getting a completed chat response" width="100%" />
91
89
  </div>
92
90
 
93
91
  ### First request
@@ -96,19 +94,22 @@ or secret manager.
96
94
  export MASTER_KEY=fgw_your-master-key # the key ferrogw init printed, in whichever shell you curl from
97
95
 
98
96
  curl http://localhost:8080/v1/chat/completions \
99
- -H "Content-Type: application/json" \
100
97
  -H "Authorization: Bearer $MASTER_KEY" \
98
+ -H "Content-Type: application/json" \
101
99
  -d '{
102
100
  "model": "gpt-4o-mini",
103
101
  "messages": [{"role": "user", "content": "Hello from Ferro Labs AI Gateway"}]
104
102
  }' | jq
105
103
  ```
106
104
 
105
+ Every release is signed with keyless cosign and ships an SPDX SBOM —
106
+ verification steps are in [SECURITY.md](SECURITY.md#verifying-releases).
107
+
107
108
  ---
108
109
 
109
110
  ## Why Ferro Labs AI Gateway
110
111
 
111
- Most AI gateways are Python proxies that crack under load or JavaScript services that eat memory. Ferro Labs AI Gateway is written in Go from the ground up for real-world throughput — a single binary that routes LLM requests with predictable latency and minimal resource usage.
112
+ AI gateways differ most under load, in throughput, latency and memory. Ferro Labs AI Gateway is written in Go from the ground up for real-world throughput — a single binary that routes LLM requests with predictable latency and minimal resource usage.
112
113
 
113
114
  | Feature | Ferro Labs | LiteLLM | Bifrost | Kong AI |
114
115
  |:-----------------|:------------|:--------|:-----------|:------------|
@@ -139,12 +140,16 @@ Most AI gateways are Python proxies that crack under load or JavaScript services
139
140
 
140
141
  ## Dashboard
141
142
 
142
- Every gateway binary serves a built-in operations console at `/` — same port as
143
+ Every release binary serves a built-in operations console at `/` — same port as
143
144
  the API, compiled in with `go:embed`, no second image and no second origin. Sign
144
145
  in with your `MASTER_KEY` or any admin / read-only key and it reads the live
145
146
  gateway: traffic, spend, provider health, routing, plugins, request logs, and the
146
147
  audit trail.
147
148
 
149
+ The bundle is produced by the release pipeline, so a binary built with
150
+ `go install` is the one exception: it answers `/` with a placeholder instead.
151
+ Any other install method above ships the console.
152
+
148
153
  <div align="center">
149
154
  <img src="docs/dashboard.gif" alt="Ferro Labs AI Gateway operations console: Overview, Analytics, Providers, Routing Strategies, Plugins, Playground, Tracing, Request Logs, Audit Trail, Configuration, and API Keys" width="100%" />
150
155
  </div>
@@ -330,8 +335,8 @@ make build && ./bin/ferrogw
330
335
  ### Railway & Render
331
336
 
332
337
  The deploy buttons at the top of this README provision either platform: Railway
333
- with SQLite on a volume (set the three `*_STORE_DSN` variables to paths under
334
- `/data`) or PostgreSQL, and Render from the repo's `render.yaml` Blueprint,
338
+ with SQLite on a volume (point `API_KEY_STORE_DSN`, `CONFIG_STORE_DSN` and
339
+ `REQUEST_LOG_STORE_DSN` at paths under `/data`) or PostgreSQL, and Render from the repo's `render.yaml` Blueprint,
335
340
  which generates `MASTER_KEY` and wires the store DSNs to a managed Postgres
336
341
  automatically.
337
342
 
@@ -343,7 +348,7 @@ tag, health check, and resource limits. Run everything from the repository root:
343
348
 
344
349
  ```bash
345
350
  make up # dev: builds from source
346
- IMAGE_TAG=v1.4.0 CORS_ORIGINS=https://your-domain.com make up-prod
351
+ IMAGE_TAG=v1.4.5 CORS_ORIGINS=https://your-domain.com make up-prod
347
352
  make down # tears down either
348
353
  ```
349
354
 
@@ -367,8 +372,12 @@ Helm charts: [github.com/ferro-labs/helm-charts](https://github.com/ferro-labs/h
367
372
 
368
373
  ## Migrate to Ferro Labs AI Gateway
369
374
 
370
- The gateway is OpenAI-compatible, so migration from any gateway — or from
371
- calling a provider directly — is a `base_url` change.
375
+ The gateway is OpenAI-compatible, so for a client already using an
376
+ OpenAI-compatible SDK, migration — from another gateway or from calling a
377
+ provider directly — is a `base_url` and `api_key` change: point the SDK at the
378
+ gateway and present a gateway-issued credential in place of the provider's own.
379
+ A client with its own API, such as LiteLLM's `completion()` below, also moves to
380
+ the OpenAI SDK.
372
381
 
373
382
  ### From LiteLLM
374
383
 
@@ -418,7 +427,7 @@ with no custom headers in self-hosted mode.
418
427
  **Why migrate from Portkey:**
419
428
 
420
429
  - Fully open source — no per-request pricing, no log limits
421
- - Self-hosted — your data never leaves your infrastructure
430
+ - Self-hosted — the gateway runs in your infrastructure, and prompts reach only the providers you configure
422
431
  - No vendor lock-in — Apache 2.0 license
423
432
  - MCP support — Portkey self-hosted lacks native MCP
424
433
  - FerroCloud (coming soon) for teams that want a managed service
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ferrogw",
3
- "version": "1.4.4",
3
+ "version": "1.4.5",
4
4
  "description": "Ferro Labs AI Gateway — one OpenAI-compatible API in front of 30+ LLM providers, with routing, guardrails and key management.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Ferro Labs <hello@ferrolabs.ai>",
@@ -34,11 +34,11 @@
34
34
  "node": ">=18"
35
35
  },
36
36
  "optionalDependencies": {
37
- "@ferro-labs-ai/gateway-linux-x64": "1.4.4",
38
- "@ferro-labs-ai/gateway-linux-arm64": "1.4.4",
39
- "@ferro-labs-ai/gateway-darwin-x64": "1.4.4",
40
- "@ferro-labs-ai/gateway-darwin-arm64": "1.4.4",
41
- "@ferro-labs-ai/gateway-win32-x64": "1.4.4",
42
- "@ferro-labs-ai/gateway-win32-arm64": "1.4.4"
37
+ "@ferro-labs-ai/gateway-linux-x64": "1.4.5",
38
+ "@ferro-labs-ai/gateway-linux-arm64": "1.4.5",
39
+ "@ferro-labs-ai/gateway-darwin-x64": "1.4.5",
40
+ "@ferro-labs-ai/gateway-darwin-arm64": "1.4.5",
41
+ "@ferro-labs-ai/gateway-win32-x64": "1.4.5",
42
+ "@ferro-labs-ai/gateway-win32-arm64": "1.4.5"
43
43
  }
44
44
  }