Custom model endpoints

Every endpoint override is optional and off by default. Unset means the runtime's own vendor API, which is what an agent uses unless told otherwise.

A claude agent

Two modes, and they are alternatives — agents set refuses the second one. Azure AI Foundry is not the generic mode with a different URL; it authenticates on its own vars.

mode	ledger key	renders	credential (secret store)
custom gateway	endpoint_base_url	ANTHROPIC_BASE_URL	ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN
Azure AI Foundry	foundry_resource or foundry_base_url	ANTHROPIC_FOUNDRY_RESOURCE / ANTHROPIC_FOUNDRY_BASE_URL	ANTHROPIC_FOUNDRY_API_KEY or ANTHROPIC_FOUNDRY_AUTH_TOKEN (an Entra bearer token)

agentctl secret set ANTHROPIC_FOUNDRY_API_KEY --agent inventx     # value from stdin — NEVER in the ledger
agentctl agents set inventx foundry_resource my-resource          # or: foundry_base_url https://my-resource.services.ai.azure.com/anthropic
agentctl apply inventx                                            # renders the vars into ~/.config/agentctl/agent.env
agentctl agents set inventx foundry_resource ""                   # back to the direct API — apply REMOVES the var

agents add --runtime claude --api-key <k> --provider foundry stores the key under ANTHROPIC_FOUNDRY_API_KEY at creation time; the endpoint itself is still agents set plus apply. Only the non-secret half lives in the ledger, a plaintext git repo: there is no ledger key for a key or a token, and apply warns when an agent declares an endpoint the store has no credential for.

A pi agent

endpoint_base_url means one narrow thing here: keep the provider the agent already names (model.provider → PI_PROVIDER), move its URL. It renders into pi-agent.env as PI_BASE_URL, and the bridge registers it as a base-URL override on that provider. The model catalog, the per-model costs and API-key discovery all stay pi's own. The credential stays the provider's usual var: openai → OPENAI_API_KEY, openrouter → OPENROUTER_API_KEY.

agentctl secret set OPENAI_API_KEY --agent sami       # value from stdin — NEVER in the ledger
agentctl agents set sami endpoint_base_url https://gw.corp/openai/v1
agentctl apply sami                                   # renders PI_BASE_URL into ~/.config/agentctl/pi-agent.env
agentctl agents set sami endpoint_base_url ""         # back to the provider's own endpoint — apply REMOVES the var

declared on a pi agent	result
foundry_resource / foundry_base_url	claude-only: warned at apply, agent left on its provider's endpoint
endpoint_base_url with no provider pinned	warned at apply: no named provider to override, so the URL is inert