Debug inference clients that use an attached provider and its native endpoint, including hosted APIs and host-local Ollama, vLLM, SGLang, TRT-LLM, LM Studio, or NIM. Use for provider attachment, endpoint policy, credential substitution, topology, and migration from the removed managed inference endpoint. Trigger keywords - debug inference, managed inference endpoint, local inference, ollama, lm studio, vllm, sglang, trtllm, NIM, inference failing, model server unreachable, credential_endpoint_mismatch, host.openshell.internal.
92%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Diagnose inference as ordinary provider-authorized network traffic. OpenShell no longer supplies a managed inference route, rewrites request shapes, or selects a model. The application calls the provider's native endpoint and owns its base URL, model, request format, and timeout.
Use installed openshell --help output as the authority for command syntax.
Refer to the published provider management guide
and provider profile guide
for current behavior.
openshell status
openshell gateway info
openshell sandbox get <sandbox>For a host-local model server, host.openshell.internal identifies the machine
running the gateway. It does not identify the operator's laptop when the gateway
is remote. A server listening only on 127.0.0.1 may also be unreachable from a
container; bind it to an address reachable from the gateway runtime.
openshell provider get <provider>
openshell profile export <profile-id> -o yamlCheck that the profile:
For a custom or self-hosted OpenAI-compatible endpoint, import an endpoint-bearing profile. A base URL stored only in provider configuration does not authorize a new endpoint.
openshell profile lint -f ./provider-profile.yaml
openshell profile import -f ./provider-profile.yaml
openshell provider create --name <provider> --type <profile-id>Add the required --credential KEY or --credential KEY=VALUE arguments shown
by the profile. Never broaden endpoint policy merely to silence a credential
binding error.
openshell sandbox provider list <sandbox>
openshell sandbox provider attach <sandbox> <provider> --wait --timeout 30Save the change's receipt_id and use openshell sandbox provider status <sandbox> <provider> --receipt <receipt-id> --wait --timeout 30 to check when it takes effect. Success confirms that the sandbox applied the credentials, policy, and environment for new processes. If the result is pending, failed, withheld, or superseded, inspect its reason before launching the client.
Launch the client after the attachment wait succeeds so it receives the updated environment:
openshell sandbox exec <sandbox> -- <client-command>After updating an ordinary static provider, wait for that change and launch a
new client. An existing process keeps its environment reference; readiness does
not guarantee that it uses the replacement value. Retained revisions and
stable_placeholder: true have different resolution behavior, as described in
Runtime Limitations.
Diagnose managed-refresh credentials according to their own lifecycle.
Keep credentials and issued references out of diagnostic output. Acknowledged detach revokes future credential resolution and removes the reference from future process environments. Requests already forwarded may still finish:
openshell sandbox provider detach <sandbox> <provider> --wait --timeout 30The application must use the real upstream contract:
Probe the exact endpoint from a newly launched sandbox process. Start with a non-secret discovery endpoint when the provider offers one, then send a minimal inference request using the provider's documented API shape.
| Symptom | Likely cause | Fix |
|---|---|---|
credential_placeholder_in_request_body | A body reference is invalid/revoked, or classification metadata is unavailable | Check the controlled denial reason; remove the reference from conversation history or restore provider access. Do not enable body credential rewriting or bypass flags to send tool output. Unknown literals and valid issued placeholders pass unchanged, including the model provider’s own placeholder. Header resolution does not enable body rewriting. |
| A retired managed endpoint fails DNS resolution | Client still uses the removed managed endpoint | Configure the provider's native base URL and attach an endpoint-bearing provider profile |
| Direct request is denied | Missing attachment, endpoint policy, HTTP rule, or binary authorization | Inspect the attached provider profile and sandbox effective policy |
credential_endpoint_mismatch | Credential profile does not authorize the request recipient | Correct the host/port/path or import a narrowly scoped profile for the intended endpoint |
credential_placement_mismatch | A placeholder is outside declared placement or the metadata-free Authorization default | Match the profile placement. For other headers, query parameters, or path slots, update the imported profile and upgrade the gateway before the supervisor; explicit body/WebSocket rewrite policies remain supported. |
request_authority_mismatch | HTTP authority differs from the CONNECT destination | Use the same host and effective port in both authorities |
| Credential variable is absent | Provider was not attached when this process launched, profiles collide on a key, or credential delivery failed | Check provider readiness, then launch a new process; resolve duplicate keys explicitly. Missing placement metadata or an older component alone does not withhold credentials. |
| Upstream rejects the model or body | Client relied on removed model/request rewriting | Configure the real model and provider-native request format in the application |
127.0.0.1 works on the host but not in the sandbox | Loopback refers to different runtime | Use host.openshell.internal or another gateway-reachable endpoint and profile |
| Host-local request times out | Server bind address, gateway topology, or host firewall blocks container-to-host traffic | Verify the listener and permit only the required gateway network path and port |
For Ollama, LM Studio, vLLM, SGLang, TRT-LLM, and local NIM deployments:
host.openshell.internal and the actual port.Report:
NVIDIA/OpenShell
2e5589b
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.