R4
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:

  1. Authenticate with an AGENT-scoped API key
  2. Keep a local PEM-encoded RSA private key on the runtime host
  3. Register the matching public key with R4
  4. Read the vault items that were shared to that agent
  5. Decrypt secrets locally with the MCP server, CLI, SDK, or raw machine API
  6. 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
  • Vault-backed access granted after the runtime registers its public key
  • One of:

Canonical Workflow

1. Get the runtime credentials ready

  • Operators create or manage agent records in Platform -> Developer -> Agents
  • The runtime receives its AGENT API key or bootstraps a new agent-only org through POST /api/v1/auth/auth/register-agent (send X-Requested-With: R4Client on that public auth POST)
  • The runtime generates or is provisioned with its local private key
  • At this stage the agent is only a credentials shell unless the bootstrap request already included its first public key. Security-group membership, project membership, and direct vault sharing stay disabled until that first public key is registered.

The important split is:

  • the platform UI gives the runtime its API key
  • the runtime host must still generate or receive its own RSA private key

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

2. Register the public key

If the bootstrap flow did not already include publicKey, register the runtime key through:

  • POST /api/v1/machine/vault/public-key
  • or the CLI
  • or the Node SDK

This allows R4 to wrap vault DEKs for that agent.

Once the first registration succeeds, operators can add the agent to security groups, projects, or direct vault permissions.

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 checkpoint-signed vault metadata writes.

They can:

  • register their 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 the runtime's currently active registered encryption key. If the runtime rotates that 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:

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

That delegated-orchestration power does not change the current trust rules. Even an agent-manager runtime still needs its active registered signer for checkpoint-backed vault writes, and the broader attachment/procurement/webhook surfaces 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 CLI, Node SDK, MCP server, or current raw machine API is missing a capability the runtime needs, submit feedback through:

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: CLI

npm install -g @r4-sdk/cli
 
openssl genrsa -out ./agent-private-key.pem 2048
 
r4 auth login \
  --api-key "$R4_API_KEY" \
  --private-key-path ./agent-private-key.pem
 
r4 auth whoami
r4 vault items
r4 vault search github
r4 vault get GITHUB_PRODUCTION_TOKEN

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 r4 vault items or the raw machine API reports that no wrapped key exists for the vault, the most common cause is ordering: the runtime public key was registered after access had already been assigned. Ask the operator to confirm the key registration happened first, then re-share or re-assign the access path.

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/sdk'
 
const r4 = await R4.create({
  apiKey: process.env.R4_API_KEY!,
  privateKeyPath: './agent-private-key.pem',
})
 
const password = r4.env.GITHUB_PRODUCTION_TOKEN
  1. Authentication and Keys
  2. Retrieve Passwords
  3. MCP, CLI, or Node SDK
  4. API Reference
  5. Current Limitations
  6. Submit Feedback