### Quickstart with virtualenv Source: https://github.com/0xzr/freellmpool/blob/main/README.md Portable virtual-environment path for the quickstart. Creates a venv, activates it, upgrades pip, installs freellmpool, and runs the same ask command as the uvx quickstart. ```bash python3 -m venv .venv . .venv/bin/activate python -m pip install --upgrade pip python -m pip install freellmpool freellmpool ask --max-tokens 32 "Reply with one short sentence: freellmpool is ready." ``` -------------------------------- ### freellmpool init non-interactive examples Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md Non-interactive examples of the freellmpool init command. The first prints an actionable setup plan for the opencode agent; the second includes Tailnet serve and remote client setup for the metaswarm agent. ```bash freellmpool init --agent opencode --yes ``` ```bash freellmpool init --agent metaswarm --tailnet --yes ``` -------------------------------- ### Quickstart with uvx Source: https://github.com/0xzr/freellmpool/blob/main/README.md Runs the quickstart with uvx, requiring no checkout or manually managed virtualenv. Fresh install to first reply is about 19 seconds on a clean Linux/Python 3.12 environment when a keyless provider is up. ```bash uvx freellmpool ask --max-tokens 32 "Reply with one short sentence: freellmpool is ready." ``` -------------------------------- ### Metaswarm setup commands Source: https://github.com/0xzr/freellmpool/blob/main/docs/AGENTS.md Copy-pastable setup for Metaswarm: initializes the agent, installs the profile, starts the tailnet serve with a dedicated token, and runs a dry-run doctor. Without an explicit key, tailnet serve exits 2 before starting. ```bash freellmpool init --yes --agent metaswarm --tailnet freellmpool profile install metaswarm FREELLMPOOL_PROXY_KEY='' freellmpool tailnet serve --port 8080 freellmpool profile doctor metaswarm --dry-run ``` -------------------------------- ### Run freellmpool init --yes for first-run setup Source: https://github.com/0xzr/freellmpool/blob/main/README.md Run the first-run setup in detect-only mode. It inspects provider keys, installed agent CLIs, Tailscale state, and proxy config, then prints one copy-pastable next step without editing files. Use --json to emit the same detection as versioned JSON for scripts and agents. ```bash freellmpool init --yes ``` -------------------------------- ### Print coding agent setup and profile commands Source: https://github.com/0xzr/freellmpool/blob/main/README.md Prints setup instructions for coding agents (aider, claude, codex, cline, continue, cursor, hermes, opencode) and shows or dry-runs profile installation without mutating third-party config. ```bash freellmpool code aider # also: claude, codex, cline, continue, cursor, hermes, opencode freellmpool profile show opencode freellmpool profile doctor opencode --dry-run ``` -------------------------------- ### Start tracked work with $start Source: https://github.com/0xzr/freellmpool/blob/main/AGENTS.md Invoke the default entry point to begin tracked work on a task. It primes the agent with relevant knowledge, guides through scoping, and selects the appropriate process level. ```text $start ``` -------------------------------- ### Install and start freellmpool proxy Source: https://github.com/0xzr/freellmpool/blob/main/docs/promotion/reddit-opencode.md Installs freellmpool and starts the local proxy on port 8080, which OpenCode will connect to as an OpenAI-compatible endpoint. ```bash pip install freellmpool freellmpool proxy --port 8080 ``` -------------------------------- ### Install and use freellmpool CLI and proxy Source: https://github.com/0xzr/freellmpool/blob/main/docs/best-free-llm-api-gateway.html Install freellmpool via pip, then use the CLI to ask a question keylessly when an enabled route is available, or start the local proxy which exposes an OpenAI-compatible endpoint and an experimental Anthropic path. ```bash pip install freellmpool freellmpool ask "Explain the CAP theorem in one sentence." # keyless when routes are available freellmpool proxy # OpenAI + exp. Anthropic path ``` -------------------------------- ### Install and ask via CLI Source: https://github.com/0xzr/freellmpool/blob/main/docs/promotion/long-form-article.md Install freellmpool and run a one-shot ask from the CLI. The ask command sends a prompt to the pool and prints the reply. ```bash pip install freellmpool freellmpool ask "Explain semantic versioning in one paragraph." ``` -------------------------------- ### freellmpool CLI commands for setup, profiles, ask, recipes, jobs, reports, and tailnet Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md New user-facing CLI commands for freellmpool, covering init, profiles, ask, battle, playground, recipes, jobs, reports, quota-wise mode, and tailnet gateway. The commands are grouped by feature area and show the intended first-run experience after `pip install freellmpool`. ```bash freellmpool init freellmpool init --agent metaswarm --tailnet freellmpool profile list freellmpool profile show metaswarm freellmpool profile install opencode freellmpool profile doctor metaswarm freellmpool ask --role coder "fix this failing test" freellmpool ask --role critic < patch.diff freellmpool ask --second-opinion "is this design solid?" freellmpool roles freellmpool battle "which answer is strongest?" freellmpool playground freellmpool recipe list freellmpool recipe run pr-review --input patch.diff freellmpool recipe run repo-summary --path . freellmpool jobs add --recipe repo-summary --path docs/ freellmpool jobs run freellmpool jobs watch freellmpool report last --markdown freellmpool report last --html --open FREELLMPOOL_MODE=wise freellmpool ask --role cheap "summarize this" freellmpool quota-wise status freellmpool tailnet status freellmpool tailnet serve --port 8080 freellmpool tailnet connect ``` -------------------------------- ### Install freellmpool via pip Source: https://github.com/0xzr/freellmpool/blob/main/docs/llms.txt Install the freellmpool package from PyPI. This is the keyless start command mentioned in the project description. ```bash pip install freellmpool ``` -------------------------------- ### Install and use freellmpool CLI Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-llm-api-providers-list.html Install freellmpool and run the CLI to ask a question or list configured providers. The ask command is keyless when an eligible route is available. ```bash pip install freellmpool freellmpool ask "Explain the CAP theorem in one sentence." # keyless when an eligible route is available freellmpool providers # see which tiers you've configured ``` -------------------------------- ### Install llm-freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/plugins/llm-freellmpool/README.md Install the plugin using the llm CLI. ```bash llm install llm-freellmpool ``` -------------------------------- ### GET /readyz ready response Source: https://github.com/0xzr/freellmpool/blob/main/docs/ADOPTION_SPRINT_PLAN.md Example GET /readyz response when ready_providers > 0, returning HTTP 200. When none are ready, status becomes not_ready and reason becomes no_ready_providers with HTTP 503. ```json { "schema_version": 1, "status": "ready", "reason": "ready_providers_available", "ready_providers": 1, "total_providers": 2, "summary": { "ready": 1, "unconfigured": 0, "no_enabled_models": 0, "cooldown": 0, "quota_exhausted": 1 } } ``` -------------------------------- ### Run Claude Code on free models with freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-claude-api.html Install freellmpool, start the proxy, set the required environment variables, and launch Claude Code. The ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY are set to dummy values; ANTHROPIC_MODEL and ANTHROPIC_SMALL_FAST_MODEL are set to auto. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 enables gateway model discovery. Run `freellmpool code claude` to print this setup. ```bash pip install freellmpool freellmpool proxy export ANTHROPIC_BASE_URL=http://localhost:8080 export ANTHROPIC_AUTH_TOKEN=dummy export ANTHROPIC_API_KEY=dummy export ANTHROPIC_MODEL=auto export ANTHROPIC_SMALL_FAST_MODEL=auto export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 claude ``` -------------------------------- ### Install metaswarm profile with freellmpool CLI Source: https://github.com/0xzr/freellmpool/blob/main/docs/INTEGRATIONS.md Shows, installs, and dry-run checks the metaswarm profile. Includes Tailnet setup for remote agents, a free/cheap worker lane, a larger freellmpool reviewer lane, and Codex/Opus lanes only as explicit user-owned paid escalation/final-review tools. ```bash freellmpool profile show metaswarm freellmpool profile install metaswarm freellmpool profile doctor metaswarm --dry-run ``` -------------------------------- ### Compare responses and start local tools with freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/README.md Run a side-by-side comparison you can inspect in the terminal or local browser. `battle` compares responses, `proxy` starts a local proxy on port 8080, and `playground` starts a local playground on the same port. ```bash freellmpool battle "which changelog entry is clearer?" --synthesize freellmpool proxy --port 8080 freellmpool playground --port 8080 ``` -------------------------------- ### Install local package and copy plugin/tools Source: https://github.com/0xzr/freellmpool/blob/main/integrations/opencode/README.md Commands to pack the local package, install it into OpenCode's config directory, and copy the plugin and tools files. Required until registry publication is verified. ```sh cd /absolute/path/to/integrations/opencode npm pack npm install --prefix ~/.config/opencode ./opencode-freellmpool-0.1.0.tgz mkdir -p ~/.config/opencode/plugin ~/.config/opencode/tools cp plugin/freellmpool.js ~/.config/opencode/plugin/ cp tools/*.js ~/.config/opencode/tools/ ``` -------------------------------- ### Run coding agents on free models with freellmpool proxy and related commands Source: https://github.com/0xzr/freellmpool/blob/main/README.md Run a coding agent on free models by pointing it at the proxy. The proxy speaks the OpenAI API and includes an experimental Anthropic-compatible path. The commands start the proxy, print setup for Claude Code, list profiles, show the Metaswarm profile, and install the Hermes custom-endpoint config. ```bash freellmpool proxy # starts http://localhost:8080 freellmpool code claude # prints the one-line setup for Claude Code freellmpool profile list # richer installable profiles freellmpool profile show metaswarm # Tailnet-aware Metaswarm profile freellmpool profile install hermes # Hermes custom-endpoint config # (also: codex, aider, cline, continue, cursor, hermes, opencode, metaswarm) ``` -------------------------------- ### Interactive keys add examples Source: https://github.com/0xzr/freellmpool/blob/main/docs/CAPACITY.md Interactive examples of `keys add`. The command first looks for an existing local provider, then checks the synced external catalog. Typos and model names are matched with a small Levenshtein search, and the CLI asks before importing the suggested provider. ```bash freellmpool keys add Hyperbolic freellmpool keys add Hyperbolc freellmpool keys add Llama-3.3-70B-Instruct ``` -------------------------------- ### Install freellmpool metaswarm adapter Source: https://github.com/0xzr/freellmpool/blob/main/docs/promotion/reddit-metaswarm.md Commands to copy the adapter into a metaswarm project, make it executable, and install the freellmpool Python package. Assumes metaswarm is already installed and configured. ```bash mkdir -p .metaswarm/adapters cp integrations/metaswarm/freellmpool-review-adapter.sh .metaswarm/adapters/freellmpool.sh chmod +x .metaswarm/adapters/freellmpool.sh python -m pip install freellmpool ``` -------------------------------- ### Install and check capacity Source: https://github.com/0xzr/freellmpool/blob/main/docs/capacity-management.html Install the freellmpool package and check the status of your LLM providers with a target of 5 healthy providers. ```bash pip install freellmpool freellmpool capacity status --target 5 ``` -------------------------------- ### Run the init wizard Source: https://github.com/0xzr/freellmpool/blob/main/docs/INTEGRATIONS.md Detects provider keys, agent CLIs, proxy config, and Tailscale state, then prints copy-pastable setup plans without editing third-party config. Use --json for JSON output. The --agent flag targets a specific agent; --tailnet includes Tailscale state. ```bash freellmpool init --yes freellmpool init --yes --agent opencode freellmpool init --yes --agent metaswarm --tailnet freellmpool init --json ``` -------------------------------- ### Install and use freellmpool with Groq Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-groq-api.html Install freellmpool, set your Groq API key (plus any other free keys), and run commands that either pin Groq with -p groq or let the pool fail over automatically on a 429. Set FREELLMPOOL_ROUTING=fast to prefer the lowest-latency tier. ```bash pip install freellmpool export GROQ_API_KEY=... # plus any other free keys freellmpool ask -p groq "..." # pin Groq when you want its speed freellmpool ask "..." # or pool + fail over automatically FREELLMPOOL_ROUTING=fast freellmpool ask "..." # prefer the lowest-latency tier ``` -------------------------------- ### Inspect local setup with init wizard Source: https://github.com/0xzr/freellmpool/blob/main/README.md Print-only init wizard to inspect local provider keys, agent CLIs, proxy config, and Tailscale state before wiring tools. The --agent and --tailnet flags add agent-specific and Tailscale configuration. ```bash freellmpool init --yes freellmpool init --yes --agent opencode freellmpool init --yes --agent metaswarm --tailnet ``` -------------------------------- ### Install Metaswarm profile with freellmpool init, profile install, tailnet serve, and profile doctor Source: https://github.com/0xzr/freellmpool/blob/main/README.md Install the Metaswarm agent profile that mirrors the project's posture: one free/cheap worker lane through the local proxy, one larger freellmpool reviewer lane, and Codex/Opus as explicit user-owned paid escalation/final-review lanes only (never silent). ```bash freellmpool init --yes --agent metaswarm --tailnet freellmpool profile install metaswarm freellmpool tailnet serve --port 8080 freellmpool profile doctor metaswarm --dry-run ``` -------------------------------- ### Run local proxy for existing tools Source: https://github.com/0xzr/freellmpool/blob/main/docs/promotion/long-form-article.md Start the local OpenAI-compatible proxy and point existing tools at it via OPENAI_BASE_URL and OPENAI_API_KEY. The proxy listens on localhost:8080/v1 and accepts any API key. ```bash freellmpool proxy export OPENAI_BASE_URL=http://localhost:8080/v1 export OPENAI_API_KEY=anything ``` -------------------------------- ### Start freellmpool proxy and configure OpenAI-compatible environment Source: https://github.com/0xzr/freellmpool/blob/main/docs/AGENTS.md Starts the freellmpool proxy on port 8080 and sets the OpenAI-compatible base URL and API key environment variables. The API key is ignored by freellmpool. ```bash freellmpool proxy --port 8080 export OPENAI_BASE_URL=http://localhost:8080/v1 export OPENAI_API_KEY=anything # ignored by freellmpool ``` -------------------------------- ### Install and use freellmpool with Mistral Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-mistral-api.html Install freellmpool, set your Mistral API key, and use the CLI to ask questions. The first command pins the Mistral route; the second pools and fails over for general tasks. ```bash pip install freellmpool export MISTRAL_API_KEY=... # plus other free keys freellmpool ask -m mistral/mistral-small-latest "Refactor this function" < code.py freellmpool ask "..." # pool + fail over for general tasks ``` -------------------------------- ### Install freellmpool with pip Source: https://github.com/0xzr/freellmpool/blob/main/integrations/metaswarm/README.md Installs the freellmpool package so metaswarm can run it. ```sh python -m pip install freellmpool ``` -------------------------------- ### aider setup with freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/docs/AGENTS.md Configure environment variables and launch aider with the freellmpool-compatible endpoint. Set OPENAI_API_BASE to http://localhost:8080/v1, use any API key, and specify the model as openai/auto. ```bash export OPENAI_API_BASE=http://localhost:8080/v1 export OPENAI_API_KEY=anything aider --model openai/auto ``` -------------------------------- ### Install dev dependencies and run tests Source: https://github.com/0xzr/freellmpool/blob/main/README.md Install the package in editable mode with development dependencies, run the Ruff linter, and execute the test suite. This command is used for local development and CI, and it runs without network access. ```bash python -m pip install -e ".[dev]" && ruff check . && pytest ``` -------------------------------- ### freellmpool init Definition of Done commands Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md Definition of Done commands for the init wizard. The first prints an actionable setup plan; the second includes Tailnet serve and remote client setup. ```bash freellmpool init --yes --agent opencode ``` ```bash freellmpool init --yes --agent metaswarm --tailnet ``` -------------------------------- ### Install OpenCode TUI plugin Source: https://github.com/0xzr/freellmpool/blob/main/integrations/opencode-tui/README.md Installs the OpenCode TUI plugin from a local clone of the freellmpool repository. Records the plugin in ~/.config/opencode/tui.json. ```sh # from a clone of the freellmpool repo: opencode plugin -g file:/absolute/path/to/integrations/opencode-tui ``` -------------------------------- ### GET /v1/providers response Source: https://github.com/0xzr/freellmpool/blob/main/docs/ADOPTION_SPRINT_PLAN.md Example GET /v1/providers response. Only the fields shown are emitted; rpd == 0 means unknown/unmetered, making daily_limit and remaining null and the model not exhausted. Missing credentials set configured=false and status unconfigured; disabled models are omitted. ```json { "schema_version": 1, "object": "list", "data": [{ "id": "provider-id", "configured": true, "ready": true, "status": "ready", "enabled_models": 1, "ready_models": 1, "cooldown_remaining_s": 0.0, "models": [{ "id": "provider-id/model-id", "name": "model-id", "ready": true, "status": "ready", "daily_limit": 1000, "used_today": 0, "remaining": 1000 }] }] } ``` -------------------------------- ### Install and configure freellmpool proxy Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-openai-api-alternatives.html Install freellmpool via pip, set the OpenAI base URL to the local proxy, and run existing OpenAI SDK code unchanged on free models. ```bash pip install freellmpool export OPENAI_BASE_URL=http://localhost:8080/v1 # after: freellmpool proxy # your existing OpenAI SDK code now runs on free models, unchanged ``` -------------------------------- ### Run freellmpool proxy and set OpenAI-compatible environment variables Source: https://github.com/0xzr/freellmpool/blob/main/README.md Starts the local proxy server and configures environment variables for OpenAI-compatible tools. On loopback, any placeholder API key works unless FREELLMPOOL_PROXY_KEY or --api-key is set; Tailnet/LAN serving requires a real proxy bearer token by default. ```bash freellmpool proxy export OPENAI_BASE_URL=http://localhost:8080/v1 export OPENAI_API_KEY=unused ``` -------------------------------- ### Dev setup commands Source: https://github.com/0xzr/freellmpool/blob/main/CONTRIBUTING.md Sets up the development environment and runs the initial checks. The pytest command is noted to make zero network calls because provider traffic is faked. ```bash git clone https://github.com/0xzr/freellmpool cd freellmpool python -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e ".[dev]" ruff check . pytest # 0 network calls; provider traffic is faked ``` -------------------------------- ### Install command for freellmpool MCP server Source: https://github.com/0xzr/freellmpool/blob/main/docs/mcp-listings/glama-submission.md JSON configuration for installing and running the freellmpool MCP server via uvx. The command is 'uvx' with argument 'freellmpool mcp'. Use this in MCP client configuration to add the server. ```json { "command": "uvx", "args": ["freellmpool", "mcp"] } ``` -------------------------------- ### Install freellmpool with pip or pipx Source: https://github.com/0xzr/freellmpool/blob/main/README.md Installs the freellmpool package. The only dependency is httpx, and Python 3.11+ is required. Use pipx for an isolated CLI installation. ```bash pip install freellmpool # or: pipx install freellmpool ``` -------------------------------- ### Copy .env.example to .env and edit keys Source: https://github.com/0xzr/freellmpool/blob/main/docs/ACCOUNTS.md Copies the example environment file to .env so you can fill in your API keys. The .env file is gitignored by default in this repo. freellmpool reads from the environment, so you can load the file with `set -a; source .env; set +a` or a tool like direnv. ```bash cp .env.example .env # edit .env, fill in the keys you have ``` -------------------------------- ### Start the freellmpool proxy Source: https://github.com/0xzr/freellmpool/blob/main/docs/INTEGRATIONS.md Starts the gateway on port 8080, exposing an OpenAI-compatible API at http://localhost:8080/v1. On loopback, any API key is accepted; otherwise use your proxy bearer token. The model can be 'auto', 'groq', or 'groq/openai/gpt-oss-120b'. ```bash freellmpool proxy --port 8080 # Base URL: http://localhost:8080/v1 # API key: anything on loopback, or your proxy bearer token when auth is enabled # Model: auto (or "groq", or "groq/openai/gpt-oss-120b") ``` -------------------------------- ### Install metaswarm freellmpool adapter Source: https://github.com/0xzr/freellmpool/blob/main/docs/INTEGRATIONS.md Copies the metaswarm review-only adapter into the project's .metaswarm/adapters directory and makes it executable. Requires at least one strong review provider key (MISTRAL_API_KEY, NVIDIA_API_KEY, or OPENROUTER_API_KEY) before enabling; without them it fails closed with error_type: "auth_missing". ```bash mkdir -p .metaswarm/adapters cp integrations/metaswarm/freellmpool-review-adapter.sh .metaswarm/adapters/freellmpool.sh chmod +x .metaswarm/adapters/freellmpool.sh ``` -------------------------------- ### Start proxy and configure OpenCode with freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/docs/promotion/reply-bank.md Start the local proxy on port 8080, then configure OpenCode to use it as a custom OpenAI-compatible provider. The JSON config sets the model to freellmpool/auto and uses the @ai-sdk/openai-compatible npm package with baseURL http://localhost:8080/v1 and an API key from the FREELLMPOOL_PROXY_KEY environment variable. ```bash freellmpool proxy --port 8080 ``` ```json { "$schema": "https://opencode.ai/config.json", "model": "freellmpool/auto", "provider": { "freellmpool": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:8080/v1", "apiKey": "{env:FREELLMPOOL_PROXY_KEY}" }, "models": { "auto": {}, "fast": {}, "quality": {}, "fair": {} } } } } ``` -------------------------------- ### Example capacity status output Source: https://github.com/0xzr/freellmpool/blob/main/docs/CAPACITY.md Example output from 'freellmpool capacity status' showing the number of healthy providers and a recommended action. ```text LLM capacity: 3/5 healthy providers Action recommended: add 2 provider(s). ``` -------------------------------- ### Key inventory TOML example Source: https://github.com/0xzr/freellmpool/blob/main/docs/CAPACITY.md Example TOML entry for a manually created key in the key inventory. The inventory should not contain raw API key values; keep secrets in environment variables, config.toml, your shell profile, or a secret manager. ```toml [[keys]] provider = "groq" env_var = "GROQ_API_KEY" label = "personal-main" created_at = "2026-06-05" expires_at = "2026-12-31" commercial_allowed = true notes = "created manually" ``` -------------------------------- ### Install Hermes profile with freellmpool CLI Source: https://github.com/0xzr/freellmpool/blob/main/docs/INTEGRATIONS.md Installs and dry-run checks the Hermes profile (included in release 0.12.0). Hermes supports OpenAI-compatible custom endpoints; after installing, run `hermes model` and choose Custom endpoint, or inspect the print-only profile. ```bash freellmpool profile install hermes freellmpool profile doctor hermes --dry-run ``` -------------------------------- ### Install and run freellmpool CLI keyless Source: https://github.com/0xzr/freellmpool/blob/main/docs/freellmpool-vs-litellm-vs-openrouter.html Install freellmpool and run a keyless CLI query when routes are available. The comment notes that the command works without an API key when keyless routes are available. ```bash pip install freellmpool freellmpool ask "Explain the CAP theorem in one sentence." # keyless when routes are available ``` -------------------------------- ### Install and use freellmpool with Gemini Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-gemini-api.html Installs freellmpool, sets the Gemini key, and shows two usage patterns: pinning Gemini for long inputs with -p gemini, or pooling with automatic failover. Requires other free keys for pooling. ```bash pip install freellmpool export GEMINI_API_KEY=... # plus other free keys freellmpool ask -p gemini "Summarize" < long-document.txt # pin Gemini for long input freellmpool ask "..." # or pool + fail over ``` -------------------------------- ### Install Hermes Agent profile for freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/docs/run-coding-agents-on-free-models.html Install and verify the Hermes Agent profile. The dry-run shows the supported config without editing ~/.hermes/config.yaml. Alternatively, use the interactive menu to set the custom endpoint. ```bash freellmpool profile install hermes freellmpool profile doctor hermes --dry-run # Or run: hermes model → Custom endpoint → http://localhost:8080/v1 ``` -------------------------------- ### MCP client config with uvx Source: https://github.com/0xzr/freellmpool/blob/main/docs/MCP_LISTINGS.md Install block for directories that accept raw client config, using uvx to run the freellmpool package with the mcp argument. ```json { "mcpServers": { "freellmpool": { "command": "uvx", "args": ["freellmpool", "mcp"] } } } ``` -------------------------------- ### Dashboard ASCII preview Source: https://github.com/0xzr/freellmpool/blob/main/integrations/opencode-tui/README.md Example of the live dashboard rendered inside OpenCode, showing routing mode, lifetime savings, tokens served, provider race with cooldowns, latency sparkline, and last-served model. ```text ┌─ freellmpool ─────────────────────┐ │ routing quality │ │ 💸 $0.0006 saved ⚡ 128 tok/s │ │ 50 tokens served free · 13 req │ │ ── provider race ── │ │ 🥇 llm7 ██████████ 9 ⏳53s │ │ 🥈 ovh ████░░░░░░ 4 │ │ 🥉 groq █░░░░░░░░░ 1/1000 │ │ latency ███████▇▇▇▇▇ 124ms │ │ last: groq/openai/gpt-oss-120b │ └───────────────────────────────────┘ ``` -------------------------------- ### Run full release verification suite Source: https://github.com/0xzr/freellmpool/blob/main/docs/RELEASE_CHECKLIST.md Run the full release verification suite: lint, type-check, tests, coverage, security scans (bandit, pip-audit, zizmor), and a Trivy container scan. Requires the dev/security extras installed and the Docker image built; the Trivy scan uses a digest-pinned image and fails on HIGH/CRITICAL vulnerabilities. ```bash set -euo pipefail python3 -m pip install -e ".[dev,security]" ruff check . python3 -m mypy --follow-imports=skip src/freellmpool/routing_modes.py \ src/freellmpool/catalog_validation.py src/freellmpool/_version.py \ src/freellmpool/readiness.py PYTHONPATH=src python3 -m pytest PYTHONPATH=src python3 -m pytest --cov=freellmpool --cov-branch \ --cov-report=term-missing --cov-report=json:.coverage.json python3 scripts/check_coverage.py .coverage.json scripts/check-counts PYTHONPATH=src python3 scripts/validate_catalog.py python3 scripts/check_docs.py docs python3 scripts/check_assets.py PYTHONPATH=src python3 scripts/check_release_ready.py --skip-build PYTHONPATH=src python3 scripts/check_release_ready.py python3 scripts/security_exceptions.py validate python3 scripts/security_exceptions.py check-suppressions bandit --recursive src --severity-level high --confidence-level high --ignore-nosec mapfile -t ignored < <(python3 scripts/security_exceptions.py ids pip-audit) audit_args=() for advisory in "${ignored[@]}"; do audit_args+=(--ignore-vuln "$advisory"); done python3 -m pip_audit . --strict --desc=on --aliases=on "${audit_args[@]}" zizmor --strict-collection --no-ignores --no-config \ --min-severity=high --min-confidence=high . docker build --tag freellmpool:release-check . test "$(docker buildx version | awk '{print $2}')" = v0.36.1 trivy_ignore=$(mktemp) python3 scripts/security_exceptions.py ids trivy > "$trivy_ignore" trivy_scan_dir=$(mktemp -d) docker save --output "$trivy_scan_dir/freellmpool-image.tar" \ freellmpool:release-check docker run --rm \ -v "$trivy_scan_dir:/scan:ro" \ -v "$trivy_ignore:/trivyignore:ro" \ aquasec/trivy:0.72.0@sha256:cffe3f5161a47a6823fbd23d985795b3ed72a4c806da4c4df16266c02accdd6f \ image --input /scan/freellmpool-image.tar \ --exit-code 1 --severity HIGH,CRITICAL --pkg-types os,library \ --scanners vuln --ignorefile /trivyignore ``` -------------------------------- ### GET /readyz Source: https://github.com/0xzr/freellmpool/blob/main/README.md Public advisory local-capacity readiness (200 when at least one provider is ready, otherwise 503); it never live-probes an upstream. ```APIDOC ## [GET] /readyz ### Description Public advisory local-capacity readiness (200 when at least one provider is ready, otherwise 503); it never live-probes an upstream. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - **status** (string) - "ready" #### Error Response (503) - **status** (string) - "not ready" #### Response Example { "status": "ready" } ``` -------------------------------- ### Pin Cerebras with freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-cerebras-api.html Install freellmpool, set the Cerebras key, explicitly pin a Cerebras model to spend trial credit intentionally, and benchmark providers. Keep Cerebras out of automatic routing to avoid consuming the finite $5 trial unexpectedly. ```bash pip install freellmpool export CEREBRAS_API_KEY=... # plus other free keys freellmpool ask -m cerebras/gpt-oss-120b "..." # explicitly spend trial credit freellmpool benchmark # time each provider you've configured ``` -------------------------------- ### Get a second opinion with freellmpool ask Source: https://github.com/0xzr/freellmpool/blob/main/README.md Get a bounded second opinion instead of a full `tokenmax` blast. The shared panel asks a few diverse providers, keeps individual failures visible, and can append a non-fatal synthesis when you pass `--synthesize`. ```bash freellmpool ask --second-opinion --opinions 3 "is this implementation plan sound?" freellmpool ask --role second-opinion --synthesize "which release note is clearer?" ``` -------------------------------- ### Manage freellmpool profiles for OpenCode Source: https://github.com/0xzr/freellmpool/blob/main/docs/AGENTS.md Lists available profiles, shows the OpenCode profile, installs it (print-only, does not edit third-party config files), and runs a dry-run doctor check. ```bash freellmpool profile list freellmpool profile show opencode freellmpool profile install opencode freellmpool profile doctor opencode --dry-run ``` -------------------------------- ### Use freellmpool with NVIDIA free tier Source: https://github.com/0xzr/freellmpool/blob/main/docs/free-nvidia-api.html Installs freellmpool, sets the NVIDIA API key, lists NVIDIA's free models, and sends a request pinned to a specific provider/model. The -m flag uses the format provider/model, here nvidia/nvidia/nemotron-3-super-120b-a12b. ```bash pip install freellmpool export NVIDIA_API_KEY=... # plus other free keys freellmpool models -p nvidia # browse NVIDIA's free catalog freellmpool ask -m nvidia/nvidia/nemotron-3-super-120b-a12b "..." # provider/model pin ``` -------------------------------- ### MCP config with provider keys Source: https://github.com/0xzr/freellmpool/blob/main/docs/MCP.md Example MCP config that passes provider API keys through the server's environment. Replace the placeholder key values with your actual keys. ```json { "mcpServers": { "freellmpool": { "command": "freellmpool", "args": ["mcp"], "env": { "GROQ_API_KEY": "gsk_...", "CEREBRAS_API_KEY": "csk-..." } } } } ``` -------------------------------- ### Manual key checklist output Source: https://github.com/0xzr/freellmpool/blob/main/docs/CAPACITY.md Example output of `keys checklist --target 5`, listing providers that need manual key configuration to reach the desired number of healthy providers. ```text Manual key checklist to reach 5 healthy providers: - gemini: create a key manually, then set GEMINI_API_KEY - cloudflare: create a key manually, then set CLOUDFLARE_API_TOKEN ``` -------------------------------- ### Run sandboxed OpenCode on freellmpool Source: https://github.com/0xzr/freellmpool/blob/main/integrations/opencode-jail/README.md Starts the freellmpool proxy and runs the sandboxed OpenCode script in various modes: interactive TUI, headless single turn with --run, opencode serve with --serve, and containment verification with --selftest. ```sh freellmpool proxy # starts the proxy on http://127.0.0.1:8080 integrations/opencode-jail/opencode-freellmpool-jailed.sh # interactive TUI in ~/project integrations/opencode-jail/opencode-freellmpool-jailed.sh --run "…" # headless single turn integrations/opencode-jail/opencode-freellmpool-jailed.sh --serve # opencode serve (basic-auth) integrations/opencode-jail/opencode-freellmpool-jailed.sh --selftest # prove the containment, exit ``` -------------------------------- ### Set provider credentials and inspect configuration Source: https://github.com/0xzr/freellmpool/blob/main/docs/use-multiple-free-llm-apis.html Export environment variables for provider API keys (e.g., GROQ_API_KEY, CEREBRAS_API_KEY, GEMINI_API_KEY, NVIDIA_API_KEY) to enable more routes. Then use 'freellmpool providers' to show what's configured and 'freellmpool benchmark' to time each provider so routing prefers the fastest. ```bash export GROQ_API_KEY=... # plus CEREBRAS_API_KEY, GEMINI_API_KEY, NVIDIA_API_KEY, ... freellmpool providers # shows what's configured freellmpool benchmark # times each provider so routing prefers the fastest ``` -------------------------------- ### Run security checks locally Source: https://github.com/0xzr/freellmpool/blob/main/SECURITY.md Install the pinned security extra and run the same policy and scanner arguments used by CI. Includes Bandit, pip-audit, zizmor, and the supply-chain test. ```bash python3 -m pip install -e ".[dev,security]" python3 scripts/security_exceptions.py validate python3 scripts/security_exceptions.py check-suppressions bandit --recursive src --severity-level high --confidence-level high --ignore-nosec mapfile -t ignored < <(python3 scripts/security_exceptions.py ids pip-audit) audit_args=() for advisory in "${ignored[@]}"; do audit_args+=(--ignore-vuln "$advisory"); done python3 -m pip_audit . --strict --desc=on --aliases=on "${audit_args[@]}" zizmor --strict-collection --no-ignores --no-config \ --min-severity=high --min-confidence=high . pytest -q tests/test_supply_chain.py ``` -------------------------------- ### Install checksum-pinned GitHub CLI v2.98.0 Source: https://github.com/0xzr/freellmpool/blob/main/docs/RELEASE_CHECKLIST.md Download and verify the checksum-pinned GitHub CLI v2.98.0 for release and attestation operations. The distro CLI may be too old to verify immutable releases; this script extracts the pinned binary and checks that the required attestation/release verify subcommands are available. ```bash set -euo pipefail release_cli_dir=$(mktemp -d) gh_archive="$release_cli_dir/gh_2.98.0_linux_amd64.tar.gz" curl --fail --location --silent --show-error \ --output "$gh_archive" \ https://github.com/cli/cli/releases/download/v2.98.0/gh_2.98.0_linux_amd64.tar.gz printf '%s %s\n' \ 3b8ac6b30336802fc1a858d7c084e11cdf24ac1a761ca90b68022d7d729208de \ "$gh_archive" | sha256sum --check - tar --extract --gzip --file "$gh_archive" --directory "$release_cli_dir" release_gh="$release_cli_dir/gh_2.98.0_linux_amd64/bin/gh" "$release_gh" --version | grep --fixed-strings 'gh version 2.98.0' "$release_gh" attestation verify --help >/dev/null "$release_gh" release verify --help >/dev/null "$release_gh" release verify-asset --help >/dev/null ``` -------------------------------- ### Non-interactive keys add with --base-url Source: https://github.com/0xzr/freellmpool/blob/main/docs/CAPACITY.md Non-interactive example of `keys add` that creates a minimal OpenAI-compatible provider when no external match is good enough. It asks for the API base URL and a default model id; leave the model blank to autodiscover models from the OpenAI-compatible GET /models endpoint. If a key is needed, the CLI uses the key passed with --value or asks for one. ```bash freellmpool keys add Hyperbolic \ --base-url https://api.hyperbolic.xyz/v1 \ --model meta-llama/Llama-3.3-70B-Instruct \ --value "$HYPERBOLIC_API_KEY" \ --yes ``` -------------------------------- ### GET /livez and /healthz response body Source: https://github.com/0xzr/freellmpool/blob/main/docs/ADOPTION_SPRINT_PLAN.md Legacy body returned by GET /livez and GET /healthz with HTTP 200. Preserves the existing byte-for-byte JSON alias behavior. ```json {"status": "ok"} ``` -------------------------------- ### Discover and import local runtimes Source: https://github.com/0xzr/freellmpool/blob/main/README.md Discovers and imports local runtimes (LM Studio, Ollama, llama.cpp) from a fixed list of literal loopback endpoints. Discovery is read-only; import is a separate affirmative step that writes no credential and keeps imported models out of automatic routing (auto = false). Custom endpoints must be canonical literal loopback URLs such as http://127.0.0.1:1234/v1; hostnames, LAN addresses, redirects, and broad network scans are rejected. ```bash freellmpool local discover freellmpool local discover --name lm_studio freellmpool local import --name lm_studio --yes freellmpool ask --providers local_lm_studio --model "" "hello" ``` -------------------------------- ### MCP client config with freellmpool command Source: https://github.com/0xzr/freellmpool/blob/main/docs/MCP_LISTINGS.md Alternative install block after explicit pipx or pip install, using the freellmpool command directly. ```json { "mcpServers": { "freellmpool": { "command": "freellmpool", "args": ["mcp"] } } } ``` -------------------------------- ### Example secret JSON map for FREELLMPOOL_SENTINEL_KEYS_JSON Source: https://github.com/0xzr/freellmpool/blob/main/docs/CATALOG_SENTINEL.md Example JSON value for the FREELLMPOOL_SENTINEL_KEYS_JSON secret. Maps catalog environment-variable names to their values; never commit this value. ```json {"GROQ_API_KEY":"...","CLOUDFLARE_API_TOKEN":"...","CLOUDFLARE_ACCOUNT_ID":"..."} ``` -------------------------------- ### List and run freellmpool recipes Source: https://github.com/0xzr/freellmpool/blob/main/README.md List and run bundled recipes that wrap common workflows in JSON files. Recipes use the same role presets and shared panel helper as `ask` and `battle`; there is no separate routing engine. ```bash freellmpool recipe list freellmpool recipe run second-opinion "is this launch plan clear?" --synthesize freellmpool recipe run pr-review --input patch.diff freellmpool recipe run repo-summary --path 'src/freellmpool/*.py' freellmpool recipe run metaswarm-worker-review --input worker.md --validation-output-file validation.txt ``` -------------------------------- ### Use freellmpool CLI commands for ask, tokenmax, stats, and badges Source: https://github.com/0xzr/freellmpool/blob/main/README.md Core CLI commands: ask for a prompt, pipe input for commit messages, tokenmax for maximum-effort fan-out, providers/models for configuration, stats for persistent lifetime totals, and badge to generate SVG badges. tokenmax adds a synthesized verdict by default unless --no-synthesize is passed; the MCP tool returns model answers for the agent to synthesize. stats survives restarts and upgrades; badge --summary produces a larger card with tokens, requests, estimated savings, and provider mix. ```bash freellmpool ask "Write a haiku about sqlite" git diff | freellmpool ask "Write a commit message for this" freellmpool tokenmax "Hardest question you've got" # 🌈 blast models, print answers, optional synthesis freellmpool providers # which providers are configured freellmpool models # cataloged provider/model ids freellmpool stats # lifetime tokens served free + estimated cost avoided freellmpool badge -o badge.svg # a shareable SVG badge of that total freellmpool badge --summary -o summary.svg # a larger usage summary card ``` -------------------------------- ### Milestone 1 demo commands Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md Commands for the first-run demo in Milestone 1, covering init with agent and tailnet flags, tailnet serve, profile doctor, and a wise-mode ask with a role. ```bash freellmpool init --agent metaswarm --tailnet freellmpool tailnet serve freellmpool profile doctor metaswarm FREELLMPOOL_MODE=wise freellmpool ask --role cheap "summarize this" ``` -------------------------------- ### GET /summary.svg Source: https://github.com/0xzr/freellmpool/blob/main/README.md Local operations surface. ```APIDOC ## [GET] /summary.svg ### Description Local operations surface. ### Method GET ### Endpoint /summary.svg ### Response #### Success Response (200) - **image/svg+xml** (string) - SVG summary #### Response Example (SVG content) ``` -------------------------------- ### GET /badge.svg Source: https://github.com/0xzr/freellmpool/blob/main/README.md Local operations surface. ```APIDOC ## [GET] /badge.svg ### Description Local operations surface. ### Method GET ### Endpoint /badge.svg ### Response #### Success Response (200) - **image/svg+xml** (string) - SVG badge #### Response Example (SVG content) ``` -------------------------------- ### GET /status Source: https://github.com/0xzr/freellmpool/blob/main/README.md Local operations surface. ```APIDOC ## [GET] /status ### Description Local operations surface. ### Method GET ### Endpoint /status ### Response #### Success Response (200) - **html** (string) - Status UI #### Response Example (HTML content) ``` -------------------------------- ### GET /dashboard Source: https://github.com/0xzr/freellmpool/blob/main/README.md Local operations surface. ```APIDOC ## [GET] /dashboard ### Description Local operations surface. ### Method GET ### Endpoint /dashboard ### Response #### Success Response (200) - **html** (string) - Dashboard UI #### Response Example (HTML content) ``` -------------------------------- ### Run init wizard tests Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md Verification command for the init wizard work unit. Runs the new and existing tests. ```bash PYTHONPATH=src python3 -m pytest tests/test_init_wizard.py tests/test_cli.py tests/test_agents.py ``` -------------------------------- ### Run tests for MCP UX tools Source: https://github.com/0xzr/freellmpool/blob/main/docs/PRODUCT_UX_TAILNET_PLAN.md Verifies the implementation of WU-011 by running the relevant test files. ```bash PYTHONPATH=src python3 -m pytest tests/test_mcp.py tests/test_roles.py tests/test_recipes.py tests/test_battle.py ``` ```bash PYTHONPATH=src python3 -m pytest tests/test_mcp_listings.py ```