# OpenAI-compatible providers

Connect Ollama, Strata or your own inference API with host-local configuration, explicit authentication and manual model selection.

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.

**Check your installed release**

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.

```text
BernOps app → existing agent connection → coding-agent host
                                        → your inference API → your model
```

Use 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](/docs/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. `--context` and `--max-output` describe 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:

1. Install your operator's approved private bootstrap. From the Git root you want to authorize, sign in to the intended BernOps target:

   ```bash
   bernops auth login --target cloud
   ```

   For local development, use `bernops auth login --local` instead. Complete the real browser approval. This step grants platform access only; it does not start an agent.
2. Add a connection using one of the examples below, through its `provider check` step. Skip `service stop` if no service is installed yet, and skip the final `service start`: `agent setup` below installs/starts the service. Replace the example connection ID, model and limits with your own.
3. With the connection already configured, enroll the host, authorize the current Git root and configure its service:

   ```bash
   bernops agent setup --target cloud --authorize-host \
     --provider home-ollama --repo "$PWD"
   ```

   Use `--target local` for the same local target selected at login. Substitute `local-strata` or your own connection ID for `home-ollama`. Approve the host as the same BernOps account. No Codex login or `--login-provider` is needed for a configured custom connection.
4. Wait for `ready`, then check `bernops service status` and `bernops repo list`. The service must be verified and connected, and the repository available. Proceed to [select the model in the app](#select-in-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:

```bash
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 start
```

The 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:

```bash
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 start
```

Replace 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:

```bash
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 4096
```

The 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:

```bash
bernops provider edit office-strata --compat-json \
  '{"supportsDeveloperRole":false,"supportsReasoningEffort":false}'
bernops provider check office-strata
bernops service start
```

The 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`.

```bash
bernops provider models home-ollama
```

This 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:

```bash
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

```bash
bernops provider list
bernops provider status home-ollama
bernops provider check home-ollama
bernops provider check home-ollama --infer
```

- `list`, `inspect` and `status` do not reveal keys. `credentials_ready` means the selected auth mode is configured, including explicit `none`; it does not mean a server accepted the key. A keyless connection can be ready while `authenticated` is false.
- Plain `check` queries `/models`, returning reachability, a timestamp, `verified: false` and `inference_performed: false`. A missing `/models` endpoint does not prevent manually configured inference.
- **`check --infer` sends 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

1. After starting the agent, check `bernops service status`: expect a verified release and `connection_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.
2. 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**.
3. Type a simple message such as `test — reply with OK` and click **Send prompt**. Wait for a response from that selected model. Merely seeing the model in the picker or a `ready` badge does not prove delivery.
4. 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:** `localhost` means 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.pem` adds connection-specific trust with certificate verification enabled. Use a regular non-symlink file owned by the user or root, not group/world writable. `--system-ca` restores normal system trust on edit; never disable certificate verification.
- **Non-loopback HTTP:** requires explicit `--allow-http` and can expose prompts and credentials in cleartext. Prefer HTTPS or an encrypted tunnel. `--no-allow-http` clears 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:

```bash
bernops service stop
bernops provider remove home-ollama
bernops service start
```

Only 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:

```text
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 help
```

Add/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](/docs/openai-compatible-providers.md) and through the [LLM documentation index](/docs/llms.txt). Section IDs remain stable for focused retrieval:

```bash
bernops docs search "Ollama"
bernops docs search "Strata"
bernops docs get openai-compatible-providers#ollama
bernops docs get openai-compatible-providers#networking
```

Search 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.
