PyPI version Python 3.11+ License: MIT CI

EggPool

A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts behind one OpenAI/Anthropic-compatible endpoint.

Features

  • Proxies model requests across multiple providers and accounts behind a single endpoint
  • Supports OpenAI-compatible and Anthropic-compatible upstream request paths
  • Dynamically discovers available models; routes by quota utilization
  • Per-account outbound proxy support (pproxy — SOCKS5, HTTP, Shadowsocks)
  • Tracks requests, tokens, latency, errors, and estimated costs in SQLite
  • Multi-page dashboard with 50+ themes, reliability, routing, and runtime views
  • Model metadata enrichment from provider catalogs, OpenRouter, Artificial Analysis, and Hugging Face
  • Designed for lightweight deployments (Raspberry Pi, SBCs)
  • Transparent protocol transcoding between OpenAI and Anthropic request formats
  • Thinking/reasoning capability-aware routing with configurable budget mapping

Quick Start

# Install (one-shot)
curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash

# Interactive onboarding — connect providers, validate, start
eggpool onboard

# Install as a systemd service
sudo env "PATH=$PATH" "$(command -v eggpool)" deploy systemd --install

See Deployment for alternative install methods (pipx, manual, production) and the full deployment guide.

CLI Reference

Command Description
eggpool serve Start the proxy server (--daemon to detach)
eggpool onboard Interactive onboarding wizard
eggpool connect Add a provider account interactively
eggpool connect list List supported providers
eggpool check-config Validate configuration
eggpool migrate Run database migrations
eggpool rehash Restart to apply config changes
eggpool stop Stop the running server
eggpool models refresh Refresh the model catalog
eggpool stats transcoding Show protocol transcoding statistics
eggpool accounts status Show configured account status (provider, priority, weight, enabled)
eggpool accounts explain Show per-account routing eligibility for a model
eggpool runtime-status Print runtime health summary
eggpool backup Create a timestamped backup
eggpool recover Restore from a backup archive
eggpool deploy systemd Install/manage systemd service
eggpool deploy cron Install watchdog cron (non-systemd)
eggpool update Check for and install updates

All commands accept --config /path/to/config.toml. Config resolution: --config > $EGGPOOL_CONFIG > ~/.config/eggpool/config.toml > ./config.toml.

Full command reference: docs/deployment.md

Configuration

Configuration lives in a single TOML file. API keys are loaded from environment variables or .env.

# Example provider configuration
[providers.opencode-go]
id = "opencode-go"
base_url = "https://opencode.ai/zen/go/v1"
protocols = ["openai", "anthropic"]

[[providers.opencode-go.accounts]]
name = "personal"
api_key = "sk-your-opencode-go-key"

Use eggpool connect for interactive provider setup. See docs/providers.md for the full provider catalog, configuration details, and troubleshooting.

Key Config Sections

Section Purpose
[server] Bind address, port (default 11300), API key, logging, threads
[upstream] Upstream API base URL, timeouts, connection pool
[database] SQLite path, WAL mode
[models] Catalog refresh, exposure mode, model collapse, withdrawal policy
[routing] Routing strategy, retry limits, quota mode, same-tier fairness
[dashboard] Dashboard toggle, theme, refresh interval
[providers.*] Provider configs with accounts and routing priority
[network] Outbound transport, DNS cache
[model_info] Optional model metadata refresh, aliases, overrides, and external source settings
[transcoder] Protocol transcoding between OpenAI and Anthropic formats

The catalog refresh is non-destructive by default: failed, empty, or partial upstream responses never silently de-pool a healthy account. Set [models].catalog_withdrawal_policy (preserve_until_health default, confirmed_once, confirmed_twice) to opt into destructive behavior on authoritative refreshes. See architecture/README.md § Catalog Refresh Semantics.

Full config reference: config.example.toml | docs/providers.md

Protocol transcoding

When [transcoder] enabled = true, EggPool bridges OpenAI Chat Completions and Anthropic Messages bidirectionally so a single client ecosystem (e.g. OpenCode, which speaks only OpenAI) can reach Anthropic-only upstreams (e.g. MiniMax International at api.minimax.io/anthropic) and vice versa.

What gets translated:

  • Request bodies (text + tool-use + vision + thinking + structured outputs)
  • Streaming SSE events (including tool-call deltas and thinking deltas)
  • Non-retryable error envelopes
  • Usage and cost fields (preserved exactly as the upstream reported them)

What is dropped with a structured warning log:

  • OpenAI fields with no Anthropic equivalent (logit_bias, presence_penalty, top_logprobs, etc.)
  • Anthropic fields with no OpenAI equivalent (top_k, cache_control)

Phase 6 feature flags ([transcoder.features]) — all off by default:

  • tools — bidirectional tool calling translation
  • vision — image/document content parts
  • thinking — extended thinking ↔ reasoning_content
  • structured_outputs — response_format / json_schema coercion
  • anthropic_primitives — top_k, cache_control, context_management, container, mcp_servers

