agent.pw

library0.8.2jsnpmunverified

agent.pw is a robust credential vault and authentication framework specifically designed for AI agents. It provides secure storage for encrypted credentials, including OAuth tokens and API keys, utilizing AES-GCM for data at rest. The library manages the entire OAuth lifecycle, supporting PKCE, token refresh, revocation, and RFC 9728 discovery. Currently at version 0.8.2, the project exhibits a rapid release cadence with frequent patch and minor updates (multiple in April 2026 alone), indicating active development and continuous improvement. Key differentiators include its agent-centric design, comprehensive OAuth handling, support for admin-configurable credential profiles, path-based organization (`ltree` paths like `acme.connections.github`), and scoped access control. It is designed to be embeddable, working seamlessly with any PostgreSQL-compatible database without requiring a separate server component.

auth-security llm-agents database

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

agent.pw is primarily an ESM module, though CJS usage might be possible via transpilation or specific Node.js settings, ESM is recommended.

import { createAgentPw } from 'agent.pw';

OAuth-related utilities are located in the 'agent.pw/oauth' subpath. Ensure correct subpath import for specific features.

import { createInMemoryFlowStore } from 'agent.pw/oauth';

Database connection utilities are located in the 'agent.pw/sql' subpath. This is a common mistake to import from the root.

import { createDb } from 'agent.pw/sql';

The `unwrap` utility is an external dependency from the `okay-error` package, not an internal export of `agent.pw`.

import { unwrap } from 'okay-error';

This quickstart demonstrates how to initialize `agent.pw` with a PostgreSQL database, an encryption key, and an in-memory OAuth flow store, then resolves headers for a resource.

import { createAgentPw } from "agent.pw"; import { createInMemoryFlowStore } from "agent.pw/oauth"; import { createDb } from "agent.pw/sql"; import { unwrap } from "okay-error"; async function initializeAgentPw() { const databaseUrl = process.env.DATABASE_URL ?? ''; if (!databaseUrl) { throw new Error("DATABASE_URL environment variable is required."); } const encryptionKey = process.env.AGENTPW_ENCRYPTION_KEY ?? ''; if (!encryptionKey) { throw new Error("AGENTPW_ENCRYPTION_KEY environment variable is required."); } const db = unwrap(createDb(databaseUrl)); const agentPw = await unwrap( createAgentPw({ db, encryptionKey, flowStore: createInMemoryFlowStore(), }), ); console.log('agent.pw initialized successfully.'); // Example: Resolve headers for a previously connected resource const path = "acme.connections.docs"; // Replace with your resource path try { const headers = await unwrap(agentPw.connect.resolveHeaders({ path })); console.log(`Resolved headers for ${path}:`, headers); } catch (error) { console.error(`Failed to resolve headers for ${path}:`, error); } return agentPw; } initializeAgentPw().catch(console.error);

Debug

Known footguns

breakingAs `agent.pw` is in active `0.x.x` development, minor version increments (e.g., `0.6.0` to `0.7.0`) may introduce breaking API changes not explicitly detailed as such. Always review release notes carefully when upgrading.

gotchaThe `encryptionKey` is critical for credential security. Losing this key will result in irreversible loss of access to all encrypted credentials stored by `agent.pw`. It must be a strong, securely generated secret.

gotchaMany `agent.pw` operations return `Result` types (an `Ok` or `Err` wrapper) requiring the use of `unwrap` from `okay-error`. Failing to handle potential errors from `unwrap` can lead to uncaught exceptions and application crashes.

breakingVersion `0.8.0` introduced the ability to initialize with a profile-only configuration without an encryption key, but the core `createAgentPw` function still mandates an `encryptionKey` if you intend to store secrets. This feature primarily applies to specific `connect.prepare` flows.

gotchaThe OAuth redirect URIs (`redirectUri`) specified in `agentPw.connect.startOAuth` must exactly match the redirect URIs configured with the OAuth provider. Mismatches will result in authorization failures.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

28 hits · last 30 days

bytedance

gptbot

ahrefsbot

petalbot

script

Resources

githubhttps://github.com/smithery-ai/agent.pw ↗

packagehttps://www.npmjs.com/package/agent.pw ↗

homepagehttps://agent.pw ↗