feat(providers): add Oracle Cloud Infrastructure Generative AI provider profile

Add an example oci-genai inference profile for OCI Generative AI through its
OpenAI-compatible endpoint. The profile injects a compartment-scoped
Generative AI API key as a bearer token only at the regional OCI inference
hosts and only under /openai/v1, so the sandbox never holds the key and the
key cannot reach any other OCI surface.

Register the profile id in the telemetry provider bucket and the provider
profile listing test, add a row to the inference provider table, and add a
docs page covering the OCI authentication transports and how each maps to
OpenShell today, the policy-before-key IAM ordering, least-privilege policy
statements, key rotation, regions and realms, and troubleshooting.

Follows the deepinfra precedent: example YAML, telemetry bucket, overview
row, docs page. No new mechanism.

Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>

Author: fede-kamel

crates/openshell-core/src/telemetry.rs

@@ -203,6 +203,7 @@ pub enum ProviderProfile {
     Github,
     Gitlab,
     Nvidia,
+    OciGenai,
     Openai,
     Opencode,
     Outlook,
@@ -221,6 +222,7 @@ impl ProviderProfile {
             Self::Github => "github",
             Self::Gitlab => "gitlab",
             Self::Nvidia => "nvidia",
+            Self::OciGenai => "oci-genai",
             Self::Openai => "openai",
             Self::Opencode => "opencode",
             Self::Outlook => "outlook",
@@ -239,6 +241,7 @@ impl ProviderProfile {
             "github" | "gh" => Self::Github,
             "gitlab" | "glab" => Self::Gitlab,
             "nvidia" => Self::Nvidia,
+            "oci-genai" | "oci" => Self::OciGenai,
             "openai" => Self::Openai,
             "opencode" => Self::Opencode,
             "outlook" => Self::Outlook,

crates/openshell-server/src/grpc/provider.rs

@@ -5122,6 +5122,7 @@ fn telemetry_provider_profile(provider_type: &str) -> TelemetryProviderProfile {
         Some("deepinfra") => TelemetryProviderProfile::Deepinfra,
         Some("github") => TelemetryProviderProfile::Github,
         Some("nvidia") => TelemetryProviderProfile::Nvidia,
+        Some("oci-genai") => TelemetryProviderProfile::OciGenai,
         Some("openai") => TelemetryProviderProfile::Openai,
         _ => TelemetryProviderProfile::Custom,
     }
@@ -6301,6 +6302,7 @@ mod tests {
                 "google-cloud",
                 "google-vertex-ai",
                 "nvidia",
+                "oci-genai",
                 "openai",
                 "openrouter",
                 "pypi"

docs/how-it-works/providers/oracle.mdx

@@ -0,0 +1,193 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Oracle"
+sidebar-title: "Oracle"
+description: "Reach OCI Generative AI from OpenShell sandboxes with a compartment-scoped Generative AI API key that the proxy injects only at the OCI inference endpoint."
+keywords: "Generative AI, Oracle Cloud, OCI, OCI Generative AI, API Key, OpenAI-compatible, Credentials, Sandbox"
+---
+
+The `oci-genai` provider gives sandboxes governed access to
+[OCI Generative AI](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
+through its OpenAI-compatible endpoint. The sandbox receives a placeholder in
+`OCI_GENAI_API_KEY`; the sandbox proxy swaps in the real Generative AI API key
+only on requests to the regional OCI inference host, and only under
+`/openai/v1`. The agent never holds the key, and the key is useless anywhere
+else.
+
+## OCI Authentication Transports
+
+OCI clients authenticate in several ways. This table shows how each maps to
+OpenShell today.
+
+| OCI transport | Typical client | OpenShell support |
+|---|---|---|
+| Generative AI API key (`sk-...`, bearer token on `/openai/v1`) | OpenAI SDKs, curl, any OpenAI-compatible agent | Supported by the `oci-genai` profile on this page. |
+| API key request signing (user principal, RSA HTTP `Signature` header) | OCI CLI, OCI SDKs, `langchain-oci` `auth_type=API_KEY` | Not yet. Needs proxy-side OCI request signing, similar to [AWS SigV4](/how-it-works/providers/aws). |
+| Security token (session from `oci session authenticate`) | OCI CLI, `langchain-oci` `auth_type=SECURITY_TOKEN` | Not yet. Same signing gap, plus an `external` refresh of the token file. |
+| Instance principal, resource principal, OKE workload identity | Compute, Functions, OKE workloads | Not yet. Same signing gap, plus a gateway refresh strategy that federates the principal. |
+
+Use the Generative AI API key transport for inference. For the native
+`/20231130` Generative AI API, Object Storage, or any other OCI service, wait
+for proxy-side request signing or front the service with a bridge that signs in
+its own workload and exposes a bearer-authenticated endpoint to the sandbox.
+
+## Prerequisites
+
+- An OCI tenancy with Generative AI available in your region. Regional
+  availability and the model list served through the OpenAI-compatible
+  endpoint are in the
+  [OCI Generative AI documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm).
+- The [OCI CLI](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm)
+  configured with an identity that can manage policies and Generative AI API
+  keys in the target compartment.
+- A running OpenShell gateway (see [Quick Start](/about/quickstart)).
+
+## Create the IAM Policy First
+
+A Generative AI API key is an IAM principal of type `generativeaiapikey`. It
+only works after a policy admits that principal type. Create the policy before
+the key: a key created before its policy can stay unauthorized well after the
+policy lands, and OCI returns the same `401` for an unknown key and an
+unauthorized one, so the response will not tell you which it is.
+
+Scope the policy to one compartment and the one principal type. Do not grant
+`manage` when `use` is enough:
+
+```shell
+COMPARTMENT_ID=ocid1.compartment.oc1..example
+
+oci iam policy create \
+  --compartment-id "$COMPARTMENT_ID" \
+  --name openshell-genai-api-keys \
+  --description "Generative AI API keys in this compartment may call Generative AI" \
+  --statements "[\"allow any-user to use generative-ai-family in compartment id $COMPARTMENT_ID where ALL {request.principal.type='generativeaiapikey'}\"]"
+```
+
+To pin the policy to a single key after it exists, add
+`request.principal.id='<api-key-ocid>'` to the `where` clause.
+
+## Create the Generative AI API Key
+
+Create the key in the same compartment the policy covers, in the region you
+will call. Set an expiry; the secret is returned once, in the create response,
+and cannot be retrieved later:
+
+```shell
+REGION=us-chicago-1
+
+oci generative-ai api-key create \
+  --compartment-id "$COMPARTMENT_ID" \
+  --region "$REGION" \
+  --display-name openshell-agents \
+  --key-details '[{"keyName":"primary","timeExpiry":"2027-01-01T00:00:00Z"}]'
+```
+
+Copy the `sk-...` secret from the response into a password manager or a
+gateway credential store. Rotate it with
+`oci generative-ai api-key renew` and disable it with
+`oci generative-ai api-key set-api-key-state`; both take effect without
+touching sandboxes because the gateway, not the sandbox, holds the value.
+
+## Import the Profile and Create a Provider
+
+Import the `oci-genai` profile; a gateway serves only the profiles you imported:
+
+```shell
+openshell provider profile import --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/oci-genai.yaml --global
+```
+
+Create a provider from the key. Read the secret from your password manager or
+an environment variable rather than typing it into the shell history:
+
+```shell
+openshell provider create \
+  --name my-oci-genai \
+  --type oci-genai \
+  --credential OCI_GENAI_API_KEY="$OCI_GENAI_API_KEY"
+```
+
+The key is compartment-scoped, so no `opc-compartment-id` header or
+compartment configuration is needed.
+
+## Use from a Sandbox
+
+Create a sandbox with the provider attached and call the endpoint. The proxy
+resolves the `OCI_GENAI_API_KEY` placeholder only for the OCI host declared by
+the profile:
+
+```shell
+openshell sandbox create --name oci-demo --provider my-oci-genai
+
+openshell sandbox exec --name oci-demo -- sh -c '
+  curl -sS --compressed \
+    https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1/chat/completions \
+    -H "Authorization: Bearer $OCI_GENAI_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "{\"model\":\"meta.llama-3.3-70b-instruct\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK\"}]}"
+'
+```
+
+Any OpenAI SDK works unchanged. Point it at the regional base URL and pass the
+placeholder as the API key:
+
+```shell
+export OPENAI_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1
+export OPENAI_API_KEY="$OCI_GENAI_API_KEY"
+```
+
+Model identifiers use the OCI form, such as `meta.llama-3.3-70b-instruct`,
+`openai.gpt-oss-120b`, or `xai.grok-4`. The Chat Completions and Responses
+APIs are served under `/openai/v1`. Not every model behind the native API is
+reachable through the OpenAI-compatible endpoint with an API key; check the
+OCI documentation for the current list.
+
+The profile ships `curl` as its only client binary. Add your interpreter or
+agent CLI to `binaries` in a copy of the profile before importing it, or the
+credential is never injected for that process.
+
+## Regions and Realms
+
+The profile's host pattern `inference.generativeai.*.oci.oraclecloud.com`
+matches every region in the commercial realm; `*` matches exactly one DNS
+label, which is the region identifier. Tenancies in other realms, such as
+government realms, use a different domain. Copy the profile and add an endpoint
+entry with that realm's host before importing.
+
+Dedicated AI cluster endpoints use the same regional host, so the profile
+covers them as well.
+
+## Security Notes
+
+- **Least privilege on both sides.** The IAM policy admits only
+  `generativeaiapikey` principals in one compartment, and the profile grants
+  only `/openai/v1` on the regional inference host. A leaked placeholder cannot
+  be used from outside the sandbox, and the real key cannot reach any other
+  OCI service.
+- **Expiry and rotation.** Set `timeExpiry` on every key. Rotate with
+  `oci generative-ai api-key renew` and update the provider with
+  `openshell provider update`; running sandboxes pick up the new value through
+  the normal placeholder path.
+- **Auditing.** Calls made with the key are attributed to the key's OCID in
+  OCI Audit. Use one key per agent fleet or per workspace so audit entries map
+  to an OpenShell provider.
+- **No compartment header.** Because the key is compartment-scoped, sandboxes
+  never learn a compartment OCID. Keep it that way; do not add
+  `opc-compartment-id` to the endpoint rules.
+
+## Troubleshooting
+
+- **`401` on every request.** Either the key is unknown or it is not yet
+  authorized. Confirm the policy exists in the key's compartment and was
+  created before the key. If the key was created first, mint a new key rather
+  than waiting.
+- **Binary garbage instead of JSON.** The endpoint compresses responses. Pass
+  `--compressed` to curl, or let your SDK negotiate encoding.
+- **`GET /openai/v1/models` returns `404`.** Model listing is not served on
+  this endpoint. Do not use it as a health check; send a small chat request
+  instead.
+- **Request denied by the sandbox proxy.** Check that the calling binary is in
+  the profile's `binaries` list and that the request path starts with
+  `/openai/v1`. Use `openshell sandbox logs` to see the denial.
+- **Native API calls fail.** `/20231130` endpoints require OCI request
+  signing, which this profile does not provide. See the transport table above.

docs/how-it-works/providers/overview.mdx

@@ -470,6 +470,7 @@ selects the model and request timeout.
 | Anthropic | `anthropic` | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` |
 | NVIDIA API Catalog | `nvidia` | `https://integrate.api.nvidia.com/v1` | `NVIDIA_API_KEY` |
 | DeepInfra | `deepinfra` | `https://api.deepinfra.com/v1/openai` | `DEEPINFRA_API_KEY` |
+| Oracle Cloud Infrastructure Generative AI | `oci-genai` | `https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1` | `OCI_GENAI_API_KEY` |
 | Google Vertex AI | `google-vertex-ai` | Region and model dependent | `GOOGLE_VERTEX_AI_TOKEN` or `GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN` |
 
 An OpenAI-compatible protocol does not make the `openai` profile safe for an

docs/index.yml

@@ -55,6 +55,8 @@ navigation:
       path: how-it-works/providers/aws.mdx
     - page: "Google"
       path: how-it-works/providers/google.mdx
+    - page: "Oracle"
+      path: how-it-works/providers/oracle.mdx
   - section: "Policies"
     slug: policies
     contents:

providers/oci-genai.yaml

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Example provider profile. OpenShell does not load it; import it explicitly:
+#   openshell provider profile lint   -f providers/oci-genai.yaml
+#   openshell provider profile import -f providers/oci-genai.yaml --global
+#
+# Copy and edit this file rather than importing it unchanged. `binaries` is the
+# least-privilege control that decides which processes may reach the endpoints
+# below, so it has to name the paths in *your* image.
+#
+# Client binaries:   curl. Add the interpreter or agent CLI that calls the
+#                    OpenAI-compatible endpoint (python, node, ...) before
+#                    relying on binary-scoped attribution for this profile.
+# Reference layout:  any image with curl or an OpenAI SDK. Point the SDK at
+#                    https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1
+#                    and pass OCI_GENAI_API_KEY as the API key; the sandbox
+#                    proxy resolves the placeholder only at the hosts below.
+# Credential scope:  one OCI Generative AI API key (sk-...), created with
+#                    `oci generative-ai api-key create`. The key is scoped to
+#                    the compartment it was created in, so requests do not
+#                    need an opc-compartment-id header. Create the IAM policy
+#                    that admits `request.principal.type='generativeaiapikey'`
+#                    BEFORE creating the key; a key minted before its policy
+#                    can stay unauthorized for a long time.
+# Endpoint access:   the regional OCI Generative AI inference hosts in the
+#                    commercial realm (oraclecloud.com), TLS terminated, L7
+#                    enforced, limited to the OpenAI-compatible /openai/v1
+#                    surface. Generative AI API keys are only valid there;
+#                    the native /20231130 API requires OCI request signing,
+#                    which this profile does not grant. Other realms use their
+#                    realm domain: add a matching endpoint entry.
+# Smoke test:        openshell sandbox create --provider <name> -- \
+#                      curl -sS --compressed \
+#                        https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1/chat/completions \
+#                        -H "Authorization: Bearer $OCI_GENAI_API_KEY" \
+#                        -H 'Content-Type: application/json' \
+#                        -d '{"model":"meta.llama-3.3-70b-instruct","messages":[{"role":"user","content":"Reply with OK"}]}'
+
+id: oci-genai
+display_name: Oracle Cloud Infrastructure Generative AI
+description: OCI Generative AI inference through the OpenAI-compatible endpoint with a compartment-scoped Generative AI API key
+category: inference
+inference_capable: true
+credentials:
+  - name: api_key
+    description: OCI Generative AI API key (compartment-scoped, sent as a bearer token)
+    env_vars: [OCI_GENAI_API_KEY]
+    required: true
+    auth_style: bearer
+    header_name: authorization
+discovery:
+  credentials: [api_key]
+endpoints:
+  # `*` matches exactly one DNS label, which is the region identifier, for
+  # example us-chicago-1, eu-frankfurt-1, or ap-osaka-1.
+  - host: "inference.generativeai.*.oci.oraclecloud.com"
+    port: 443
+    protocol: rest
+    enforcement: enforce
+    rules:
+      - allow: { method: POST, path: "/openai/v1/**" }
+      - allow: { method: GET, path: "/openai/v1/**" }
+      - allow: { method: DELETE, path: "/openai/v1/**" }
+binaries: [/usr/bin/curl, /usr/local/bin/curl]