Skip to main content

PyPI version Crates.io version Rust runtime License: MIT CI PyPI Downloads Crates.io Downloads

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 need eggpool 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)

Table of built distributions (wheels) for eggpool 0.8.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Release 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 log

Security 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.

Select from 3 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.8.3 This release

3 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page