Send a request. Pick a route.
Different clients enter through Ferry. Each request goes to an eligible upstream.
English
OPEN SOURCE · SELF-HOSTED · AI GATEWAY
Less time retrying.
More time for your AI.
Connect your clients to the accounts you already have. Ferry handles routing, waiting and recoverable failures.
Go + SQLite · AMD64 / ARM64 · Apache-2.0
REQUEST → RESPONSE → RECOVERY
Six ways to use Ferry
Requests, responses, fallback, queues, logical models and reset credits.
Return the result. Keep working.
Streamed text, tool arguments and completion events travel back to the same client.
Primary fails. A fallback takes over.
A temporary failure on one account can move the request to a compatible backup.
Rate limited? Wait, then continue.
Hold requests while capacity is unavailable; release them in order when it opens.
Change models. Keep your integration.
Your app calls a logical model such as work. Change the underlying model, account or route in Ferry without changing client configuration. Hermes is one example.
Configure logical models →Redeem credits before they expire.
AutoReset redeems available Codex reset credits within the expiry threshold and records the outcome. Default: 20 minutes before expiry; can be disabled.
Configure AutoReset →Illustrations, not live traffic. Recovery has time and attempt budgets, honors cancellation and cannot splice another upstream stream after visible output is committed.
FERRY / CAPABILITIES
What Ferry handles
Wait through rate limits
Keep eligible requests pending within a bounded recovery window.
Recover from upstream failures
Use a compatible fallback when the route permits recovery.
Control concurrency
Bound active requests and queue traffic at capacity.
Let agents help operate it
Use the Skill and management API to inspect, simulate and apply authorized changes.
Route by tested capabilities
Match the endpoint, model and protocol to the task.
Keep a stable model name
Change routes without changing the model name in every client.
Connect three protocols
Chat, Responses and Messages, within each route’s capabilities.
Inspect every attempt
Keep routing decisions, recovery, usage and cost evidence together.
GET STARTED
Two commands to start.
Create the administrator, add an upstream and issue a client key. No source build or separate database is required.
Installation, backups and upgrades →TERMINAL
curl -fsSLo compose.yaml https://github.com/hulkbig/ferry/releases/latest/download/compose.yaml
docker compose up -dOpen localhost:17910 to initialize.
Before you start
Does Ferry include accounts or credits?
No. Use your own API keys or supported subscriptions. Calls, retries and capability probes can incur upstream charges.
Will Thinking continue until success?
Waiting is bounded by recovery budgets. A client’s Thinking display is not evidence of continuous upstream reasoning.
Are all combinations verified?
No. Some account drivers have offline coverage only. Verify tools, streaming and follow-up turns on your own routes.