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.9.tar.gz (615.7 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.9-py3-none-any.whl (567.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: eggpool-0.3.9.tar.gz
  • Upload date:
  • Size: 615.7 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.9.tar.gz
Algorithm Hash digest
SHA256 5018e37ddde08d5dcbea198d457c1bd5e93b63251e53699f993b9651644ab471
MD5 17ed0747b1c40734bb46eb28927d74cd
BLAKE2b-256 2dc5797751e70c74a6ad50c5d3ef027d9a57ee8881291eaf0fbbcdcdf9543f20

See more details on using hashes here.

File details

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

File metadata

  • Download URL: eggpool-0.3.9-py3-none-any.whl
  • Upload date:
  • Size: 567.1 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.9-py3-none-any.whl
Algorithm Hash digest
SHA256 ac1aff6d507b528d63313ecedeb36fd1bc5342182eb18a290eb337ae9c9bc08d
MD5 1f8a6cb001921b0f80d7dbaa44b7ae14
BLAKE2b-256 54ab93bab8de1e19672240dd9a9044d71e284e2ad7f9c8f6dff9ff4f0b51902c

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

This release

0.3.9 This release

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