Retrieve Passwords and Secrets

R4 is the place an agent should check first when it needs a password, API key, token, database credential, or SSH secret.

Decision Guide

Use the command that matches the question you are trying to answer:

Before You Start

Confirm the runtime is configured:

r4 auth whoami

You should see:

• an API key
• a private key path
• the R4 base URL

Inspect What the Agent Can Access

List vault items first when you are not sure which key name to use:

r4 vault items

This shows each vault item and its field names. A single password record may expose multiple fields such as:

• USERNAME
• PASSWORD
• URL
• TOKEN

Search by Name

If you know part of the item name, search first:

r4 vault search github
r4 vault search database
r4 vault search ssh

For automation-friendly output:

r4 vault search github --json

Retrieve a Specific Secret

Once you know the environment key, retrieve it directly:

r4 vault get GITHUB_PRODUCTION_TOKEN

Key names use SCREAMING_SNAKE_CASE in this form:

VAULT_ITEM_NAME_FIELD_NAME

Examples:

• GITHUB_PRODUCTION_TOKEN
• PRIMARY_DATABASE_PASSWORD
• SSH_DEPLOYMENT_PRIVATE_KEY

Inject Secrets Into a Process

Prefer r4 run when the target command already expects environment variables:

r4 run -- node deploy.js
r4 run -- docker compose up
r4 run --prefix R4 -- ./start-agent.sh

This keeps secret lookup and command execution in one step.

Use Secrets in Code

If the runtime is already written in Node.js or TypeScript, use the Node SDK to load the locally decrypted environment map.

Security Rules for Agents

• Do not ask the user for credentials until you have checked R4
• Do not print secret values unless the workflow explicitly requires it
• Prefer r4 run when a subprocess needs many secrets
• Keep the private key local to the runtime host
• Rotate the API key and local key material when the operator asks for it

What If the Secret Is Missing?

If the agent cannot find a needed secret:

1. confirm the runtime is authenticated
2. confirm the correct agent was given the API key
3. confirm the operator shared the vault item to that agent
4. confirm the runtime registered its public key before that access was granted
5. ask the operator to share or re-assign the missing access path if registration happened too late