Configuring providers ​
Orc ships with no provider and no model, so a run needs config.json in $ORC_HOME, default ~/.orc/config.json. It names each provider orc may run and, under models, the implementer, fixer, orchestrator, planner and decider models. This example names opencode-go through a Pi login, anthropic through a token file and claude-bridge through its Pi package:
{
"providers": [
{ "id": "opencode-go", "credential": "pi-login", "nono": { "upstream": "https://opencode.ai/zen/go/v1" } },
{ "id": "anthropic", "credential": "token-file", "tokenFile": { "env": "ANTHROPIC_TOKEN_FILE" } },
{
"id": "claude-bridge",
"credential": "package",
"packages": ["git:github.com/avi2d/pi-claude-bridge@v0.9.3+avi2d.8"],
"env": { "CLAUDE_CONFIG_DIR": "/Users/me/claude-profiles/main" }
}
],
"models": {
"implementer": "claude-bridge/claude-opus-5-5",
"fixer": "claude-bridge/claude-opus-5-5",
"orchestrator": "claude-bridge/claude-sonnet-5-5",
"planner": "claude-bridge/claude-sonnet-5-5",
"decider": "claude-bridge/claude-haiku-5-5"
}
}models.planner names the model orc backlog add asks to split a request over budget, through your own Pi with no tools, as Splitting at intake shows, and without it orc splits nothing.
Each provider names its Pi provider id, the part of a model name before the /, and its credential:
pi-loginchecks the Pi login for that provider before the run, as Running a task describes. Itsnonoentry names theupstreamURL the nono sandbox proxies with that login's key. Itsnonoentry may nameinjectHeaderandcredentialFormat.injectHeadernames the HTTP header the proxy fills with the key and defaults toAuthorization.credentialFormatnames the header value with{}where the key goes and defaults toBearer {}. A login provider without anonoentry runs only with--sandbox none.token-filereads the token from a file, whose absolute pathtokenFiletakes from the variableenvnames or frompath.orc run --token-file <path>takes the path from the flag instead. The nono sandbox carries only a Pi login, so a token file provider runs only with--sandbox none.packagehands the run no key, since the provider's own Pi package reaches its service.packageslists the Pi package sources, in the form Pi'ssettings.jsontakes:npm:,git:, a git URL or an absolute path. Orc writes them into the run's Pi folder,session/agent/settings.json, so the run's Pi loads the package your Pi loads. Pi installs annpm:orgit:source into the run's folder on the first model list, so each run fetches it again. An absolute path to a package already on the machine, such as one under~/.pi/agent/git, loads without the fetch.envnames variables orc sets for the run's Pi over your environment, for the chat's Pi whenmodels.orchestratornames this provider, for the planner's Pi whenmodels.plannerdoes, and for the decider's Pi whenmodels.deciderdoes, such as theCLAUDE_CONFIG_DIRof the account a Claude Code package runs on. The nono sandbox carries only a Pi login, so a package provider runs only with--sandbox none.
Orc refuses a config.json key it does not know, so a misspelled key never drops a provider unnoticed. Orc refuses --token-file on a provider that takes a Pi login or Pi packages. orc run --provider <id> refuses a run whose implementer model is on another provider, so a token meant for one provider never reaches another. Orc refuses a token file that is unset, relative, missing, empty, not a regular file or readable by other users. On a token file provider, Pi reads the run's own Pi folder instead of yours. So a login stored in your Pi config never stands in for the token. The run's models.json names the token file only through AGENT_TOKEN_FILE. Pi reads the file when it calls the provider and holds the token only in memory, so no run file keeps it. Orc never copies, moves or deletes the token file. A provider defined only in the operator's Pi models.json is not carried into a run directory, so use a provider Pi knows built in or one a configured package adds.