AIGW is a local-first control plane for teams that use reviewed third-party AI services. It manages Accounts, Tokens, reusable Routes, explicit client bindings, and guarded native projections. It does not relay model traffic, run a gateway, or own conversation state.
Each client resolves its endpoint and model from its own binding. Read the authority boundary for the complete design.
| Goal | Command | Then |
|---|---|---|
| Connect the first Account | aigw setup |
Follow Next |
| Import reviewed team settings | aigw setup --from team.toml |
Connect any one Account when ready |
| Inspect current state | aigw |
Follow Next |
| Bind a Route to a client | aigw use --for <client> <route> |
Follow Next |
| Replace one Account Token | aigw rotate <account> |
Follow Next |
| Diagnose a problem | aigw doctor |
Run its recommended action |
| Migrate retained local state | aigw config migrate --dry-run |
Review, then apply |
aigw check sends a selected-model request by default and may use provider
quota. Use aigw check --endpoint-only 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 install.\aigw.exe 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 installation
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.
Interactive setup creates one Account and one Route, then binds the explicitly selected client when its prerequisites are available:
aigw setupThe guided flow offers admitted clients and asks for a protocol when a client
supports more than one. It preserves the Account, Token, Route, and selection
if the client is not installed; install that client and run aigw sync later.
aigw check verifies a projected binding, not the act of installing a client.
To connect a direct OpenAI Responses endpoint without a team manifest:
printf '%s\n' "$TEAM_TOKEN" \
| aigw add team \
--label "Team endpoint" \
--openai-url https://api.example.com/v1 \
--model model-id \
--for codex \
--token-stdinUse --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 manifest. Save the tracked
manifests/team.toml as a local team.toml, then run:
aigw setup --from team.tomlImporting the team catalogue requires neither every provider Token nor an
installed client. To connect one Account during setup, select only that Account.
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 --account dmxapiWith a writable backend, unattended setup can bind the stdin Token to that Account explicitly:
printf '%s\n' "$DMXAPI_TOKEN" \
| aigw setup --from team.toml --account dmxapi --token-stdinOther Accounts remain available without becoming prerequisites. With the environment backend, set one compatible Account variable, then activate its unselected reviewed recommendations without repeating setup:
aigw sync
aigw checkWith a writable credential backend, run aigw rotate <account>, then select
the desired Route with aigw use --for <client> <route>; use synchronizes
that client. An existing explicit selection is never replaced by a newly
available recommendation.
--for accepts claude, claude-desktop, codex, and hermes. A Route
exposing more than one compatible protocol requires an explicit choice; see
Hermes protocol and model selection.
sync discovers installed clients and changes only AIGW-owned projection state.
It reconciles enabled client bindings whose Route, authentication, and native
surface are available. With the read-only environment backend, a newly available
Account Token can also activate an unbound client's reviewed recommendation;
writable stores are not searched for unselected Tokens. sync never replaces an
explicit selection or Token, or creates a missing client. See the complete
first-member and deferred-client journey.
An installation retaining the preceding schema fails normal commands closed. Preview its deterministic replacement before applying it:
aigw config migrate --dry-run
aigw config migrate
aigw sync
aigw checkMigration changes only AIGW configuration. It preserves Account Tokens, client
files, sessions, and one exact predecessor configuration. Before rolling the
program back, restore that predecessor with aigw config migrate --rollback.
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 Accounts used by
that process through AIGW_TOKEN_<ACCOUNT>; the client process must inherit the
same environment when its projected helper reads the Token. Exact variable
encoding, native-store behavior, and external credential executables belong to
the security model.
aigw
aigw use --for <client> <route>
aigw status
aigw check
aigw verify --for <client>| Command | Contract |
|---|---|
status |
Observe Client Bindings and projection readiness without reading Tokens |
check |
Check enabled clients; default inference may use provider quota |
doctor |
Explain current problems without mutation |
repair |
Reconcile bounded AIGW-owned client state |
test |
Probe an endpoint without model inference or native-client execution |
verify |
Run a real-client session; it may make multiple quota-consuming requests |
rollback |
Restore verified or previous configuration and client projections |
Use aigw repair --dry-run --json before repairing drift. Human output gives one
next action; machine consumers use the command's JSON mode where available.
aigw check examines all enabled clients unless --for <client> limits its
credential, projection, and network observations to one enabled client.
| Entity | Owns |
|---|---|
| Account | Provider endpoints and one logical Token boundary |
| Route | account + model and reusable display metadata |
| Client binding | One client's Route, enabled intent, protocol, and options |
| Native projection | The AIGW-owned portion of one client's configuration |
There is no global model selection: aigw use --for <client> <route> changes
exactly one client binding. A present Token, synchronized file, endpoint probe,
and successful native-client request 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. Account 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 entity model and Adapter admission for extension requirements.
| Surface | Owner |
|---|---|
| Accounts, Tokens, Routes, and client bindings | AIGW |
| AIGW-marked Codex, Claude Code, Hermes, and Desktop projections | 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 |
An Account may use a direct provider URL or an independently operated compatible endpoint, including an explicit loopback URL. AIGW stores and projects that choice; 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 rollback restores configuration and client projections.
aigw update --rollback restores the retained portable executable.
Homebrew-managed installations use Homebrew for program upgrades and removal.
For a portable installation:
aigw update
aigw sync
aigw checkTo restore the retained predecessor:
aigw update --rollback
aigw sync
aigw checkProgram rollback does not silently downgrade configuration. If the predecessor
cannot read an isolated copy of current configuration, AIGW leaves both program
and configuration unchanged. Restore a compatible configuration explicitly with
aigw config migrate --rollback, then retry aigw update --rollback.
On macOS, the installed AIGW program moves Keychain Tokens saved by 0.3.5 and
earlier to its own reader the first time it uses them; nothing needs to be
entered again. The versioned credential readers that clients call never move a
Token, so a predecessor that is still installed keeps reading it.
aigw update --rollback returns the Tokens to the retained program's reader
after admitting the rollback and before activating that program. Before a
Homebrew downgrade, run aigw update --rollback on the Homebrew installation:
it returns the Tokens without touching Homebrew's files, and the next Token use
by a kept release takes them back. If it cannot read the configuration, it
moves no Token and reports that the credentials are not ready. Without that
step, the older program asks macOS to allow access to each Token.
The first Homebrew upgrade from 0.3.5 or earlier is a managed cutover, not a bare
brew upgrade aigw: existing sessions may still call Homebrew's public
credential-command link. Before the switch, the release operator must stage
the final successor's private reader, verify its exact commands against the
existing Account items without a prompt, preproject managed clients, and prefetch the
verified Cask. Measure the bounded link gap, then immediately test captured
commands and real clients; restore the predecessor if acceptance fails. Do not
switch if a required existing native item cannot be read noninteractively.
A session still caching the public link may fail once during the gap. Blanket client shutdown or restart does not eliminate that risk and is not an upgrade step. Later versioned-reader upgrades must keep old commands callable. See the credential succession decision.
aigw uninstall withdraws AIGW-owned client projections and removes the
portable executable plus its predecessor. It retains versioned credential
reader files for cached or shared callers; a withdrawn Client Binding cannot
read its Token merely because the executable remains. Accounts, Routes, Client
Bindings, Tokens, configuration backup, and user-authored client state remain.
For a Homebrew installation, disable enabled clients first and let Homebrew remove the package; AIGW does not overwrite or delete package-manager-owned files.
Updates resolve GitLab and GitHub as independent optional peers. 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 projection boundary
- Security model
- Team rollout
- Terminal experience
- Change and release policy
- Decision Records
- Competitive research
Licensed under the MIT License.