Secret Stubs

Runta can authenticate your agent’s request without exposing real credentials to your agents.

Store a Secret

To ensure maximum security, utilize interactive input methods that prevent these values from being recorded in your shell history.

export OPENAI_API_KEY=sk... # Set the source environment variable.
runta secret set openai-api-key --value-env OPENAI_API_KEY # Read the value from an environment variable.
printf '%s' 'ghp_...' | runta secret set github-token --value-stdin # Pipe a value directly over stdin.
runta secret set internal-api --prompt --cache-ttl-secs 300 # Enter the value securely in an interactive prompt.

import os
from runta import Runta

runta = Runta()

secret = runta.secrets.set(
    "openai-api-key",
    os.environ["OPENAI_API_KEY"],
    cache_ttl_secs=0,
)

import { Runta } from "@runta/runta-sdk";

const runta = new Runta();

const secret = await runta.secrets.set(
  "openai-api-key",
  process.env.OPENAI_API_KEY!,
  { cacheTtlSecs: 0 },
);

Store additional secrets by repeating secret set or the SDK set call. There is no separate bulk-secret method.

Set or Update a Secret Stub

Secret stubs match a destination host and optional path. The literal ${credential} placeholder is replaced with the stored secret value when the egress gateway injects the outbound request.

runta secret rule set \
  demo \
  --host api.openai.com \
  --path '/v1/*' \
  --secret openai-api-key \
  --header Authorization \
  --template 'Bearer ${credential}'

from runta import Runta, SecretStubConfig

runta = Runta()
runtime = runta.runtimes.get("demo")

stub = runtime.secrets.set_secret_stub(
    "https://api.openai.com",
    path="/v1/*",
    config=SecretStubConfig(
        credential="openai-api-key",
        header="Authorization",
        value="Bearer ${credential}",
    ),
)

import { Runta } from "@runta/runta-sdk";

const runta = new Runta();
const runtime = await runta.runtimes.get("demo");

const stub = await runtime.secrets.setSecretStub("https://api.openai.com", {
  path: "/v1/*",
  config: {
    credential: "openai-api-key",
    header: "Authorization",
    value: "Bearer ${credential}",
  },
});

Set Multiple Secret Stubs

CLI flags create one rule per command. To create several rules in one CLI command, use a YAML file:

rules:
  - runtime: demo
    host: api.openai.com
    path: /v1/*
    secret: openai-api-key
    header: Authorization
    template: Bearer ${credential}
  - runtime: demo
    host: api.github.com
    path: /repos/*
    secret: github-token
    header: Authorization
    template: Bearer ${credential}

runta secret rule set -f rules.yaml

Python and TypeScript create multiple rules with repeated SDK calls. Setting the same runtime, host, path, and injection target updates the existing rule instead of creating a duplicate.

List and Delete Secret Stubs

runta secret rule list --runtime demo
runta secret rule delete <stub_id>

for stub in runtime.secrets.list_secret_stubs():
    print(stub.id, stub.host_pattern, stub.path_pattern)

runtime.secrets.delete_secret_stub(stub.id)

for (const stub of await runtime.secrets.listSecretStubs()) {
  console.log(stub.id, stub.hostPattern, stub.pathPattern);
}

await runtime.secrets.deleteSecretStub(stub.id);

Deletion is by stub ID. Delete several rules by iterating over the list; the CLI and SDKs do not expose a bulk-delete operation.

Omit --runtime in the CLI to list all runtime-scoped stubs. Tenant-wide stub listing is also available through runta.secrets.list_secret_stubs() in Python and runta.secrets.listSecretStubs() in TypeScript.

Quick Reference

Use the Runta CLI for terminal workflows, shell scripts, and direct runtime operations.

Task	CLI command
Store a tenant secret	`runta secret set openai-api-key --prompt`
Create a runtime secret stub	`runta secret rule set demo --host api.openai.com ...`
List runtime secret stubs	`runta secret rule list --runtime demo`
Inspect one secret stub	`runta secret rule describe <stub_id>`
Delete a secret stub	`runta secret rule delete <stub_id>`

Use these calls after creating or resolving a Python runtime handle such as runtime.

Task	Python SDK
Store a tenant secret	`runta.secrets.set("openai-api-key", value)`
Create a runtime secret stub	`runtime.secrets.set_secret_stub(url, config=config)`
List runtime secret stubs	`runtime.secrets.list_secret_stubs()`
Inspect one secret stub	`runtime.secrets.get_secret_stub(stub_id)`
Delete a secret stub	`runtime.secrets.delete_secret_stub(stub_id)`

Use these promise-based calls after creating or resolving a TypeScript runtime handle.

Task	TypeScript SDK
Store a tenant secret	`await runta.secrets.set("openai-api-key", value)`
Create a runtime secret stub	`await runtime.secrets.setSecretStub(url, { config })`
List runtime secret stubs	`await runtime.secrets.listSecretStubs()`
Inspect one secret stub	`await runtime.secrets.getSecretStub(stubId)`
Delete a secret stub	`await runtime.secrets.deleteSecretStub(stubId)`