Skip to content
eggstackPublic

Repository files navigation

PyPI version Crates.io version Rust runtime License: MIT CI PyPI Downloads Crates.io Downloads

EggPool

EggPool is a self-hosted proxy that combines AI provider accounts behind familiar OpenAI and Anthropic API endpoints. Run it on your computer or LAN, then point coding agents and other clients at one local service.

What EggPool does

  • Routes requests across configured providers and accounts using health, quota, and priority information.
  • Translates supported OpenAI and Anthropic request formats. Gemini wire formats are also supported.
  • Provides a dashboard, model discovery, usage tracking, and optional local user accounts with personal API tokens.
  • Supports per-account outbound proxies, including SSH, and runs on Linux x86_64, Linux aarch64, and macOS arm64.

Windows and other unqualified targets are unsupported for the EggPool server.

Install and start

The recommended binary-first installer fetches the verified native executable from GitHub raw releases and installs it as standalone-rust. It verifies the SHA-256 checksum before execution and never invokes uv, pipx, pip, Python, Cargo, or a source build.

bash -o pipefail -c 'curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash' && \
  export PATH="$HOME/.local/bin:$PATH"
eggpool onboard

eggpool onboard creates a config if needed, guides you through provider setup, creates the first administrator on a new database, and starts the server. Save the personal API token it displays once. If output is redirected, use eggpool onboard --show-secret only on a secure console. For unattended password input, use --password-stdin.

Package-manager alternatives are uv tool install eggpool, pipx install eggpool, and cargo install eggpool (Rust 1.89 or newer). These alternatives use their package manager for updates. The native installer supports Linux x86_64, Linux aarch64, and macOS arm64.

For a systemd service or production deployment, see Deployment. For installation ownership, exact upgrades, and rollback, see Upgrading.

Make your first request

Set the personal token from onboarding in the environment used by your client:

export EGGPOOL_API_KEY='<personal-token-shown-once>'

# Liveness is public. Model discovery and inference require a personal token.
curl http://127.0.0.1:11300/v1/healthz
curl -H "Authorization: Bearer $EGGPOOL_API_KEY" http://127.0.0.1:11300/v1/models

Use a model ID returned by /v1/models:

curl -H "Authorization: Bearer $EGGPOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Hello!"}]}' \
  http://127.0.0.1:11300/v1/chat/completions

The API supports OpenAI Chat Completions, stateless OpenAI Responses, Anthropic Messages, and embeddings when an operator configures an eligible provider. See the API reference.

Coding agents

Generate a local client configuration or export a remote profile for another machine:

eggpool configsetup opencode --apply
eggpool configsetup codex --model <eggpool-model-or-alias>
eggpool configremote codex

Generated configurations reference EGGPOOL_API_KEY; they do not contain the resolved key. Use a personal token for each managed user. See Agent Configuration for supported clients, managed setup, and desktop installation.

LAN access and security

EggPool listens on 0.0.0.0:11300 by default. Keep the port on a trusted LAN or VPN and do not expose it directly to the public internet. Browser password sign-in requires loopback or trusted HTTPS proxy transport. For a headless device, use SSH port forwarding. For a team, use an operator-managed HTTPS proxy or VPN. See Firewall.

The personal token authenticates inference, model discovery, and integration profiles. It does not grant dashboard or administrator access. The shared [server].api_key is for legacy installations and is retired after local user access is initialized.

Configuration and updates

Configuration is read from --config, then $EGGPOOL_CONFIG, then $XDG_CONFIG_HOME/eggpool/config.toml (or ~/.config/eggpool/config.toml when unset, if present), then ./config.toml. Provider credentials belong in environment variables or the config-adjacent .env file, not in config.toml. Prefer eggpool connect to add an account; see Configuration and Providers.

eggpool check-config
eggpool update
eggpool update 0.8.0
eggpool install-provenance

eggpool update installs the latest catalogued release. A version argument selects that exact catalogued release. eggpool install-provenance shows which package manager or standalone updater owns the installation.

Documentation

Guide Use it for
Deployment Personal, systemd, and production setup
Providers Provider setup, account routing, and model discovery
Agent Configuration Coding-agent setup and remote profiles
CLI Reference Command options and local administration
API Reference Endpoints, authentication, and request limits
Configuration Model-router settings
Backups and Restore Backup, restore, and recovery
Upgrading Updates, rollback, and installation ownership
Raspberry Pi Single-board computer setup
Proxy Configuration Per-account outbound proxies

Additional references cover protocol transcoding, stateless Responses, model routing, context limits and budgets, reasoning, and database recovery.

Development

The runtime is Rust. See AGENTS.md for current formatting, lint, test, and tooling commands.

License

MIT

Releases

Packages

Contributors

Languages