auth

name

auth

description

Register an AI-provider API key on a VPS running bento, via SSH, and propagate it to every BENTO_MANAGED stack. Drives bento-auth (Anthropic, OpenAI, OpenRouter, z.ai, Gemini, and any OpenAI-compatible endpoint). Use when the user says "add my OpenAI key", "register an Anthropic key", "set up provider auth on my bento server". NOTE: subscriptions (Claude Pro/Max, ChatGPT Plus) are OUT OF SCOPE — those use each app's native sign-in.

You are handling a secret (an API key) on the user's behalf. Never echo the key into any output, log line, or command you display — keep it out of narration and out of BENTO_VERBOSE traces. All artifacts stay in English.

When to invoke

• "register my OpenAI / Anthropic / OpenRouter / z.ai / Gemini key on <host>"
• "add a provider key to my bento server"
• "wire an OpenAI-compatible endpoint into bento"

This is API KEYS only. If the user wants to use a subscription (Claude Pro/Max, ChatGPT Plus), do NOT use bento-auth — point them at the app's native sign-in (e.g. openclaw models auth login --provider openai, or paperclip's bundled claude /login). bento-auth's old subscription snapshots went stale in days and were removed.

Inputs

Input	Source	Notes
VPS host + SSH user	user message; default user root	reachable via SSH
provider	user message	must be a bento-auth catalog id (see below)
API key	user message — collect privately, NEVER display it back

Discover the valid provider ids from the host itself (don't hardcode):

ssh "$user@$host" "bash /root/.local/share/bento/scripts/bento-auth --help"

Register — non-interactive over SSH

bento-auth reads the key from stdin (read -rs) and honours BENTO_AUTH_ASSUME_YES=1 to skip the "store anyway?" prompt on a failed validation. So you can pipe the key in without a TTY. Read the key into a shell variable WITHOUT printing it, then:

# Collect the key into $KEY by whatever private means; do not echo it.
printf '%s\n' "$KEY" | ssh "$user@$host" \
  "BENTO_AUTH_ASSUME_YES=1 bash /root/.local/share/bento/scripts/bento-auth <provider>"
unset KEY

For an exotic OpenAI-compatible endpoint not in the catalog:

printf '%s\n' "$KEY" | ssh "$user@$host" \
  "BENTO_AUTH_ASSUME_YES=1 bash /root/.local/share/bento/scripts/bento-auth openai-compat <label> <base_url>"

bento-auth validates the key (where the catalog defines a validate URL), persists it to state.providers.<ENV>, and runs auth_propagate_state_providers to docker service update --env-add it onto every running BENTO_MANAGED stack. Future deploys inherit it automatically.

If validation fails, bento-auth (with ASSUME_YES) still stores it and prints a warning — surface that warning to the user so they can re-check the key.

Verify

ssh "$user@$host" "bash /root/.local/share/bento/scripts/bento-auth list"

This prints registered keys MASKED — safe to show the user. Confirm the provider's env var appears.

Report back

• Which provider env var is now set (masked), and that it propagated to managed stacks.
• Which apps consume it: hermes, paperclip, and generic OpenAI-compatible apps read these env vars. openclaw does NOT — it owns its provider config; tell the user to reference the propagated ${ENV} in an openclaw custom-provider definition if they want it there.
• If the user actually needs a subscription, redirect to the app's native sign-in.

Full reference: docs/reference/bento-auth.md on the host (and in the repo).