EggPool
A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts behind OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages-compatible paths.
Features
- Client endpoints for OpenAI Chat Completions (
/v1/chat/completions), stateless OpenAI Responses (/v1/responses), and Anthropic Messages (/v1/messages), plus a bounded native-only remote-compaction operation (/v1/responses/compact) - Transparent bidirectional protocol transcoding between OpenAI and Anthropic, plus native Gemini wire codecs
- Load-based routing across multiple providers and accounts with dynamic model discovery, quota awareness, and health gating
- Optional sticky model-router aliases for virtual-model selection
- Request, token, latency, error, and cost tracking in SQLite, with a multi-page dashboard
- Model metadata enrichment from provider catalogs, OpenRouter, Artificial Analysis, and Hugging Face, including thinking/reasoning capability metadata
- Per-account outbound proxy support, including SSH proxies
- Managed multi-user access with per-user personal tokens, exact model-access policies, durable per-user and instance budgets, and browser-session admin
- Live config reload (
eggpool rehash) for provider/routing changes; host, port, and database changes needeggpool restart - Designed for lightweight deployments (Raspberry Pi, SBCs)
Quick Start
# Install and activate in this Bash/zsh session (verified binary; no Python required)
bash -o pipefail -c 'curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash' && export PATH="$HOME/.local/bin:$PATH"
# Or via your package manager: `uv tool install eggpool`, `pipx install eggpool`,
# or `cargo install eggpool` (Rust 1.89+). Targets: Linux x86_64, Linux aarch64, macOS arm64.
# Interactive onboarding — connect providers, validate, start
eggpool onboard
# Install as a systemd service
sudo env "PATH=$PATH" "HOME=$HOME" "$(command -v eggpool)" deploy systemd --install
See Deployment for systemd, cron, and production setup, and standalone binaries for install internals.
The curl install is binary-first: it fetches the qualified GitHub raw
executable for your target (SHA-256 verified before execution) and commits it
to ~/.local/bin/eggpool as a standalone-rust installation that uses
native eggpool update thereafter — it never invokes uv, pipx, pip, Python,
Cargo, or a source build. Windows and other unqualified targets are
unsupported. The command above adds the directory to this invoking shell
after a successful install; running the bare curl ... | bash form persists
future-shell PATH configuration but cannot change its parent shell. To use a
custom destination, set EGGPOOL_INSTALL_BIN_DIR inside the installer Bash
process and export that same path in the invoking shell, for example:
bash -o pipefail -c 'export EGGPOOL_INSTALL_BIN_DIR="$HOME/opt/eggpool/bin"; curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash' && export PATH="$HOME/opt/eggpool/bin:$PATH"
To update or switch to one exact catalogued release and to roll back, see Upgrading:
eggpool update # latest catalogued release, same owner
eggpool update 0.8.0 # exact historical-version switch
eggpool install-provenance shows the package manager or standalone update authority.
First Request
serve runs as a daemon (--verbose stays in the foreground). List your models, then call one:
eggpool serve
eggpool status
# For a managed installation, create a personal credential for this user and
# set its one-time value in the client environment:
eggpool users token USER --show-secret
export EGGPOOL_API_KEY='<personal-token-shown-once>'
# Liveness / readiness (no key needed)
curl http://127.0.0.1:11300/v1/healthz
# {"status":"ok"}
# Model ids available to your accounts
curl -H "Authorization: Bearer $EGGPOOL_API_KEY" \
http://127.0.0.1:11300/v1/models
# Chat completion (use any model id from /v1/models)
curl -H "Authorization: Bearer $EGGPOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}' \
http://127.0.0.1:11300/v1/chat/completions
Managed inference and integration requests use the caller's personal token as
Authorization: Bearer <token> (OpenAI-style) or x-api-key: <token>
(Anthropic-style). Legacy, pre-bootstrap installs may continue using the
shared server key until migration; it does not grant managed-user access. To pin a provider, qualify
the model as model/provider (e.g. "gpt-4o/openai"); eggpool accounts explain --model <id> shows per-account eligibility. Full endpoint list:
API reference.
Coding Agents
eggpool configsetup opencode --apply # managed OpenCode install with drift detection
eggpool configsetup codex --model <eggpool-model-or-alias>
eggpool configsetup claude-code
eggpool configremote codex # secret-free remote profile for other machines
Generated configs reference EGGPOOL_API_KEY without embedding the key. Set it to a personal token from eggpool users token USER --show-secret; eggpool getkey is only for legacy installs. See Agent Configuration for all targets, the managed --apply/--sync/--check/--remove lifecycle, remote profiles, and the transactional eggpool-connect desktop helper.
Dashboard & LAN Access
By default EggPool binds 0.0.0.0:11300 and serves a public read-only dashboard at http://<lan-ip>:11300/. To share with desktops on your LAN, set [integrations].advertise_base_url = "http://<lan-ip>:11300/v1", run eggpool rehash (advertised URL is live-reloadable profile output; it never changes the listen socket), then export a profile with eggpool configremote codex. Lock it down with [server].host = "127.0.0.1" (local only) or eggpool dashboard public --off (key required on the dashboard too). See Firewall.
Browser password sign-in is shown only over loopback or trusted HTTPS proxy
transport. A remote plaintext HTTP visit to /login receives an explanation
without a username or password form. For a solo headless device, use SSH port
forwarding to loopback; teams should use an operator-managed HTTPS proxy or
VPN. LAN inference tokens remain a separate API transport choice.
CLI Essentials
| Command | Description |
|---|---|
eggpool onboard |
Interactive onboarding wizard |
eggpool connect / eggpool connect list |
Add a provider account / list supported providers |
eggpool check-config |
Validate configuration |
eggpool serve / stop / restart / rehash |
Run, stop, restart, or live-reload the server |
eggpool status |
Concise proxy/provider health summary (--json supported) |
eggpool models refresh |
Refresh the model catalog |
eggpool accounts status |
Show account status (provider, priority, weight, enabled) |
eggpool backup / recover |
Create / restore timestamped backups |
eggpool update [VERSION] |
Install the latest or one exact catalogued release |
Full command list: CLI reference.
Configuration
One TOML file (--config > $EGGPOOL_CONFIG > ~/.config/eggpool/config.toml > ./config.toml). Provider/upstream API keys come from environment variables or .env, never the file; the EggPool server key itself lives under [server] (api_key, or api_key_env to own it via environment — eggpool newkey rotates it). Prefer eggpool connect over hand-editing; the commented config.example.toml (plus config.sbc.example.toml for SBCs) documents every section. Config changes are validated before apply and classified as live-reloadable (rehash) or restart-required — see Live Configuration Rehash and Providers.
Documentation
| Guide | Link |
|---|---|
| Deployment (systemd, cron, production) | Deployment |
| Provider catalog & configuration | Providers |
| Agent configuration | Agent configuration |
| API endpoints | API endpoints |
| Stateless Responses | Stateless Responses |
| Protocol transcoding | Protocol transcoding |
| Semantic model routing | Semantic model routing |
| Backup & restore | Backup & restore |
| Upgrading & rollback | Upgrading & rollback |
| Per-account outbound proxy | Per-account outbound proxy |
| Thinking & reasoning | Thinking & reasoning |
| Raspberry Pi setup | Raspberry Pi setup |
| Live Configuration Rehash | Live Configuration Rehash |
| Filesystem layout | Filesystem layout |
More guides: configuration reference, model context limits, firewall, performance profiles, network diagnostics, OpenCode stream stability, model-info OpenRouter debugging, live wire-surface verification, Codex compatibility smoke, standalone binaries, release procedure, dashboard qualification, migration history, database recovery, architecture overview.
This wheel installs the native Rust eggpool executable as a
platform-specific binary. The package keeps Requires-Python >=3.11 for
package-manager compatibility only; it is not a runtime interpreter
dependency. Install targets are Linux x86_64, Linux aarch64, and macOS arm64;
Windows proxy execution remains unsupported (only the eggpool-connect
desktop helper ships for Windows).
Development
# CI parity (mirrors .github/workflows/ci.yml `check` job)
cargo fmt --manifest-path rust/Cargo.toml --all -- --check
cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings
cargo test --manifest-path rust/Cargo.toml --workspace --all-targets -- --test-threads=1
# (CI runs no-default only for `check`/`clippy`, never `test`)
cargo check --manifest-path rust/Cargo.toml --workspace --all-targets --no-default-features
cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets --no-default-features -- -D warnings
# Local-only extras (not CI steps): locked build, no-default test,
# dev tooling env (`uv sync --locked` for CI parity)
cargo build --manifest-path rust/Cargo.toml --locked
cargo test --manifest-path rust/Cargo.toml --workspace --all-targets --no-default-features -- --test-threads=1
uv sync --dev
uv run ruff format --check scripts/ tests/tooling/
uv run ruff check scripts/ tests/tooling/
uv run pyright scripts/
uv run pytest tests/tooling/ -q --tb=short --maxfail=1
See AGENTS.md for focused test targets, subsystem guidance, and the optional physical-SBC qualification pass.
License
MIT
Metadata
Release files for eggpool 0.8.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| eggpool-0.8.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details for eggpool-0.8.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| eggpool-0.8.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for eggpool-0.8.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| eggpool-0.8.3-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for eggpool-0.8.3-py3-none-macosx_11_0_arm64.whl |
Total release size: 38.0 MB
Release files / eggpool-0.8.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | eggpool-0.8.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 12.7 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
5680185034a6086da16ef2ae0830133d691eafc8b6a4c7371a625077d3788894
|
|
BLAKE2b-256 checksum How to use checksums |
030f96cc2166147a8e86ef182ea7ee2b1df446db1b4b005b81a2bf6b342e2ae0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / eggpool-0.8.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | eggpool-0.8.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 12.1 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
d30a3b3265b302e7499843b8f8ceca66480060f0bcdadb51c5d36f95acdd993f
|
|
BLAKE2b-256 checksum How to use checksums |
87c9cff5b815c77791b62ca093433631e71b1cd353c20574056b39626affd9fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / eggpool-0.8.3-py3-none-macosx_11_0_arm64.whl
| Download URL | eggpool-0.8.3-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 13.2 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b136f2ce4bd97086ed29f3c52480b45cca182532bb7ee2c19c2f97e2e6b1e40a
|
|
BLAKE2b-256 checksum How to use checksums |
5d6d151c0f683957d733bd14d4f8eb55228e1b9f925ca3a1027f897ddbd08541
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for eggpool 0.8.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 3 files in this release have been uploaded with provenance metadata.
Attestation for eggpool-0.8.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.