# Choose And Recover An Oysterun Provider This page helps you choose a provider for a Route C Session, confirm that the provider is authenticated and ready, and understand what the provider can see during normal use. Use it before starting or resuming a Session, or when a provider login or readiness warning blocks the chat. ## Before You Start Start from **Session Setup** for the Session you are creating or resuming. You need access to the project folder you want the provider to work in, the provider account you intend to use, and permission to complete provider login from the machine terminal when Oysterun asks for it. Provider login is separate from the Oysterun dashboard password. Do not give a provider dashboard credentials, dashboard bearer tokens, raw Host profiles, or other Host administration secrets. ## Start By Selecting A Provider 1. Open **Session Setup** from the new Session flow or from the Session you are resuming. 2. Find the **Provider** control. 3. Choose the provider you want to run, such as **Claude** or **Codex**. 4. Review the provider-specific controls that stay visible with that choice, including **Model**, reasoning or approval options, and any readiness warning. 5. If the model list looks stale, use the model selector's refresh control for the selected provider. The current public UI intentionally fixes Claude Permission Mode and Codex Approval Style rather than offering broader values. Capability selection and Allowed Paths are also disabled; installed Oysterun capabilities are available by default. These accepted fixed controls are not provider-readiness errors. For Codex reasoning effort, do not use `auto`. The current [Codex configuration reference](https://developers.openai.com/codex/config-reference) defines `minimal`, `low`, `medium`, `high`, and `xhigh`, with support depending on the selected model. Oysterun must derive the selectable values from its current model/catalog contract rather than preserving a stale hard-coded list. Success checkpoint: the selected provider name remains visible in Session Setup, and the exact selected model and reasoning value agree across Session Setup, Session Profile, product CLI readback, and provider launch. Oysterun does not silently switch provider, model, or reasoning. A stale unsupported value must block creation and ask the user to select a current supported value. ## Check Authentication If the provider is already signed in, Session Setup can continue to the normal start or resume path. Provider model catalogs are Host-owned status data. The Host refreshes the Claude and Codex catalogs in the background by default on a fixed 24h provider-level window. `OYSTERUN_PROVIDER_MODEL_REFRESH_BACKGROUND_ENABLE=false` disables only that background timer for proof or served-host readiness; manual refresh remains available. Refresh scheduling is based on provider `refreshed_at` / last-attempt status in `params.json`. `params.refresh.next_refresh_at` may be emitted as a diagnostic, but it is not scheduling authority. The Session Setup model selector and the Claude/Codex Model rows in Host Preferences expose manual refresh controls. All three controls call the same Host refresh endpoint and consume the same provider catalog; Host Preferences does not maintain a second model or reasoning-effort option list. Session Setup refreshes its currently selected provider, while each Host Preferences button refreshes its named provider. One successful refresh replaces that provider's complete model catalog, including each model's supported and default reasoning-effort values, then resynchronizes the visible Model and Reasoning Effort controls on both surfaces. Codex obtains these fields from app-server model discovery. Claude obtains the model list from ACP `configOptions`, switches the ephemeral discovery Session across each returned model to read that model's `effort` options, and restores the original discovery model before exit; ACP `default` is represented as Oysterun `auto`. At runtime, a non-`auto` Claude effort is applied with ACP `session/set_config_option` after the model selection and before `session.ready`; `auto` leaves the provider default unchanged. The ready Session retains the exact acknowledged model/effort receipt. Oysterun never represents ACP effort as a Claude CLI flag. Existing selections survive only while the refreshed catalog still supports them. A Host with only one provider configured must skip the missing/unavailable provider before spawning any child runtime. `/providers` remains the catalog read source and `config.json` saved defaults are not silently changed by model refresh. If a refreshed Host Preferences value is no longer supported, the UI selects a valid model/effort pair and marks the Host Preferences draft as changed; the Owner must still choose **Save** before that replacement becomes the default for new Session Setup drafts. A model identifier returned by the current provider catalog remains exact when saved and when the Session launches; Host config normalization must not silently replace a provider-discovered identifier with a static fallback. Save and launch both fail closed when the identifier is not in the current provider catalog. If provider login is missing during live chat, Oysterun shows: ```text Provider login is required before this session can continue. ``` Follow the visible recovery copy. It tells you to sign in from the machine terminal or to use **Open Terminal** when a remote terminal is available. For Codex, run `codex /login`. For Claude, run `claude /login`. After provider login is complete, use **Restart session** to resume the chat. Host Preferences intentionally has no Claude authentication card or **Connect Claude** action. Authentication belongs to the provider CLI. A normal Session is expected to use an already authenticated provider; when it is not, the Session chat must show the login-required message and terminal recovery command above. Success checkpoint: after recovery, the same Session can continue. Oysterun must not ask the provider to use dashboard credentials, and provider login must not be bypassed with a dashboard token. ## Check Readiness Before Starting Readiness means that the chat shell and the selected provider runtime are both prepared. Package availability alone is not enough. Before you start or resume: 1. Confirm the selected provider and model still match your intent. 2. Read any visible **Session Setup error**, trust warning, or startup warning. 3. Start or resume the Session only after the provider choice and visible readiness state match what you expect. Success checkpoint: a successful start opens the chat for the selected provider. If Oysterun cannot satisfy provider startup or chat binding requirements, it shows a visible Session Setup error before creating history for a new live Session. ## Understand What The Provider Can See The selected provider can receive the Session work it is asked to perform and the project folder selected for that Session. Oysterun keeps Host administration and dashboard-only operations outside provider runtime authority. Provider-visible items can include: - user prompts sent to the Session; - project files inside the selected allowed workspace; - provider-specific model, reasoning, sandbox, and approval settings; - redacted output from packaged Oysterun product commands when those commands are available to the provider; and - provider-relative skill or prompt-file references inserted into the composer. Provider-visible items do not include dashboard bearer tokens, raw dashboard profiles, raw provider credentials, direct Matrix facade calls, broad Host administration, or provider skill install and update operations as general chat capabilities. Expected result: the provider sees only the bounded Session work and allowed workspace context needed for the selected provider run. ## Use Skill And Trust Controls Safely Oysterun can install its packaged skill set for supported providers. The visible controls are narrow: - **Session Setup** owns the launch-time install checkbox. - **Session Profile** owns **Install/Update Oysterun Skills** for the selected live Session's folder and provider. - Session Profile asks for confirmation before overwriting an existing marker-owned Oysterun skill set. - Host Preferences does not expose provider skill install controls. Some providers also require workspace trust for the selected project folder. Session Setup may show a trust preview such as `trusted`, `needs_trust_write`, or `trust_write_failed`. The preview is read-only. The actual provider trust write is attempted only when you start or resume a Session. Success checkpoint: provider skill installation and provider trust are shown as bounded provider-specific controls. They do not grant the provider dashboard admin access, and trust warnings remain visible when they matter. ## Recover Safely If provider authentication fails, complete the provider login command shown by Oysterun and then use **Restart session**. Do not paste dashboard credentials or Host tokens into the provider terminal. If the model list is stale or empty, refresh the selected provider's model list from Session Setup. If it still does not load, choose another available model for that provider or stop and collect the visible readiness warning. If startup fails before a Session is created, follow the **Session Setup error** instead of looking for an empty chat shell. If startup fails after a Session is already open, keep the Session open and use the visible recovery action, such as **Restart session**, only after the provider login or readiness problem has been resolved.