PyPI version Python 3.11+ License: MIT CI PyPI Downloads

EggPool

A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts behind OpenAI Chat Completions- and Anthropic Messages-compatible paths.

Features

  • Single endpoint for OpenAI Chat Completions (/v1/chat/completions), Anthropic Messages (/v1/messages), and stateless Responses passthrough (/v1/responses)
  • Transparent bidirectional protocol transcoding between OpenAI and Anthropic
  • Dynamic model discovery with load-based routing across multiple providers and accounts
  • Request, token, latency, error, and cost tracking in SQLite
  • Multi-page dashboard with 50 themes
  • Model metadata enrichment from provider catalogs, OpenRouter, Artificial Analysis, and Hugging Face
  • Thinking/reasoning capability-aware routing with configurable budget mapping
  • Per-account outbound proxy support (pproxy — install with uv sync --extra proxy)
  • Optional orjson backend for faster JSON handling (uv sync --extra fast)
  • Designed for lightweight deployments (Raspberry Pi, SBCs)

For full details on features, architecture, and design decisions, see architecture/README.md.

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.

First-Time Setup

After installation, eggpool onboard walks you through:

  1. Connecting providers — add API keys for your AI providers (OpenAI, Anthropic, OpenRouter, etc.)
  2. Configuration validation — check-config verifies your setup
  3. Starting the server — launch in daemon mode or as a systemd service
# Connect a specific provider
eggpool connect groq

# List available providers
eggpool connect list

# Validate configuration
eggpool check-config

# Start the server (daemon mode)
eggpool serve

# Start in foreground for debugging
eggpool serve --verbose

Printing an Agent Config

Generate configuration for your coding agent:

# OpenCode
eggpool configsetup opencode

# Claude Code
eggpool configsetup claude-code

# Aider (writes .env.eggpool)
eggpool configsetup aider --model openai/gpt-4 --write

# Codex (Responses wire API)
eggpool configsetup codex --print-secret

See Agent Configuration for all supported targets and options.

LAN Access

By default, EggPool binds to localhost. To expose it on your LAN:

  1. Set a server API key first: eggpool onboard (or set [server].api_key in config)
  2. Change the bind address: [server].host = "0.0.0.0" in ~/.config/eggpool/config.toml
  3. Restart: eggpool restart

See Firewall for restricting access to your LAN.

CLI Commands

Command Description
eggpool serve Start the proxy server (daemon mode; --verbose for foreground)
eggpool stop Stop the running server
eggpool restart Fully restart the server (stop then start)
eggpool rehash Apply supported config changes live without restart (--json for structured output)
eggpool onboard Interactive onboarding wizard
eggpool connect Add a provider account interactively
eggpool connect list List supported providers
eggpool logout Remove a configured provider account
eggpool check-config Validate configuration
eggpool migrate Run database migrations
eggpool models refresh Refresh the model catalog
eggpool accounts list List configured provider accounts
eggpool accounts status Show account status (provider, priority, weight, enabled)
eggpool accounts explain Show per-account routing eligibility for a model
eggpool stats transcoding Show protocol transcoding statistics
eggpool stats repair-costs Dry-run/apply repair for suspicious historical request costs
eggpool stats recompute-costs Recompute cost_microdollars on historical requests
eggpool stats explain-dashboard Show EXPLAIN QUERY PLAN for dashboard queries
eggpool modelinfo show Show enriched model metadata
eggpool modelinfo list List model-info entries
eggpool modelinfo refresh Trigger model-info source refresh
eggpool modelinfo aliases Show model aliases
eggpool modelinfo repair Repair legacy canonical model-info detail blocks
eggpool dashboard public Print dashboard public URL
eggpool runtime-status Print runtime health summary
eggpool backup Create a timestamped backup
eggpool recover Restore from a backup archive
eggpool db vacuum Vacuum the SQLite database
eggpool set Set a config value
eggpool edit Edit config in $EDITOR
eggpool getkey Print the server API key
eggpool newkey Generate and write a new server API key
eggpool init-config Initialize config from template
eggpool version Show installed version
eggpool croncheck Fast-path cron watchdog check (stdlib-only)
eggpool ensure-running Ensure server is running (stdlib-only)
eggpool deploy systemd Print/install systemd unit
eggpool deploy cron Install watchdog cron (non-systemd)
eggpool deploy backup-cron Install daily backup cron job
eggpool deploy logrotate Print/install logrotate config
eggpool deploy all Print every deployment snippet in sequence
eggpool configsetup Generate config snippets for coding agents (see Agent Configuration)
eggpool update [VERSION] Check for latest, or install an exact PyPI release (v prefix accepted)
eggpool uninstall Uninstall EggPool from this machine

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

