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.4.8.tar.gz (776.6 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.4.8-py3-none-any.whl (714.8 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for eggpool-0.4.8.tar.gz
Algorithm Hash digest
SHA256 0589085ab188c0ed49f9c0f6dc69f8993a55175284087421a4f1adbf247267d9
MD5 16ac9a248f58416aaf4c7d30900f2525
BLAKE2b-256 11a462e60da68d0debfe1db8a07107baa7917cfb401474f944920fcdc1a1f61b

See more details on using hashes here.

File details

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

File metadata

  • Download URL: eggpool-0.4.8-py3-none-any.whl
  • Upload date:
  • Size: 714.8 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.4.8-py3-none-any.whl
Algorithm Hash digest
SHA256 5f74e8373602a333cfbeaa36574c64e2894f28a78ec6debb6aeac0d97e2fd993
MD5 4f89f613337497ba9df6611e5b31b296
BLAKE2b-256 93a4d12293c4d254b0ce728c570224517b4b5e5ce10f2b764c914ef2fd1012ab

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

0.5.0

2 files

0.4.9

2 files

This release

0.4.8 This release

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