feat(providers): support request-scoped provider credentials for existing sandboxes

[rohancmr]

Problem Statement

Some platforms create OpenShell sandboxes for interactive AI-agent workflows where credentials are resolved at request time.

The sandbox may be created first, and then a user request arrives with identity or credential material that is specific to that request. The platform may then exchange the user identity or request headers for short-lived service credentials, such as:

• GitLab tokens
• Jira or Confluence tokens
• MaaS service tokens
• MCP server credentials
• SSO JWT-derived service credentials
• workflow-specific headers or secrets

These credentials are scoped to one user, one request, one conversation, or one session. They should not become permanent sandbox credentials, and they should not be shared with other users or later requests.

Today, providers are attached to a sandbox at sandbox creation time. That works when credentials are known before CreateSandbox, but it does not fit request-time credential flows.

OpenShell should support attaching temporary provider credentials to an existing sandbox after it has been created.

Proposed Design

Add support for request-scoped or session-scoped provider credentials on existing sandboxes.

OpenShell should allow a trusted caller to attach temporary provider credentials to a sandbox after CreateSandbox.

Conceptual flow:

1. Platform receives a user request.
2. Platform creates an OpenShell sandbox.
3. Platform resolves user-specific credentials.
4. Platform attaches those credentials to the existing sandbox for a specific request/session.
5. Sandbox supervisor uses those credentials through the existing provider/proxy injection model.
6. Credentials expire or are removed when the request/session ends.

Possible API shape:

sandbox_id: sandbox-abc123
session_id: conversation-456
ttl_seconds: 3600
providers:
  - name: gitlab-user-token
    provider_type: gitlab
    credentials:
      GITLAB_TOKEN:
        source:
          type: inlineSecret
          value: "<redacted>"

Or with a Secret-backed source:

sandbox_id: sandbox-abc123
session_id: conversation-456
ttl_seconds: 3600
providers:
  - name: gitlab-user-token
    provider_type: gitlab
    credentials:
      GITLAB_TOKEN:
        source:
          type: kubernetesSecret
          namespace: openshell-system
          name: user-session-credentials
          key: gitlab-token

The exact API shape can be decided by OpenShell maintainers. The important requirement is that provider credentials can be attached after sandbox creation and scoped to a bounded request/session lifetime.

Required Behavior

OpenShell should support:

• Attaching provider credentials to an existing sandbox after CreateSandbox.
• Scoping credentials to a request, conversation, or session identifier.
• Enforcing a server-side TTL for those credentials.
• Removing or invalidating credentials when the request/session ends.
• Preventing credentials from one request/session from being visible to another.
• Auditing which caller attached which provider credentials to which sandbox/session.
• Supporting credentials sourced from inline secret material, Kubernetes Secrets, existing provider records, or future brokered credential flows.

Security Requirements

• Request-scoped credentials must fail closed if they are missing, expired, or unauthorized.
• Credentials must not appear in logs, events, list responses, or audit output.
• A caller should only be able to attach credentials that OpenShell policy allows.
• Credentials from one user/request/session must not be reused by another.
• TTL must be enforced server-side.
• On session end, credentials should be deleted or made unusable.
• The child agent process should continue to receive placeholders where possible, with the supervisor/provider layer performing controlled credential injection.

Why This Is Needed

Many interactive agent systems resolve credentials only after receiving a user request.

For example, a platform may receive a request with a user SSO identity, exchange that identity for short-lived GitLab or Jira credentials, and then run an agent task inside an OpenShell sandbox.

Those credentials are not always known before sandbox creation. They may also be valid only for a short period and only for that user's request.

Without this feature, platforms must choose one of the following workarounds:

• create all provider credentials before sandbox creation,
• store short-lived user credentials as normal OpenShell provider records,
• write raw secrets into a .env file inside the sandbox,
• pass credentials directly as environment variables,
• or keep a separate router-side credential injection system outside OpenShell.

Those options are harder to secure and harder to operate than using OpenShell's existing supervisor/provider credential injection model with request-scoped credential lifecycle support.

Example Use Case

A user starts an AI coding session that needs GitLab and Jira access.

The platform receives the request, authenticates the user, and exchanges the user identity for short-lived service tokens.

The platform creates an OpenShell sandbox and then attaches those credentials to the sandbox for the current conversation:

For sandbox sandbox-abc123 and session conversation-456,
make these GitLab and Jira provider credentials available only for this session.
Expire them after 1 hour or when the session is released.

The OpenShell supervisor should then use those credentials through the existing provider/proxy credential injection model.

Alternatives Considered

Attach all providers at sandbox creation time

This works only when credentials are known before CreateSandbox. It does not fit request-time identity exchange or per-request credentials.

Store user credentials as permanent OpenShell provider records

This is not ideal for short-lived, user-specific credentials. It increases credential lifecycle burden and can leave stale credentials behind.

Write a .env file into the sandbox

This works for simple runtimes, but it exposes raw credential values directly to the child process. OpenShell's supervisor/provider injection model is safer and should be used instead.

Pass credentials directly as environment variables

This has similar problems to .env: the child process receives raw credential values directly, and cleanup becomes harder.

Agent Investigation

I reviewed OpenShell's current provider and sandbox flow:

• Providers are attached to a sandbox through SandboxSpec.providers.
• Provider credentials are resolved by the gateway and delivered to the sandbox supervisor through the provider environment flow.
• The sandbox supervisor already supports credential injection through provider placeholders and proxy rewriting.
• The missing capability is not the injection mechanism. The missing capability is credential lifecycle and scope: credentials need to be attachable after sandbox creation and bounded to a specific request/session.

Checklist

• I have searched existing issues for related provider and credential lifecycle requests.
• This is a design proposal, not only a request to build a feature.

[drew]

It's already possible today to attach providers to existing sandboxes, https://docs.nvidia.com/openshell/latest/sandboxes/providers-v2#attach-and-detach-providers. Can you expand on what's currently missing?