Browse docs+

R4 for Agents

R4 is a password manager and secret store for agent runtimes.

If an agent is pointed at https://r4.dev and told to use R4 for password management, the supported path is:

Create the agent in Platform with the browser-generated public key and selected security groups
Download the one-time runtime config containing the AGENT API credentials and matching private key
Keep the local PEM-encoded RSA private key on the runtime host
Read the vault items that were shared to that agent
Decrypt secrets locally with the MCP server, SDK, or raw machine API
Optionally create or archive vault metadata when the runtime signs checkpoints with its active registered key

What an Agent Needs

An AGENT API key in {accessKey}.{secret} format
A local RSA private key in PEM format
A registered public key before vault-backed access is granted. The Platform create-agent wizard handles this by generating the key pair locally, sending only the public key to the backend, creating the agent, and applying selected security groups in one flow.
One of:
- the MCP server
- the Node SDK
- the machine API

Canonical Workflow

1. Get the runtime credentials ready

Operators create or manage agent records in Platform -> Developer -> Agents
That platform wizard generates the runtime key pair locally in the browser, sends the public key during agent creation, applies selected security groups, and then offers a one-time JSON runtime config containing agentId, accessKey, accessSecret, and privateKey
New account registration happens through the website. Agent runtime bootstrap should use Platform -> Developer -> Agents.
Import that config on the runtime host with r4 configure agent --config <path> when you want a shared local CLI/SDK profile.

The important split is:

the platform UI can hand the operator a one-time runtime config that includes the split API key plus the locally generated private key
R4 still stores only the public key and rotation metadata, so if that bundle is lost it cannot be downloaded again

The private key stays on the runtime host. R4 stores only the matching public key and rotation metadata.

2. Rotate or repair the public key only when needed

The platform wizard registers the initial public key during agent creation before it applies selected security groups. Normal CLI or SDK env reads should use the downloaded runtime JSON directly.

If you need to repair an idempotent registration or rotate to a different key, use:

POST /api/v1/machine/vault/public-key

Re-registering the same public key later is safe and idempotent. Rotating to a different key still requires the current private key and, when the old key still has active vault access, a complete rewrappedVaultKeys batch so every active DEK is atomically re-wrapped to the new key.

3. Retrieve the shared secrets

The agent can then:

list accessible vaults
run full or delta sync with GET /api/v1/machine/vault/sync
search vault items by name
fetch locally decrypted secret values
inject secrets into a process at runtime

Start with the Retrieve Passwords guide if your goal is to look up credentials quickly.

4. Respect the current write model

AGENT-scoped runtimes are the supported runtime path for password retrieval and can now also perform machine vault metadata writes.

They can:

repair or rotate their registered public key
retrieve wrapped vault keys
list vaults and vault items they can access
decrypt shared secrets locally
create vaults
create vault items
archive vaults
archive vault items

Those write paths still depend on endpoint policy and asset access. If the runtime rotates its registered encryption key while vault-backed access exists, it must submit replacement wrapped DEKs for every active vault. See Current Limitations.

5. Delegated orchestration is a separate capability

Some AGENT runtimes act as "master agents" for other agents.

When an AGENT runtime also has:

the tenant role TENANT_AGENT_MANAGER
machine permissions such as machine.agent.all and machine.permissions.all

it can:

create subordinate agents
grant those agents direct tenant roles
assign project or vault access to those agents

The simplest orchestration bootstrap is:

GET /api/v1/machine/agent and reuse the current domainTenantId
POST /api/v1/machine/agent to create the subordinate runtime
PATCH /api/v1/machine/agent/:id/tenant-roles to grant the needed direct roles
POST /api/v1/machine/permissions/PROJECT/:id/set-permissions to share project access

That delegated-orchestration power does not bypass endpoint policy or asset access. Vault writes, attachment management, procurement, and outbound machine webhooks still require their own endpoint permissions and, in some cases, additional tenant or org roles.

For the dedicated lifecycle and delegated-access guides, see Agent Orchestration and Permission Management.

6. Report unsupported capability gaps

If the Node SDK, MCP server, or current raw machine API is missing a capability the runtime needs, submit feedback through:

POST /api/v1/machine/feedback
or the dedicated Submit Feedback guide

This endpoint is AGENT-only and is meant for product-gap feedback such as "I tried to do X, but R4 does not support it yet." Do not include secret values, plaintext credentials, tokens, or private user data.

Fastest Path: Platform And SDK

Create the agent in Platform -> Developer -> Agents, select its security groups, download the one-time runtime config, and import it with r4 configure agent --config <path> on the runtime host. The CLI configures the local agent profile and stores the private key under ~/.r4; it still does not mint AGENT credentials or register accounts on its own.

If the runtime loses its active private key, it loses the normal self-service way to rotate to a new one because key rotation requires proof from the current private key. Treat that file as part of the runtime identity, not as an optional cache.

If the SDK or raw machine API reports that no wrapped key exists for the vault, check whether the access path changed after agent creation and then re-share or re-assign that access path. The current platform create-agent wizard sends the first public key and applies selected security groups in the same creation flow.

Fastest Path: MCP

If your agent framework already speaks MCP, use the local stdio MCP server:

{
  "mcpServers": {
    "r4": {
      "command": "npx",
      "args": ["-y", "@r4-sdk/mcp"],
      "env": {
        "R4_API_KEY": "agent_access_key.secret",
        "R4_PRIVATE_KEY_PATH": "/absolute/path/to/agent-private-key.pem"
      }
    }
  }
}

The MCP server is intentionally local. It keeps the private key on the runtime host, reuses the supported Node SDK path for decryption, and exposes read-oriented tools like vault listing, secret-key search, and exact secret retrieval.

Fastest Path: Node SDK

import R4 from '@r4-sdk/node'
 
const r4 = await R4.create({
  apiKey: process.env.R4_API_KEY!,
  privateKeyPath: './agent-private-key.pem',
})
 
const password = r4.env.GITHUB_PRODUCTION_TOKEN