A local, OpenAI-compatible proxy for Grok and ChatGPT. Sign in with your subscription, then connect OpenAI-compatible clients to one local API.
eggpass runs on your machine and sends inference requests directly to x.ai or
OpenAI. It does not relay requests through an eggpass cloud service. You do not
need a separate provider API key.
- Rust 1.89 or newer to install from source with Cargo
- A Grok subscription, a ChatGPT plan, or both
Install the published CLI from crates.io:
cargo install eggpassTo build the current repository checkout instead:
git clone https://github.com/eggstack/eggpass
cd eggpass
cargo install --path . --locked --forceeggpass login # choose a provider and sign in
eggpass key add laptop # copy the key; it is shown once
eggpass run # start the local server
eggpass status # check login and server stateThe x.ai login uses a device code by default. Use --oauth for a browser
redirect or --device to request the device-code flow explicitly. ChatGPT uses
a browser sign-in. Logging in again replaces that provider's saved credential.
eggpass run requires a client key. Issued keys are shown once and stored only
as salted hashes. Save the key for your client, for example:
export EGGPASS_API_KEY='paste-the-key-here'Replace MODEL_ID_FROM_V1_MODELS in the request below with an ID returned by
GET /v1/models.
Send a test request:
curl http://127.0.0.1:8484/v1/chat/completions \
-H "Authorization: Bearer $EGGPASS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"MODEL_ID_FROM_V1_MODELS","messages":[{"role":"user","content":"Hello"}]}'Use eggpass run --foreground to keep the server in the current terminal.
| Setting | Value |
|---|---|
| Base URL | http://127.0.0.1:8484/v1 |
| API key | The key from eggpass key add, or api_key in the config file |
| Model | An ID returned by GET /v1/models |
The client must send its key as Authorization: Bearer <key> or X-Api-Key: <key>. Setup examples for the OpenAI SDK, OpenCode, Cline, Continue, and curl
are in docs/client-setup.md.
To use the proxy from another machine, keep it bound to loopback and forward the port over SSH:
ssh -L 8484:127.0.0.1:8484 boxRequests are routed by model name. The longest matching prefix in the configuration wins; unmatched names go to the default provider.
GET /v1/models merges live catalogues from signed-in providers. A provider
that is unavailable or does not return a usable catalogue may contribute no
models. The response is normalized for OpenAI-compatible clients, so some
provider-specific models or fields may not appear. There is no built-in model
list. Check the endpoint for current IDs before configuring a client.
eggpass supports Chat Completions and the Responses API. Chat Completions
requests for ChatGPT are translated to and from the Responses API. Details on
routing, streaming, and supported fields are in
docs/how-it-works.md.
The server requires at least one client key to start. Create and manage issued
keys with eggpass key add, eggpass key list, and eggpass key revoke.
Alternatively, set api_key in the config file. A key change takes effect on
the next request, without a restart.
The server binds to 127.0.0.1 by default. A loopback port can still be
reached by web pages, so the key is required. GET /health returns the version
string, and GET /v1/last-inference returns only the last client-facing HTTP
status per provider. Those two endpoints do not require a key.
Inference requests, including prompts and responses, are sent to the selected
provider. eggpass does not keep prompt or response history. It keeps only the
most recent inference status for each provider in daemon memory; that state is
cleared when the daemon stops.
| Command | Purpose |
|---|---|
eggpass login |
Sign in to a provider. |
eggpass logout |
Revoke and remove a provider credential. |
eggpass status |
Show provider login and server state. |
eggpass usage |
Show subscription usage where available, preferring the running daemon's cached report. |
eggpass run |
Start the server. Use --foreground to keep it in the terminal. |
eggpass stop / restart |
Stop or restart the server. |
eggpass port / host |
Show or change the listen address. Changes restart a running server; when stopped, they take effect at the next start. |
eggpass key |
Add, list, or revoke client keys. |
eggpass edit |
Edit the config file. |
eggpass croncheck |
Start the server if it is not running. |
eggpass update |
Install a verified published release. |
See docs/commands.md for flags, exit codes, and side effects.
The config file is ~/.config/eggpass/config.toml. It is created with defaults
on first run and can be opened with eggpass edit.
host = "127.0.0.1"
port = 8484
api_key = ""See docs/configuration.md for routing, provider settings, timeouts, and files on disk.
| Document | Contents |
|---|---|
| Commands | Command syntax, options, and effects |
| Client setup | OpenAI SDK, OpenCode, Cline, Continue, and curl |
| Configuration | Config settings and files |
| How it works | Routing, translation, authentication, and streaming |
| Updating | Update verification and rollback |
| Troubleshooting | Common errors and fixes |
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
cargo build --releaseTests use a local stub upstream and do not access provider services.
MIT. See LICENSE.