Per-Conversation Secrets

Source: per-conversation-secrets/ OpenHands lets users store secrets in their vault for long-lived credentials. This example covers a different need: injecting a secret that belongs to one conversation only — for example, a customer’s OAuth token, a temporary CI credential, or a per-tenant API key.

Two Patterns

Pattern A — Secrets as Bash Environment Variables

Pass secrets at conversation-start time. The agent can then use $MY_KEY in any bash command it runs.

requests.post(
    f"{CLOUD}/api/v1/app-conversations",
    headers=cloud_headers,
    json={
        "secrets": {
            "DATABASE_URL": "postgres://user:pass@host/db",
            "API_TOKEN": "tok_abc123",
        },
        "initial_message": {
            "role": "user",
            "content": [{"type": "text", "text": "Run the migration using $DATABASE_URL"}],
        },
    },
)

The secrets are available as environment variables in every bash command the agent runs, but are never stored in the conversation transcript.

Pattern B — Secrets as MCP Server Auth

The same secrets field also drives ${VARIABLE} expansion inside a plugin’s .mcp.json. When you ship a plugin with a placeholder like ${MCP_SECRET_TOKEN} in its MCP server config, OpenHands fills it in from the conversation’s secrets before dialing that MCP server.

.mcp.json inside the plugin

{
  "mcpServers": {
    "my-api": {
      "url": "${MCP_SERVER_URL}/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer ${MCP_SECRET_TOKEN}"
      }
    }
  }
}

At conversation-start time, pass matching secrets:

requests.post(
    f"{CLOUD}/api/v1/app-conversations",
    headers=cloud_headers,
    json={
        "plugins": [{"source": "github:your-org/your-plugins", "ref": "main", "repo_path": "my-plugin"}],
        "secrets": {
            "MCP_SERVER_URL": "https://api.example.com",
            "MCP_SECRET_TOKEN": customer_oauth_token,
        },
        "initial_message": ...,
    },
)

OpenHands expands the placeholders before connecting to the MCP server. The token is never visible in the conversation transcript.

What Is a Plugin?

A plugin is a directory in a git repo with three files:

my-plugin/
├── .mcp.json            # MCP server config with ${...} placeholders
├── .plugin/plugin.json  # Manifest: name, version, author
└── SKILL.md             # Documentation the agent reads at startup

This example ships a working test-plugin/ in the repo — a ready-made plugin whose .mcp.json uses ${MCP_SERVER_URL} and ${MCP_SECRET_TOKEN}.

Quickstart

export OH_API_KEY="your-api-key"
pip install requests

# Pattern A: secrets as bash env vars
python test_secrets_at_start.py

# Pattern B: secrets expand into plugin MCP config
python test_mcp_secrets_at_start.py

Mid-Conversation Injection (Legacy)

You can also inject secrets into a running conversation via the agent server’s /secrets endpoint. This is less common — most use cases are better served by passing secrets at conversation-start. See test_secrets.py for the implementation.

Sandboxes

Conversations

Plugins & Skills

Hooks

Two Patterns

Pattern A — Secrets as Bash Environment Variables

Pattern B — Secrets as MCP Server Auth

What Is a Plugin?

Quickstart

Mid-Conversation Injection (Legacy)

See Also

​Two Patterns

​Pattern A — Secrets as Bash Environment Variables

​Pattern B — Secrets as MCP Server Auth

​What Is a Plugin?

​Quickstart

​Mid-Conversation Injection (Legacy)

​See Also

Two Patterns

Pattern A — Secrets as Bash Environment Variables

Pattern B — Secrets as MCP Server Auth

What Is a Plugin?

Quickstart

Mid-Conversation Injection (Legacy)

See Also