Full deploy commands 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, WAL size limit
[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 and proxy settings
[transcoder] Protocol transcoding between OpenAI and Anthropic
[metrics] Observability write buffering (immediate / balanced / low_wear)
[security] Redacted error-detail persistence
[backup] Opt-in automatic daily backups
[limits] Spend ceilings per account (5h / weekly / monthly microdollars)
[pricing] Pricing catalog sources and missing-rate fallback
[model_info] Multi-source model metadata enrichment
[maintenance] Bounded maintenance budget, SQLite hygiene, contention guard

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

Live Config Changes

eggpool rehash applies provider/account/routing/model-override changes without a restart. Disruptive changes (host, port, database path) require eggpool restart.

See Live Configuration Rehash for the full reload flow and supported fields.

Documentation

Topic Link
Deployment (install, systemd, production) docs/deployment.md
Provider catalog & configuration docs/providers.md
API endpoints docs/api-reference.md
Agent configuration (OpenCode, Claude Code, Aider, etc.) docs/agent-configuration.md
Stateless Responses support docs/stateless-responses.md
Protocol transcoding docs/transcoding.md
Backup & restore docs/backup-restore.md
Release procedure docs/releasing.md
Per-account outbound proxy docs/proxy.md
Model context limits docs/model-limits.md
Thinking & reasoning docs/thinking.md
Raspberry Pi setup docs/raspberry-pi.md
Copyable SBC configuration config.sbc.example.toml
Configuration profiles docs/config-profiles.md
Firewall configuration docs/firewall.md
Filesystem layout docs/filesystem-layout.md
Network & DNS diagnostics docs/network-diagnostics.md
OpenCode stream stability docs/opencode-stream-stability.md
Model-info OpenRouter debugging docs/model-info-openrouter-debug.md
Live Configuration Rehash docs/live-config-rehash.md
Dispatch stability runbook docs/operations/dispatch-stability.md
Database recovery runbook docs/runbooks/database-recovery.md
Architecture overview architecture/README.md

Development

uv sync --extra dev      # install dependencies

# Reproduce the exact CI environment (without local coverage tooling)
uv sync --frozen --extra ci

# Before-push check (matches CI job)
uv run ruff format --check src/ tests/ scripts/
uv run ruff check src/ tests/ scripts/
uv run pyright src/ scripts/
uv run pytest tests/smoke/ -q --tb=short --maxfail=1

# Optional `orjson` backend for the JSON helper (transcoding hot paths)
uv sync --extra fast     # or: uv pip install 'eggpool[fast]'

CI

One GitHub Actions job on every PR:

Job Python What it does
check 3.11 ruff format + ruff check + pyright + pytest tests/smoke/

See AGENTS.md for focused test subset commands.

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

MIT License

Requires

Python >=3.11

Provides Extra

ci dev fast proxy

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.7.0.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

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

eggpool-0.7.0-py3-none-any.whl (1.2 MB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for eggpool-0.7.0.tar.gz
Algorithm Hash digest
SHA256 fc8bca226eff1979764372c75dda5daf2c6c90da6d5da8bf0bb89ab0575864d9
MD5 6c78f46ad7d8bc920a5285684a4a7227
BLAKE2b-256 133a9bfd46037681705db98b9e2ca250a0d6548a722e847003f5fafdc6ad261a

See more details on using hashes here.

File details

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

File metadata

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

File hashes

Hashes for eggpool-0.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1f86d933b143c8ec847efdf3f5b98ad1a2b6172afa533de3608244a7d4883fef
MD5 d64625012d3c373ac78fe6cabadacf8e
BLAKE2b-256 efce8541908f038d313316c1b6d053f22bb8a7f90fb7fb6ef328ca1e1e846ad2

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

This release

0.7.0 This release

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

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