Gateway Secret References
Load gateway credentials from files, env vars, or secret managers — never plaintext
Gateway credentials load from a mounted file, an environment variable, or a secret-manager command — no plaintext token in YAML and no process-wide env var required.
The token, app_token, and verify_token fields accept a { source, id } reference in addition to plaintext and ${ENV}. The reference form is additive — existing configs keep working.
Quick Start
- Agent connects through the gateway
python from praisonaiagents import Agent agent = Agent(name="Ops Agent", instructions="Reply to messages", gateway=True) agent.start() - From a secret file
Read a mounted Docker or Kubernetes secret — never inherited by child processes.
yaml # gateway.yaml channels: telegram: platform: telegram token: { source: file, id: /run/secrets/telegram_token } - From an environment variable
Structural equivalent of
${SLACK_BOT_TOKEN}.yaml channels: slack: platform: slack token: { source: env, id: SLACK_BOT_TOKEN } app_token: { source: env, id: SLACK_APP_TOKEN } - From a secret manager
Run a CLI whose stdout is the secret (Vault, AWS, GCP, 1Password,
pass).yaml channels: discord: platform: discord token: source: exec id: "vault kv get -field=token secret/discord"
Which source do I choose?
Pick the source that matches where the secret already lives.
How It Works
The schema validator resolves each reference at load time, hands the plaintext value to the adapter, and registers it for log redaction.
| Source | id means | Resolved by |
|---|---|---|
file | A file path (e.g. /run/secrets/token) | Reads and strips the file contents |
env | An environment variable name | Reads and strips the env var |
exec | A command line | Runs it; stdout (stripped) is the secret |
A resolved secret string always wins over a raw {source, id} reference in the runtime merge, so adapters never receive an unresolved reference.
Reference Form
A credential field accepts a plaintext string, a ${ENV} shorthand, or the reference form below.
token: { source: file, id: /run/secrets/telegram_token, provider: custom }| Key | Type | Required | Description |
|---|---|---|---|
source | str | Yes | One of env, file, exec (or a custom registered source) |
id | str | Yes | Env var name, file path, or command line — interpreted per source |
provider | str | No | Free-form hint routed to a custom resolver (e.g. vault) |
Availability States
praisonai gateway doctor reports each field’s availability without printing its value, so operators can validate secret wiring before start-up.
| State | Meaning |
|---|---|
available | Resolved successfully (env set, file present and non-empty) |
configured-but-unavailable | Configured but cannot resolve (empty file, unreadable, empty env var) |
configured | An exec reference — configured, but not executed at probe time |
missing | Not set (env var unset, file not found) |
Human-friendly output:
$ praisonai gateway doctor --config gateway.yaml
Credential availability (values never shown):
telegram token ✓ available
slack token ✓ available
slack app_token ✗ configured-but-unavailable
discord token ✓ configured # exec source, not executedMachine-readable JSON:
$ praisonai gateway doctor --config gateway.yaml --json
{
"probes": { ... },
"secrets": {
"telegram": {"token": "available"},
"slack": {"token": "available", "app_token": "configured-but-unavailable"},
"discord": {"token": "configured"}
}
}exec-sourced credentials report as configured without running the command — the probe resolves it exactly once, so one-shot / rate-limited / rotating secret CLIs are never invoked twice.
At gateway boot, a configured-but-unavailable or missing credential now isolates just that channel instead of aborting the whole gateway — see Degraded Channel Isolation.
Log Redaction
Every resolved secret is registered so it is scrubbed from logs and tracebacks.
from praisonaiagents.secrets import resolve_secret, redact_secrets
result = resolve_secret({"source": "env", "id": "SLACK_BOT_TOKEN"})
print(redact_secrets(f"connecting with {result.value}"))
# connecting with [REDACTED]Outbound Reply Redaction
Every resolved gateway credential is also masked from bot replies, streamed drafts, and proactive/scheduled sends by the safe-by-default Outbound Secret Scrub. A credential-shaped token that surfaces in a tool result — even one you never registered — is masked the same way. Opt out per-bot with bot._redact_secrets_outbound = False (see the linked page for the full opt-out and custom-redactor pattern).
Custom Resolvers
Register a resolver to add a source (Vault, AWS Secrets Manager, GCP Secret Manager, 1Password, pass).
from praisonaiagents.secrets import (
SecretRef,
SecretResolution,
SecretResolver,
register_resolver,
)
class VaultResolver(SecretResolver):
def resolve(self, ref: SecretRef) -> SecretResolution:
# Look up ref.id in Vault; never raise on unavailable — return a
# SecretResolution instead.
return SecretResolution("available", value="resolved-secret")
register_resolver("vault", VaultResolver())
# Now this works in gateway.yaml:
# token: { source: vault, id: "secret/data/slack#token" }Backward Compatibility
Plaintext and ${ENV} keep working; the reference form is purely additive.
channels:
whatsapp:
platform: whatsapp
phone_number_id: "1234567890"
verify_token: { source: file, id: /run/secrets/wa_verify }
# Plaintext and ${ENV_VAR} still work.
token: "${WHATSAPP_API_TOKEN}"Full Example
# gateway.yaml — all three sources in one config
agents:
assistant:
instructions: "You are a helpful support agent."
model: gpt-4o-mini
channels:
telegram:
platform: telegram
# Mounted Docker / Kubernetes secret file (never inherited by child processes).
token: { source: file, id: /run/secrets/telegram_token }
slack:
platform: slack
# Structural env reference — equivalent to the old "${SLACK_BOT_TOKEN}".
token: { source: env, id: SLACK_BOT_TOKEN }
# Secret manager (Vault / AWS / GCP / 1Password / pass). Stdout is the secret.
app_token: { source: exec, id: "vault read -field=token secret/slack" }
whatsapp:
platform: whatsapp
phone_number_id: "1234567890"
verify_token: { source: file, id: /run/secrets/wa_verify }
# Plaintext and ${ENV_VAR} still work as before.
token: "${WHATSAPP_API_TOKEN}"Validate the wiring before shipping:
praisonai gateway doctor --config gateway.yamlBest Practices
Prefer file for Docker and Kubernetes secrets
A mounted secret file (/run/secrets/...) is never inherited by child processes, unlike a process-wide env var. Use { source: file, id: ... } for container deployments.
Prefer exec for secret managers with rotating credentials
Vault, AWS Secrets Manager, and GCP Secret Manager issue short-lived, rotating tokens. { source: exec, id: "..." } resolves the current value at start-up instead of pinning a stale one.
Keep ${ENV} for local development only
${ENV} and { source: env, id: ... } are convenient for local runs, but the value is visible to every child process. Move to file or exec for production.
Run gateway doctor before shipping
praisonai gateway doctor validates every field and prints the availability table without revealing any value — a safe pre-flight check for CI and deploy scripts.
Rotated secret files pick up only on a hot-reload
A rewritten { source: file } reference is re-read on a config hot-reload, not on a bare praisonai gateway reconnect. If a channel parked in CREDENTIAL_UNAVAILABLE after a runtime token rejection, trigger a hot-reload so the new file value is resolved. See Runtime credential rejection.
Related
gateway doctor and gateway status CLI reference.
Gateway overview and quick start.
Gateway Credential RotationRotating the gateway’s own auth token.
Standalone Bot YAMLSingle-bot YAML configuration and pre-flight checks.
Outbound Secret ScrubMask resolved credentials from bot replies, not just logs.
Secret Egress SentinelsReference a resolved secret by an opaque token so plaintext never reaches the model.