Skip to content

providers.md

Latest commit

 

History

History
73 lines (46 loc) · 5.17 KB

providers.md

File metadata and controls

73 lines (46 loc) · 5.17 KB

AI Providers

The Providers page lets you choose which LLM backend powers EvoNexus, configure its credentials, and test the connection — all from the dashboard. It lives under System → Providers in the sidebar and requires the config:manage permission.

EvoNexus uses Anthropic's claude CLI by default. To run on any other backend (OpenRouter, OpenAI, Gemini, AWS Bedrock, Google Vertex AI, Codex Auth), it switches to OpenClaude — a drop-in binary that speaks the same CLI protocol but dispatches to the provider of your choice via environment variables.

Supported Providers

Provider Binary Notes
Anthropic (default) claude Native Anthropic auth, no extra config
OpenRouter openclaude 200+ models via one API — Claude, GPT, Gemini, Llama, etc.
OpenAI openclaude GPT-4o, GPT-4.1, o3 via OpenAI API
Google Gemini openclaude Gemini 2.5 Pro/Flash via Google AI
Codex Auth openclaude Reuses Codex CLI's OAuth session to access OpenAI models
AWS Bedrock openclaude Claude via AWS Bedrock
Google Vertex AI openclaude Claude via GCP Vertex AI

Install OpenClaude (one-time)

If you plan to use any non-Anthropic provider, install OpenClaude globally:

npm install -g @gitlawb/openclaude

The Providers page shows a banner at the top indicating whether claude and openclaude are installed and in $PATH. If openclaude is missing, the banner shows the install command.

Activating a Provider

  1. Open System → Providers in the sidebar
  2. Click Configure on the provider you want to use
  3. Fill in the required fields (API key, base URL, model, region — depending on provider). Secrets are masked in the form and in every API response; placeholders like sk-... guide the format
  4. Click Save & Activate

The active provider is stored in config/providers.json. Both the terminal-server and the ADW runner re-read this file on every session spawn, so switching takes effect immediately — no restart needed.

A green "Active" badge marks the currently selected provider. Every other provider can still be configured and tested without affecting the active one.

Testing a Provider

Each provider card has a Test button that runs <binary> --version with the configured env vars merged into the environment, then reports success or failure inline. This is a sanity check — it verifies that the binary is installed, in $PATH, and that the env var injection works. It does not validate that your API key actually authenticates against the remote service (use the terminal after activating for that).

Security: Allowlists and Secret Masking

Both the Python runner (ADWs/runner.py) and the JS terminal bridge (dashboard/terminal-server/src/claude-bridge.js) enforce two allowlists when reading config/providers.json:

  • CLI allowlist — only claude and openclaude are accepted as spawn targets. Any other value falls back to claude.
  • Env var allowlist — only the 13 variables listed in env-variables.md are injected. Anything else is silently dropped.

The REST API that backs the Providers page masks secrets (*_KEY, *_SECRET, *_TOKEN) as first6****last4 on every response. When you open the config modal, the form starts empty for those fields — type a new value to replace, or leave empty to keep the current one. Values containing **** are treated as masked placeholders and skipped on save (so a round-trip through the UI doesn't accidentally overwrite a real secret with the mask string).

The backend also rejects any env var value containing shell metacharacters (;, &, |, backtick, $, newlines) — defense in depth against injection if someone points EvoNexus at a compromised providers.json.

Logout Warning

When you switch away from Anthropic to any other provider, OpenClaude inherits your Anthropic Claude Code login state. To avoid confusion, run /logout inside Claude Code once after activating a non-Anthropic provider if you were previously logged in. The dashboard surfaces this warning on any provider marked requires_logout.

Where It's Stored

  • config/providers.json — active provider + per-provider CLI + env vars (gitignored, contains secrets)
  • config/providers.example.json — template copied on first boot if no real file exists (checked into git)
  • .env — unchanged by this feature. AI provider env vars live in providers.json, not .env

Configuring at Install Time

The interactive setup wizard (make setup) asks which provider to use as step 3. If you pick anything other than Anthropic, it checks whether OpenClaude is installed, offers to install it, then prompts for the provider-specific keys and saves them to config/providers.json. You can re-run the wizard or use the dashboard to change providers later.

Related