AIGW is a local-first control plane for teams that use reviewed third-party AI services. It keeps providers, their Tokens and their models, points each client at one model, and writes only AIGW's own settings into each client's files. It does not relay model traffic, run a gateway, or own conversation state.
Each client resolves its endpoint and model from its own selection. Read the authority boundary for the complete design.
| Goal | Command | Then |
|---|---|---|
| Set up a provider, client and model | aigw setup |
Follow Next |
| Apply a reviewed team file | aigw setup --from team.toml |
Connect any one provider when ready |
| Inspect current state | aigw |
Follow Next |
| Point a client at a model | aigw use <client> <provider/model> |
Follow Next |
| Replace one provider's Token | aigw provider rotate <provider> |
Follow Next |
| Diagnose a problem | aigw check --depth local --verbose |
Run its Fix |
| Find a model to use | aigw model search <query> |
aigw use <client> <provider/model> |
aigw check sends one bounded inference request by default and may use
provider quota. Use aigw check --depth endpoint for a model-free endpoint
check.
On macOS, install the signed and notarized stable release with Homebrew:
brew install --cask HengYangDS/tap/aigwFor macOS, Linux, or Windows without Homebrew, download the archive and checksum manifest for the host from either release peer. The published matrix covers Darwin, Linux, and Windows on AMD64 and ARM64. Extract the archive, then run:
./aigw self install.\aigw.exe self installThe portable installer copies only the running executable, retains one
predecessor for rollback, and prints the installed path. It does not alter
PATH, read Tokens, configure clients, or start another product. Confirm the
active program before setup:
aigw self status
aigw versionIf the installed directory is not yet on PATH, invoke the printed absolute
path.
Package-manager and portable installations have different owners; see the installation lifecycle before updating or removing one.
0.7.0 reads only aigw.toml. It never reads or changes AIGW's config.toml or
the component files config.*.toml that earlier releases wrote, and it ships no
importer for them. A home that holds only those files has no configuration, and
aigw names aigw setup.
After upgrading:
- Run
aigw setup --from <team file>oraigw setup. A provider that you add under its earlier ID finds the Token already stored for it, and setup reuses that Token without a prompt. - Run
aigw use <client> <provider/model>for each client.
Client sessions that started before the upgrade keep working, because they call
the credential reader they started with, and that reader still reads the
untouched config.toml. Delete config.toml and config.*.toml once those
sessions have ended; AIGW never deletes them. A Hermes session that started
before the upgrade names a provider ID that no longer exists on the responses
or chat protocol, because those Hermes provider IDs are now
aigw-<provider>-<protocol>, such as aigw-dmxapi-responses. aigw self rollback cannot return to a release older
than 0.7.0; see Update and rollback. A team member who
still runs 0.6.1 cannot read a version 8 team file, so everyone upgrades first.
Interactive setup adds a provider or chooses an existing one, then asks for an installed client and a model from the provider's catalog, saves them, and checks the client. It is safe to run again:
aigw setupThe guided flow asks for a protocol when a client speaks more than one that
the provider serves. Without an installed client that can use the provider,
it adds the provider and stops; install a client, then run aigw setup again
to choose it and a model. Guided setup enables the client it configures, and
it has no preview: aigw setup --from team.toml --dry-run previews a team
file instead. aigw check checks the client files that AIGW
wrote, not the act of installing a client.
A script adds a provider and points a client at one of its models in two
commands. aigw provider add stores the Token only after the provider accepts
it in one authenticated request that names no model:
printf '%s\n' "$TEAM_TOKEN" \
| aigw provider add team \
--label "Team endpoint" \
--endpoint responses=https://api.example.com/v1 \
--token-stdin
aigw use codex team/model-idaigw use adds a model that the provider's catalog lists; --unlisted adds
one that it does not. Use --endpoint anthropic=<url> and an
Anthropic-compatible client for a native Anthropic endpoint. AIGW records the
endpoint choice; it does not insert or manage a gateway.
A team can instead distribute a reviewed, token-free team file. Save the
tracked manifests/team.toml as a local team.toml,
then run:
aigw setup --from team.tomlApplying the team file requires neither every provider Token nor an installed
client. To connect one provider during setup, name it. Its Token must be
available: a writable backend prompts for it, while env mode reads
AIGW_TOKEN_DMXAPI from the invoking process:
aigw setup --from team.toml --provider dmxapiWith a writable backend, unattended setup can pass that provider's Token on standard input:
printf '%s\n' "$DMXAPI_TOKEN" \
| aigw setup --from team.toml --provider dmxapi --token-stdinOther providers remain available without becoming prerequisites. With the environment backend, set one compatible provider variable, then activate its unselected reviewed recommendations without repeating setup:
aigw sync
aigw checkWith a writable credential backend, run aigw provider rotate <provider>, then
point a client at a model with aigw use <client> <provider/model>; use
synchronizes that client. An existing explicit selection is never replaced by
a newly available recommendation.
<client> is claude, claude-desktop, codex, or hermes. A model that a
client could use on more than one protocol needs an explicit --protocol; see
Hermes protocol and model selection.
sync discovers installed clients and changes only AIGW's settings in their
files. It reconciles enabled clients whose model, authentication, and client
files are available. With the read-only environment backend, a newly available
provider Token can also activate an unselected client's reviewed
recommendation; writable stores are not searched for unused Tokens. sync
never replaces an explicit selection or Token, or creates a missing client.
See the complete first-member and deferred-client journey.
Automatic selection uses the platform credential service when available and a
single platform-local fallback otherwise. An explicit
AIGW_SECRET_BACKEND=keyring, file, or env choice fails closed instead of
searching another store.
Environment mode is read-only and portable. Supply only the providers used by
that process through AIGW_TOKEN_<PROVIDER>; the client process must inherit
the same environment when its credential helper reads the Token. Exact
variable encoding, native-store behavior, and external credential executables
belong to the security model.
aigw
aigw use <client> <provider/model>
aigw status
aigw check
aigw check <client> --depth client| Command | Contract |
|---|---|
status |
Show what each client uses and whether it is ready; no network, no Token read |
check |
Check that each client works, as deep as --depth asks; model may use quota |
model list |
List the models you have added; no network, no Token read |
model search |
Search what providers offer, from their authenticated catalogs |
sync |
Make client files match the configuration |
config rollback |
Restore the configuration and client files from a verified snapshot or backup |
aigw check takes four depths, and each runs the ones before it: local
checks the configuration, the Token's presence, the client files and the
environment without a request; endpoint sends one authenticated request
that names no model; model, the default, sends one bounded inference
request; client runs a real client session, which may make several
quota-consuming requests. It checks every enabled client unless you name
clients. Use aigw sync --dry-run --json before reconciling drift. Human
output gives one next action; machine consumers use the command's JSON mode.
Declare native retry budgets explicitly when an endpoint owns recovery:
aigw client edit codex --request-retries 0 --stream-retries 0 --dry-run --json
aigw client edit codex --request-retries 0 --stream-retries 0
aigw client edit codex --native-retriesZero disables that native retry budget; --native-retries removes both, so
Codex uses its own defaults. Retry budgets belong to the client's provider:
changing the model or protocol within that provider keeps them, and
aigw use with another provider's model clears them and says so. Only Codex
currently exposes admitted native budgets. AIGW writes the declaration; it
neither retries requests nor guarantees exactly-once inference.
The client's selection owns this policy, not the shared team file. A portable program rollback first gives the retained program the current configuration, and refuses a program that cannot read it without changing programs or credentials.
Send one client through a local endpoint, such as the Responses Proxy, while its provider and model stay the same:
aigw client edit <client> --via http://127.0.0.1:8792/v1 --dry-run --json
aigw client edit <client> --via http://127.0.0.1:8792/v1
aigw client edit <client> --directThe client's selection records the upstream that forwarding reaches. AIGW
clears forwarding, and says so, whenever the client's upstream endpoint
changes: aigw use with another provider or protocol, or
aigw provider edit --endpoint for the endpoint that the client reaches.
--direct drops the forwarding endpoint and its recorded upstream together.
| Noun | Owns |
|---|---|
| Provider | A service you hold a Token for: its endpoints, one per protocol, and the Token |
| Model | What a provider serves, named provider/model, with the protocols AIGW may use it on |
| Family | Optional: which canonical model a provider's model is |
| Client | claude, claude-desktop, codex or hermes, with its selected model and files |
There is no global model selection: aigw use <client> <provider/model>
changes exactly one client. A present Token, synchronized files, an endpoint
check and a successful client session are different readiness claims.
Current source Adapters support Codex CLI/Desktop through their shared Codex Home, Claude Code through its user settings, Hermes through its provider configuration, and Claude Desktop through its separate third-party inference library. Tokens remain behind credential helpers. Missing clients stay untouched, and release support remains limited to clients with completed native evidence. Future clients require a separately admitted Adapter rather than reuse of another client's state.
See Product concepts for the vocabulary and Adapter admission for extension requirements.
| Surface | Owner |
|---|---|
| Providers, Tokens, models and each client's selection | AIGW |
| AIGW-marked settings in Codex, Claude Code, Hermes and Desktop files | AIGW |
| Codex conversations, JSONL, SQLite, and per-conversation models | Codex |
| Claude sessions and unrelated settings | Claude Code |
| External gateways and compatibility services | Their product/operator |
| IDE and ACP configuration | The IDE or ACP product |
A provider may use a direct URL or an independently operated compatible endpoint, including an explicit loopback URL. AIGW stores that choice and writes it into client files; it never installs, starts, stops, or diagnoses the external service.
Adding a compatible endpoint or model is configuration. A new host surface is a Client Adapter. Incompatible wire behavior belongs in an independent data plane. See the extension model.
aigw config rollback restores the configuration and client files.
aigw self rollback restores the retained portable program.
Homebrew-managed installations use Homebrew for program upgrades and removal.
For a portable installation:
aigw self update
aigw sync
aigw checkTo restore the retained predecessor:
aigw self rollback
aigw sync
aigw checkProgram rollback first gives the retained program an isolated copy of the
current configuration and, when that program cannot read it, refuses and
changes nothing. A release older than 0.7.0 cannot read aigw.toml, so
aigw self rollback cannot return to one. An earlier release that you install
by other means finds its own files as they were before the upgrade, without
later changes.
On macOS, a signed AIGW release reads the Keychain Tokens that another signed
release stored, so an upgrade, a program rollback and a Homebrew downgrade move
no Token. AIGW does not take over an item that 0.3.5 or earlier stored. A
command that meets such an item says that another program stored it and names
the fix: have the credential at hand, delete the item with
security delete-generic-password -s AIGW_TOKEN -a <provider>, then store the
Token again with aigw provider rotate <provider>. A command that needs the
Token itself, such as aigw use, ends there; aigw sync and the other
commands that write several clients' files name the fix as their next step,
leave that provider's client waiting and complete for the rest. A release from
0.4.1 to 0.7.2 took such an item over only when its installed program read or
replaced it, so an item that none of them used that way is still the other
program's. On a Homebrew installation aigw self rollback is refused like the
other program commands, and Homebrew installs the earlier release.
An upgrade from 0.3.5 or earlier is a new setup. A release from 0.7.0 on does not read that release's configuration, and a release from 0.8.0 on does not read its Keychain Tokens. A session that still calls Homebrew's public credential-command link fails until its client is set up again. Later upgrades keep each versioned credential command callable. See the credential succession decision.
aigw self uninstall removes AIGW's settings from the client files, then the
portable executable and its predecessor. It retains versioned credential
reader files for cached or shared callers; a client whose settings are removed
cannot read its Token merely because the executable remains. Providers,
models, client selections, Tokens, configuration backup, and user-authored
client state remain.
For a Homebrew installation, disable enabled clients first with
aigw client disable <client> and let Homebrew remove the package; AIGW does
not overwrite or delete package-manager-owned files.
Online portable updates read the GitHub release that official builds name; a
GitLab peer joins only when AIGW_GITLAB_RELEASE_ORIGIN and
AIGW_GITLAB_RELEASE_REPOSITORY name one at run time. A selected peer must
provide one complete release; AIGW never combines a tag, checksum, or asset
across peers. Online portable updates authenticate checksums.txt.sig against
the release key embedded in AIGW before checking hashes, extracting, or executing
downloaded programs. Missing or invalid signatures stop the update and preserve
the current program and rollback file; downloads never supply their own trust.
Maintainer publication belongs to
Forge operations.
mise run bootstrap
mise run check
mise run nativeUse an isolated Work Lane, start behavior changes with a failing regression, run focused checks before the complete graph, and keep generated output under its declared owner. The contribution workflow maps each invariant to its source, test, gate, and evidence boundary.
- Documentation index
- Architecture and client-file boundary
- Security model
- Team rollout
- Terminal experience
- Change and release policy
- Decision Records
- Competitive research
Licensed under the MIT License.