Quickstart - Documentation

You need a browser for the owner steps and Node 22+ on the agent’s machine. Nothing is installed globally; every command runs through npx.

The examples below use the latest published @lit-protocol/keychain. Pin an exact version (@lit-protocol/keychain@2.2.3, for example) in anything you deploy, and check the npm page for release notes before upgrading.

1. Generate an agent identity

On the machine that will run the agent:

npx @lit-protocol/keychain init ./agent-identity.json

This writes a mode-0600 file containing an Ed25519 key pair and prints its publicKey. Share only the public key with the owner. The file is never overwritten if it already exists.

Open keychain.litprotocol.com and sign in with Google, a wallet or a passkey. Each method can own a vault; Google needs neither a wallet nor a passkey. See Sign-in and recovery for the custody tradeoffs.

Add a secret

Choose Add secret, then either Store a secret (the agent receives the value) or Connect a service (the agent runs one reviewed action and never sees the key). Name it in UPPER_SNAKE_CASE, for example OPENAI_API_KEY, and paste the value. It is encrypted in your browser before upload.

Approve the agent

On Agents, click + Add agent (add secrets first on Secrets if the vault is empty). Paste your existing agent’s 64-character public key, give it a name, and select only the secrets it needs. Nothing is selected automatically. Use Select all to select enabled, unexpired secrets, or Clear selection to reset the selection. You can uncheck individual secrets before continuing. Click Approve selected secrets and complete each owner approval. Existing agents and expiry dates stay unchanged; disabled or expired secrets must be enabled or renewed on their own pages first. Never upload an identity file or private key. New secret permissions default to 30 days; Renew permissions lets you change that separately.

Ready to use

No config download or agent restart is needed. The agent uses its existing private identity and the stable Keychain service URL. Approvals become available on its next list/read/use request. If signing fails partway through, earlier approvals remain saved; Retry remaining approvals checks access before continuing. Closing does not revoke access. Use Revoke on each secret to remove it.Choose Connect to a session to copy an agent prompt or MCP/SDK setup. Use the existing identity on the agent’s machine and verify its public key matches the approved agent. Config downloads have been removed.

Keep the private identity file on the agent device and out of version control. For a different service set KEYCHAIN_SERVICE_URL (SDK serviceUrl); the default is https://keychain.litprotocol.com. The trusted Lit endpoint is independently configured, never supplied by discovery.

3. Read the secret

Node SDK
CLI: hand it to one command
MCP: Claude Code, Codex, Cursor

npm install @lit-protocol/keychain

import { readFile } from "node:fs/promises";
import { LiveKeychain } from "@lit-protocol/keychain";

const identity = JSON.parse(await readFile("./agent-identity.json", "utf8"));
const keychain = new LiveKeychain(identity.privateKey);
try {
  const secret = await keychain.get("OPENAI_API_KEY");
  // Use it in your trusted application here. Never log it.
} finally {
  keychain.destroy();
}

run decrypts the secret and places it in a child process’s environment under its own name. The CLI itself prints nothing.

npx @lit-protocol/keychain run ./agent-identity.json -- python agent.py

Prefer run over get whenever a tool, not your code, needs the value. --env SECRET=VAR renames a variable, --only A,B selects secrets, and --file SECRET=PATH writes a mode-0600 file that is removed when the command exits, for tools that only read credentials from a path.

The package ships a local stdio MCP server. Register it with absolute paths:

claude mcp add lit-keychain -- npx -y @lit-protocol/keychain mcp /absolute/path/agent-identity.json

Codex takes the same command after codex mcp add lit-keychain --. JSON clients (Cursor, Windsurf) take it as command: "npx" with the same arguments. Start with the agent_public_key, list_actions and list_secrets tools; get_secret puts plaintext into model context, so call it only when you mean to.

Before the first execution request, the SDK attests the Lit endpoint: an Intel TDX quote chained to Intel’s root, the boot event log replayed into the RTMRs, the measured release checked against the on-chain whitelist on Base, and in Node the live TLS certificate bound to the enclave. Any failure blocks the request. See Security model.

4. Revoke, rotate, renew

Everything is on the secret’s page in the dashboard:

Revoke removes one agent. The action fetches the current policy on every request, so the agent’s next request is denied.
Disable switches the secret off for every agent without deleting it.
Delete revokes every agent and removes the encrypted value from Keychain in one step, freeing the slot. It cannot be undone unless you restore the secret from an encrypted backup you saved earlier.
Rotate & approve encrypts a new value and moves the existing agents to it in one signature. Live clients discover the current version on their next request.
Renew permissions sets a new expiry any number of days from now, or Never expire removes it so access lasts until you revoke or disable it.

If you suspect a credential leaked, also revoke it at the provider. Revocation cannot recall plaintext an agent already received.

Next steps

SDK, CLI and MCP reference

Every command and tool, the three credential files, and what each Access denied: message means.

Connected services

Let an agent read a Stripe balance or post to Slack without ever holding the key.

Sign-in and recovery

Add a second owner credential and download a backup before storing anything valuable.

Security model

What the operator can see, what it can never do, and the limits of revocation.

​1. Generate an agent identity

​2. Sign in and store a secret

​3. Read the secret

​4. Revoke, rotate, renew

​Next steps

SDK, CLI and MCP reference

Connected services

Sign-in and recovery

Security model

1. Generate an agent identity

2. Sign in and store a secret

3. Read the secret

4. Revoke, rotate, renew

Next steps