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.8.tar.gz (615.3 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.8-py3-none-any.whl (566.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: eggpool-0.3.8.tar.gz
  • Upload date:
  • Size: 615.3 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.8.tar.gz
Algorithm Hash digest
SHA256 fa472f48176215f7f41180ee6c6ae2898d78e9e0df83a1ae5886009c6182db0e
MD5 37dfa12d1e335092396a29b6089324a3
BLAKE2b-256 8d5de9511a6f0fb3c3802f222d228830bad91045b8f1633c2a6c75b1f58927c7

See more details on using hashes here.

File details

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

File metadata

  • Download URL: eggpool-0.3.8-py3-none-any.whl
  • Upload date:
  • Size: 566.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.3.8-py3-none-any.whl
Algorithm Hash digest
SHA256 0fb5339db8fc3faf1510aabec12abe997ab02d747bb76d11c8c2bcf802f20d5a
MD5 66b922816df3585c9e9eb2dd322663a0
BLAKE2b-256 bf5692cfcf77feeb023668f190596951b410c158b11e1a567551deb2749d965c

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

This release

0.3.8 This release

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