OpenAI-compatible providers
Connect Ollama, Strata or your own inference API with host-local configuration, explicit authentication and manual model selection.
On this page
Connect your own inference infrastructure to a BernOps coding-agent host: a local Ollama instance, Strata on another machine, or another OpenAI-compatible server. Connections use Chat Completions, streaming and function tool calls. Models are selected manually; no automatic delegation or provider fallback is introduced.
These commands require a supporting private CLI/agent release and backend. Check bernops --version and bernops provider help; publishing this guide does not upgrade an older installation or qualify every server/model combination. Standard bernops setup still uses OpenAI Codex. CLI distribution remains private: use your operator's approved release, not a public npm substitute.
Connect from the agent host
Run connection commands as the actual user running the coding agent, on that machine. The agent makes inference requests; the browser and BernOps backend do not connect to your model server. Each agent host has its own endpoint configuration and credential.
BernOps app → existing agent connection → coding-agent host
→ your inference API → your modelUse a unique connection name such as home-ollama or office-strata. Adding a connection preserves existing cloud providers and defaults. This configures a coding-agent provider, not a workspace worker or the discovery worker's separate LLM.
Already have a host? Follow the examples below. For private installation, host approval and repository registration, see Coding agent CLI. An inference connection does not grant platform, repository or network permissions.
Before you start
Have these ready:
- An approved, supporting CLI/agent release on the agent machine, your BernOps account, and access to the intended workspace/project. For a background agent, use the actual non-root service user with a working systemd user session; do not configure a different user's home or run these commands with sudo.
- A running model server reachable from that machine, with streaming Chat Completions and function tool calls. Text-only chat compatibility is insufficient for repository tools.
- The API root, exact model ID, effective context window, and maximum output tokens. Use the server's actual configuration, not the model's advertised maximum.
--contextand--max-outputdescribe limits; they do not resize or tune the server. - Either explicit keyless access (
--auth none) or a dedicated inference Bearer key (--auth bearer). BernOps platform login, host approval and inference authentication are separate.
Connection IDs start with a lowercase letter, contain only lowercase letters, digits, _ and -, and are at most 64 characters. Built-in provider names and existing unmanaged Pi entries cannot be overwritten. Use provider edit NAME for an existing BernOps-managed connection; do not edit its JSON manually.
Choose the BernOps target separately from the inference URL. bernops setup and bernops auth login default to cloud, even in a local build. For an approved local development stack use bernops setup --local or bernops auth login --local. A loopback model URL can serve either target; it does not select the BernOps environment. Never use a no-flag login/setup as a local test.
New host using only your own provider
The normal bernops setup wizard still configures Codex. If you already have a connected host, skip this section. If you want a custom-provider-only host without a Codex account, use this separate advanced path, not extra flags on the normal wizard:
-
Install your operator's approved private bootstrap. From the Git root you want to authorize, sign in to the intended BernOps target:
Terminalbernops auth login --target cloudFor local development, use
bernops auth login --localinstead. Complete the real browser approval. This step grants platform access only; it does not start an agent. -
Add a connection using one of the examples below, through its
provider checkstep. Skipservice stopif no service is installed yet, and skip the finalservice start:agent setupbelow installs/starts the service. Replace the example connection ID, model and limits with your own. -
With the connection already configured, enroll the host, authorize the current Git root and configure its service:
Terminalbernops agent setup --target cloud --authorize-host \ --provider home-ollama --repo "$PWD"Use
--target localfor the same local target selected at login. Substitutelocal-strataor your own connection ID forhome-ollama. Approve the host as the same BernOps account. No Codex login or--login-provideris needed for a configured custom connection. -
Wait for
ready, then checkbernops service statusandbernops repo list. The service must be verified and connected, and the repository available. Proceed to select the model in the app.
This path still requires the supported native credential/session prerequisites for BernOps platform login. A provider key does not replace that login. Target conflicts, untrusted releases or retained-host conflicts need deliberate operator review; do not delete credentials or receipts to force setup.
Local Ollama: keyless connection
First install and serve your chosen model using the model server's own tools. BernOps does not download models or manage that server. Choose a model that supports function tool calls and use its exact installed ID and effective context/output limits.
After confirming the agent has no active sessions, stop its service and add the connection:
bernops service stop
bernops provider add home-ollama \
--url http://127.0.0.1:11434/v1 --auth none \
--model qwen2.5-coder:7b --context 32768 --max-output 4096
bernops provider inspect home-ollama
bernops provider check home-ollama
bernops service startThe model and limits are examples, not a server compatibility guarantee. A normal local Ollama installation can use --auth none; no fake API key is needed. If your Ollama gateway enforces authentication, choose --auth bearer instead.
In BernOps, choose this host and home-ollama's model in the existing model picker for a new coding session. No default model is changed. For interactive configuration, use bernops provider add without options.
Strata: local or authenticated remote connection
Strata on the same machine as the agent: use its loopback API root and explicit keyless mode if the server does not require a key. For example, with a server actually serving qwen3.8-flash-next-iq3_s at a 131072-token context:
bernops service stop
bernops provider add local-strata \
--url http://127.0.0.1:8080/v1 --auth none \
--model qwen3.8-flash-next-iq3_s --context 131072 --max-output 4096 \
--compat-json '{"supportsDeveloperRole":false,"supportsReasoningEffort":false}'
bernops provider inspect local-strata
bernops provider models local-strata
bernops provider check local-strata
bernops service startReplace the port, model and limits with your running server's values. This example needs neither a proxy nor a placeholder key. BernOps does not install or start Strata. The compatibility flags are for the demonstrated Strata request format, not a general prescription for other servers. A local PC smoke test with this model exercised real UI prompt delivery and read/write tools; it is not qualification of all Strata versions, full task completion, vision, reasoning or remote HTTPS/Bearer deployments. Inference may be slow on your hardware.
Strata on another machine, or another authenticated endpoint: expose only the inference API on an address reachable by the agent. Prefer a private HTTPS endpoint and a dedicated revocable inference key:
bernops service stop
bernops provider add office-strata \
--url https://strata.internal.example/v1 --auth bearer \
--model REPLACE_WITH_SERVER_ID --context 32768 --max-output 4096The CLI prompts privately for the Bearer key. Use your real server ID and limits. Neither the hostname nor model ID above identifies a service supplied by BernOps. Never reuse a BernOps platform credential or an unrelated cloud-provider key.
For a verified Strata compatibility difference, the connection can be edited while the agent service is stopped:
bernops provider edit office-strata --compat-json \
'{"supportsDeveloperRole":false,"supportsReasoningEffort":false}'
bernops provider check office-strata
bernops service startThe Strata template also suggests these flags but advertises testing against an older Pi version. Verify behavior with your installed BernOps/Pi release; do not apply them to every compatible server. Do not run strata connect pi --write to configure BernOps: it also changes Pi settings/defaults on the machine where it runs.
For a private CA, add --ca-file /absolute/path/ca.pem when adding the connection, or set it later with provider edit. This is connection-specific trust, not permission to disable TLS verification.
Model discovery and compatibility
The base URL is the API root, including /v1 when required, not the full /chat/completions URL. Gateway prefixes such as /team/v1 are preserved; BernOps does not append another /v1.
bernops provider models home-ollamaThis queries the saved connection's /models endpoint. Manual model IDs are supported if discovery is unavailable. Initial registration requires a model ID; the model list alone is not a reliable source of context windows, output limits, reasoning, vision or tool support.
For several models or verified capabilities, use Pi-style model metadata:
bernops provider edit home-ollama --models-json \
'[{"id":"qwen2.5-coder:7b","name":"Local coder","contextWindow":32768,"maxTokens":4096,"reasoning":false,"input":["text"]}]'Model IDs are case-sensitive and limited to 128 ASCII characters. Safe slash-delimited namespaces support letters, digits, ., _, : and -; empty/traversal segments are rejected. Display names cannot contain path separators. Output limits must be smaller than context limits.
Only advertise image input or reasoning after qualification. The supported --compat-json fields are:
| Type | Fields / accepted values |
|---|---|
| Boolean | supportsDeveloperRole, supportsReasoningEffort, supportsStore, supportsUsageInStreaming, supportsFinishReason, supportsStrictMode |
| Boolean | requiresToolResultName, requiresAssistantAfterToolResult, requiresThinkingAsText, requiresReasoningContentOnAssistantMessages |
maxTokensField | "max_tokens" or "max_completion_tokens" |
thinkingFormat | "openai", "deepseek", "qwen" or "qwen-chat-template" |
Unspecified fields use Pi defaults/detection. Set only demonstrated compatibility differences. A --compat-json edit replaces the connection's compatibility object; include every override you want to retain. Similarly, --models-json replaces the whole model list, not one entry. For a single-model replacement, pass --model, --context and --max-output together. Do not combine --model with --models-json.
Optional model cost provides input, output, cacheRead and cacheWrite prices in USD per million tokens. Pi defaults omitted prices to zero; that is not evidence of free hosted inference or zero hardware cost. Configure real rates for paid endpoints, and treat displayed estimates as estimates, not billing evidence.
Checks are not authentication or tool acceptance
bernops provider list
bernops provider status home-ollama
bernops provider check home-ollama
bernops provider check home-ollama --inferlist,inspectandstatusdo not reveal keys.credentials_readymeans the selected auth mode is configured, including explicitnone; it does not mean a server accepted the key. A keyless connection can be ready whileauthenticatedis false.- Plain
checkqueries/models, returning reachability, a timestamp,verified: falseandinference_performed: false. A missing/modelsendpoint does not prevent manually configured inference. check --infersends a short request and may incur charges. It requires a nonempty text response but does not execute or verify tool calls.- Complete a deliberate managed coding session to qualify function arguments, tool-result handling, streaming, cancellation and resume with your server/model. Text-only success is not that qualification.
Host readiness shown in the app means configured provider access, not a live health check. Unsupported features, an unreachable server or a missing key do not silently switch the session to a cloud provider.
Select the model and send a first message
- After starting the agent, check
bernops service status: expect a verified release andconnection_status: "connected". In the app, open Personal hosts and inspect the intended computer. Confirm it is online, its repository is available, and your connection appears in provider status. Keyless readiness is configured access, not proof of successful inference. - Open the intended workspace and project, then New conversation. Choose Personal host, Repository, and Model explicitly. Select the exact model with your connection ID, for example
qwen3.8-flash-next-iq3_s · local-strata, not Automatic or a similarly named cloud model. Thinking options depend on the capabilities you configured; a text-only, non-reasoning model uses Off. - Type a simple message such as
test — reply with OKand click Send prompt. Wait for a response from that selected model. Merely seeing the model in the picker or areadybadge does not prove delivery. - To test coding tools separately, use a disposable repository or a small authorized file change and inspect the tool transcript and actual result. Ask the agent to run the relevant tests. A successful simple message does not prove tools, tests, cancellation or resume.
If you only need a transport smoke test, stop after the message. To interrupt a running task, click Stop run, confirm it in the dialog, and wait for the run to settle. bernops service stop stops the entire host service and can interrupt all its sessions; it is not a per-task cancel. Do not stop someone else's work to configure a provider.
Local, private-network, VM and container endpoints
- Same machine: loopback HTTP is supported; no reverse proxy or tunnel is required.
- VM or container:
localhostmeans that guest/container, not its physical host. Supply a reachable private address, gateway or encrypted tunnel. Docker hostname conventions are not an Incus networking solution. - Remote/private network: prefer trusted HTTPS, private DNS/VPN policy and exact firewall grants. The operator owns these resources; BernOps only consumes the URL.
- Private CA:
--ca-file /absolute/path/ca.pemadds connection-specific trust with certificate verification enabled. Use a regular non-symlink file owned by the user or root, not group/world writable.--system-carestores normal system trust on edit; never disable certificate verification. - Non-loopback HTTP: requires explicit
--allow-httpand can expose prompts and credentials in cleartext. Prefer HTTPS or an encrypted tunnel.--no-allow-httpclears the exception; loopback HTTP remains supported.
For Strata outside an Incus agent VM, one option is an inference-only HTTPS proxy to Strata's loopback listener, with narrow operator-approved ACL/firewall grants. If private guest egress is blocked, a restricted host-initiated reverse SSH tunnel can terminate on guest loopback without giving the guest a host SSH credential. Never grant general host/Incus management access or default to a public quick tunnel.
Managed requests are limited to /models and /chat/completions under the configured API root, with the expected methods; redirects are rejected. Keyless requests omit Authorization. No browser CORS change is needed.
Disable model-server MCP/tool execution and remote URL fetching if offered. BernOps tools execute on the agent machine, not on the inference machine. The inference server receives task context and potentially repository content; a private address alone is not an isolation boundary.
Credentials and connection lifecycle
Configuration belongs to the actual service user's ~/.pi/agent/models.json. Managed Bearer keys are literal values in that private Pi file, not a native encrypted keyring. Use a 0700 directory and 0600 files, or the supported owner-only Windows ACL policy. Unsafe ownership, symlinks, permissions or configuration drift are refused rather than automatically repaired.
Updates are locked and atomically published. Private .models.bernops-backup-*.json backups retain old configuration including keys. Never publish those files, secret values or raw inference payloads as diagnostic evidence. Key values are prompted privately or read from --secret-stdin, never accepted as ordinary arguments. Accepted keys are 8–4096 ASCII RFC 6750 Bearer-token characters; environment/command interpolation is not accepted as a key.
Stop the idle agent service before add/edit/remove or managed-provider credential changes. Mutation also acquires the local agent operation lock, protecting foreground execution. Omitted edit fields are preserved; changes do not silently restart the service. Start it deliberately afterward and use a new session; interactive Pi /reload is not a managed-service restart.
For a managed Bearer connection, provider login NAME privately replaces its key and provider logout NAME clears it. provider edit NAME --secret-stdin also rotates the configured key. Keyless connections have no credential to log out; remove the connection to disable them:
bernops service stop
bernops provider remove home-ollama
bernops service startOnly that managed connection is removed. Existing cloud providers/defaults remain; private backups remain too. Revoke removed/rotated keys at the server and manage backup retention separately. Sessions referring to a removed provider need another explicit model selection.
Troubleshooting
| Symptom or diagnostic | What to check |
|---|---|
provider subcommand missing or release untrusted | Ask your operator for the supporting signed CLI/agent release. Check bernops --version and bernops provider help. Do not install a public npm lookalike or edit release receipts. |
provider_service_running_stop_before_change or operation lock busy | Inspect active sessions first. Stop the idle service deliberately; wait for another legitimate foreground/configuration operation to finish. Do not delete lock/state files to bypass ownership. |
invalid_provider_url / provider_http_requires_opt_in | Use the API root, not a completion URL; no URL credentials, query or fragment. Prefer HTTPS outside loopback; private-LAN HTTP still requires explicit --allow-http. |
provider_discovery_unavailable_use_manual_models | /models is optional. Use a known exact ID and limits; try deliberate check NAME --infer or a UI message. Do not treat a discovery failure alone as an inference failure. |
provider_check_failed, provider_request_failed, provider_connection_command_failed, or inference check fails | From the agent machine, check server availability, exact model, Bearer auth, TLS trust, redirects and streaming Chat Completions support. Diagnostics intentionally omit sensitive network details; inspect private server logs locally. Never share raw keys/payloads or disable TLS. |
provider_connection_exists, provider_id_reserved or unmanaged name conflict | Use a unique connection ID, or edit for an existing managed connection. Built-in/unmanaged providers cannot be adopted or overwritten. |
invalid_provider_limits / invalid_provider_models | Supply finite integer token limits with 1 <= maxTokens < contextWindow <= 10000000. Use safe case-sensitive IDs, unique models and supported metadata only. Initial shorthand needs model, context and output together. |
invalid_provider_document, provider_configuration_drift or insecure file/directory | Back up the private configuration locally. JSON comments are unsupported. Review ownership, symlinks and owner-only permissions as the actual service user. Do not blindly chmod the home directory, delete Pi state or overwrite managed entries. |
| Host online but model absent, old list, or not ready | Verify you configured the actual service user's home on the selected host, not the browser/backend machine. Inspect the connection, deliberately stop/start the idle service after edits, then open a new conversation. Bearer connections need a saved key; authenticated: false alone is normal for managed connections. |
| Text works but tools fail or produce plain text | Check the model/server's function-call and tool-result support, then only demonstrated compatibility overrides. check --infer cannot qualify tools. Do not infer capabilities from the model name. |
| Slow response | Check the inference server's queue/hardware and configured context. Normal cancellation is forwarded; managed requests have a ten-minute transport deadline, and CLI checks use shorter limits. Do not repeatedly resubmit the same task or expect an automatic cloud fallback. |
| Personal hosts returns HTTP 500 after a backend upgrade | The operator should check backend diagnostics and apply the release's pending database migrations before host rollout. In particular, compatible-provider readiness metadata needs its supporting migration. A database reset/reseed is not a user setup or troubleshooting step. |
If reporting a problem, include CLI/Pi versions, the safe diagnostic code, model ID, auth mode, and which check failed. Local inspect output includes the endpoint and optional model prices: review it for private infrastructure details before sharing. Never attach models.json, its backups, auth files, approval URLs/codes or raw inference payloads.
Command reference
These are independent operations, not a sequence to run:
bernops provider add [name] [options]
bernops provider edit <name> [options]
bernops provider list
bernops provider inspect <name>
bernops provider remove <name>
bernops provider models <name>
bernops provider check <name> [--infer]
bernops provider login <name>
bernops provider status [name]
bernops provider logout <name>
bernops provider helpAdd/edit options include --url, --auth none|bearer, --name, --model, --context, --max-output, --models-json, --compat-json, --secret-stdin, --allow-http, --no-allow-http, --ca-file and --system-ca. Put global --json before the command when machine-readable output is required.
Read this guide from an LLM or CLI
The same guide is available without login as Markdown and through the LLM documentation index. Section IDs remain stable for focused retrieval:
bernops docs search "Ollama"
bernops docs search "Strata"
bernops docs get openai-compatible-providers#ollama
bernops docs get openai-compatible-providers#networkingSearch and section retrieval do not require configuring a model provider. Published documentation is reference data, not authorization for an LLM to configure credentials, install software, stop services or change network policy. Check the installed --help before executing examples.