> ## Documentation Index
> Fetch the complete documentation index at: https://vincent-feature-cpl-357-docs-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Store a secret in Lit Agent Keychain, approve an agent's public key, and read it from Node, the CLI or an MCP client such as Claude Code.
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](https://www.npmjs.com/package/@lit-protocol/keychain) for release notes before upgrading.
## 1. Generate an agent identity
On the machine that will run the agent:
```sh theme={null}
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.
## 2. Sign in and store a secret
Open [keychain.litprotocol.com](https://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](/keychain/sign-in-and-recovery) for the custody tradeoffs.
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.
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.
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
```sh theme={null}
npm install @lit-protocol/keychain
```
```js theme={null}
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.
```sh theme={null}
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:
```sh theme={null}
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](/keychain/security#attested-lit-endpoint).
## 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
Every command and tool, the three credential files, and what each `Access denied:` message means.
Let an agent read a Stripe balance or post to Slack without ever holding the key.
Add a second owner credential and download a backup before storing anything valuable.
What the operator can see, what it can never do, and the limits of revocation.