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
  • Designed for lightweight deployments (Raspberry Pi, SBCs)
  • Transparent protocol transcoding between OpenAI and Anthropic request formats

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
[routing] Routing strategy, retry limits, quota mode
[dashboard] Dashboard toggle, theme, refresh interval
[providers.*] Provider configs with accounts and routing priority
[network] Outbound transport, DNS cache
[transcoder] Protocol transcoding between OpenAI and Anthropic formats

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-only in v1)
  • Streaming SSE events
  • 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)

What is not translated in v1 (lands in phase 6):

  • Tool calls / function calling
  • Vision / image content
  • Extended thinking / reasoning
  • Structured outputs (response_format / json_schema)

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)

When [dashboard].enabled = true, a multi-page dashboard is served at / with request stats, latency metrics, provider health, 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

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

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.3.7.tar.gz (614.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.3.7-py3-none-any.whl (566.4 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: eggpool-0.3.7.tar.gz
  • Upload date:
  • Size: 614.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.3.7.tar.gz
Algorithm Hash digest
SHA256 ff6f95b4f6a1f7530082fd8b910e9ceae607c7c36d4be0f19b58aee560e0e666
MD5 9defff84e29976e14d3a084e4320e831
BLAKE2b-256 b794437af1c3a87815b31a78bb5a2fb81693b28236a64ef586645f031781b28e

See more details on using hashes here.

File details

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

File metadata

  • Download URL: eggpool-0.3.7-py3-none-any.whl
  • Upload date:
  • Size: 566.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.3.7-py3-none-any.whl
Algorithm Hash digest
SHA256 4eefcf1db899c3e8e71f839721d11c452408b06c525e572a626316db4b4ec373
MD5 40521031cf01267598b66f1be1013260
BLAKE2b-256 ef41e43ca2b22e228444543767a0472cbef175bca32c5ab26ba46d25d16e19c8

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

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

This release

0.3.7 This release

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