See docs/transcoding.md for the full translation table and known limitations.

API Endpoints

Method Path Description
GET /v1/models List available models
POST /v1/chat/completions OpenAI-compatible chat completions
POST /v1/messages Anthropic-compatible messages
GET /v1/healthz Liveness check
GET /v1/readyz Readiness check
GET /api/backoffs Active upstream-derived account backoffs (?now=<epoch> for reproducible snapshots)
GET /api/model-info Enriched model metadata summaries
GET /api/model-info/{model_id} Enriched metadata detail for one model
GET /api/model-info/{model_id}/aliases Source-keyed alias rows for one model
GET /api/model-info/sources Model-info source health
POST /api/model-info/refresh Trigger model-info refresh — ?model_id=<id>&source=<provider_catalog|openrouter|artificial_analysis|huggingface>&force=1 for a single-model force refresh (auth-gated). model_id accepts provider-suffixed IDs (gpt-4o/openai); unknown source values return HTTP 400

When [dashboard].enabled = true, a multi-page dashboard is served at / with request stats, latency metrics, provider health, model-info detail pages, and more. Stats API available under /api/stats/*.

Documentation

Topic Link
Deployment (install, systemd, production) docs/deployment.md
Provider catalog & configuration docs/providers.md
Backup & restore docs/backup-restore.md
Per-account outbound proxy docs/proxy.md
Model context limits docs/model-limits.md
Raspberry Pi setup docs/raspberry-pi.md
Firewall configuration docs/firewall.md
Filesystem layout docs/filesystem-layout.md
Network & DNS diagnostics docs/network-diagnostics.md
Protocol transcoding docs/transcoding.md
Thinking & reasoning docs/thinking.md

Development

uv sync --extra dev
uv run ruff check src/ tests/ scripts/
uv run ruff format src/ tests/ scripts/
uv run pyright src/ scripts/
uv run pytest

Agent Configuration

eggpool configsetup generates configuration snippets for popular coding agents:

Target Command Output --write default Model Status
OpenCode eggpool configsetup opencode JSON provider config N/A (clipboard) auto stable
Claude Code eggpool configsetup claude-code JSON snippet N/A (clipboard) N/A stable
Aider eggpool configsetup aider Shell env exports .env.eggpool recommended stable
Codex eggpool configsetup codex TOML provider block N/A (printed) recommended version-sensitive
Qwen Code eggpool configsetup qwen-code JSON provider block N/A (printed) optional verify schema
Kilo eggpool configsetup kilo JSON provider block N/A (printed) optional verify schema
Continue eggpool configsetup continue YAML model block ~/.continue/eggpool.yaml usually yes stable fragment
Cline eggpool configsetup cline JSON profile cline-eggpool.json recommended paste into UI
Roo Code eggpool configsetup roo-code JSON profile roo-code-eggpool.json recommended paste into UI
Goose eggpool configsetup goose Shell env exports N/A (printed) recommended verify env vars
OpenHands eggpool configsetup openhands Shell env exports N/A (printed) recommended stable fragment

Shared options: --host, --base-url, --model, --write, --output, --force, --no-clipboard, --print-secret. Generated JSON, TOML, YAML, and shell snippets escape catalog/config values for the target format, including provider-suffixed model IDs.

Examples:

eggpool configsetup aider --model openai/gpt-4 --write
eggpool configsetup continue --model claude-sonnet-4 --output ~/.continue/eggpool.yaml
eggpool configsetup cline --no-clipboard

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.8.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dbowman91 from gravatar.com dbowman91

Credits

Author: David Bowman

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

aggregation anthropic llm multi-account openai opencode proxy router

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eggpool-0.5.0.tar.gz (790.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

eggpool-0.5.0-py3-none-any.whl (728.4 kB view details)

Uploaded Python 3

File details

Details for the file eggpool-0.5.0.tar.gz.

File metadata

  • Download URL: eggpool-0.5.0.tar.gz
  • Upload date:
  • Size: 790.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for eggpool-0.5.0.tar.gz
Algorithm Hash digest
SHA256 daa56ff2b402ede3c20c6711f64bc7edd853d9509b84ec734e3ea2aba44f9751
MD5 d3ec5711a358fcaeb212185b633fb252
BLAKE2b-256 a4599ed5c05219d91e5be3018e93ce77862a828a33763f0fee0229766c2e9788

See more details on using hashes here.

File details

Details for the file eggpool-0.5.0-py3-none-any.whl.

File metadata

  • Download URL: eggpool-0.5.0-py3-none-any.whl
  • Upload date:
  • Size: 728.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for eggpool-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3cd7713bea3134ad044a6fada5304e316ebe3b394ed0e82821b525996023d2ef
MD5 4a96f4beb5b54dc6ee882385b19ab4aa
BLAKE2b-256 b7a78de18a615b3f63f508ac6eaeb533ec4abc7a58a47610f17231505171f485

See more details on using hashes here.

Release history Release notifications | RSS feed

0.8.0

3 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

This release

0.5.0 This release

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

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