AgentPassVault

Important

This is a hobby project and is currently under active development.

AgentPassVault is a secure, standalone secret manager designed specifically for autonomous AI agents (like OpenClaw, formerly Moltbot, ClawdBot). It provides a bridge between human owners and automated workers, ensuring agents can access credentials without exposing sensitive data in chat logs or LLM context.

Why AgentPassVault?

• Prevent Secret Leakage: AI agents often need credentials. Sharing them directly in chat or system prompts is a massive security risk. AgentPassVault keeps secrets out of the LLM context.
• Asynchronous Approval: Agents can request secrets they don't have. Humans fulfill these requests via a secure UI.
• Zero Knowledge: The server never sees your plaintext secrets. Everything is encrypted/decrypted on the client side.

Quick Start (Install & Use)

This section is the end-user path. Development setup is in Development Guide.

Assumption: Web UI is available at https://agentpassvault.com.

1) Register and create an Agent

1. Sign up / log in at https://agentpassvault.com.
2. Go to Agents and create an agent.
3. Copy the generated agent config values (apiUrl, tenantId, agentId, appToken).

2) Prepare persistent config path (human setup)

Before agent init, choose a persistent workspace path and set:

# Set this in your agent's shell login script, replace /home/node with your setting.
export AGENTPASSVAULT_CONFIG_PATH="/home/node/.openclaw/workspace/config/agentpassvault"

If you run your agent with Docker Compose, pass it as an environment variable (example):

environment:
  # Replace /home/node with your setting.
  - AGENTPASSVAULT_CONFIG_PATH=/home/node/.openclaw/workspace/config/agentpassvault

3) Give your agent one short instruction

Use this prompt in OpenClaw:

Read and follow this guide strictly:
https://raw.githubusercontent.com/joshua5201/AgentPassVault/main/GUIDE.md

The config/key path is defined in environment variable `AGENTPASSVAULT_CONFIG_PAT`.
Prompt the user if this environment variable is not set. It will use the default path `~/.config/agentpassvault``.
Do CLI installation/setup yourself, then use the documented secret workflow.
Prefer existing secrets first (list/search/get), and only create requests when missing or no access.
Never print plaintext secrets in chat/logs.

4) Fulfillment (human side)

1. Click the fulfillment link sent by the agent.
2. Log in to AgentPassVault Web UI.
3. Approve existing secret access or create a new secret, then approve.

After approval, the agent continues with request get / secret get as described in GUIDE.md.

How It Works

1. The "Ask" Pattern (Missing Secret)

When an agent needs a secret it doesn't have:

1. Agent Request: The agent creates a request for a specific service (e.g., "AWS Production").
2. Human Notification: The agent provides a secure link to the human: "I need AWS credentials. Please provide them here: [LINK]".
3. Fulfillment: The human clicks the link, enters the secret, and the agent is granted access via a secure lease.

2. The Lease Flow (Retreival)

Access is managed through Leases:

1. Public Key Auth: Agents register a public key.
2. Encrypted Delivery: The server provides secrets previous encrypted specifically by the web client for the agent's public key.
3. Local Decryption: The Agent CLI tool decrypts the secret locally using the private key.
4. Rotation Integrity: If a secret is updated or an agent rotates its key, old leases are invalidated.

Why It Is Safe

AgentPassVault uses a Zero-Knowledge Architecture:

• Master Key: Secrets are encrypted with a Master Key derived from the human's password (which never leaves the browser).
• Agent-Specific Encryption: When a lease is created, the Web UI decrypts the secret and re-encrypts it with the agent's public key.
• No Plaintext on Server: The database only stores data that the server itself cannot decrypt. Even if the server is compromised, your secrets remain safe.

Development Guide

Quick Start (Local Dev)

Prerequisites

• Docker & Docker Compose
• Java 21 (for native execution)

1. Start the Infrastructure

docker compose up -d

For parallel local stacks, set a unique APV_CONTAINER_PREFIX in .env (for example alice-apv-) to avoid container name conflicts.

2. Setup Database

./scripts/database/flyway.sh

3. Run the Application

./run_dev_app.sh

The API will be available at http://localhost:8080.

Frontend Development

The frontend is a TypeScript monorepo managed by Turborepo and pnpm. It consists of three main parts:

• packages/sdk: The core cryptographic and API logic.
• apps/cli: The agentpassvault command-line tool.
• apps/web: The React-based administrator dashboard.

Prerequisites

• Node.js: Version 20 or higher.
• pnpm: The package manager used for this project. Install via npm install -g pnpm.

Core Commands (Run from the frontend/ directory)

Command	Description
pnpm install	Install all dependencies for the entire monorepo.
pnpm build	Build all packages (SDK, CLI, Web). Includes linting and type-checking.
pnpm clean	Remove all build artifacts (dist, .turbo, node_modules).
pnpm lint	Run code quality and formatting checks.
pnpm typecheck	Run TypeScript compiler checks across all projects.
pnpm test	Run all unit tests.
pnpm sync-dtos	Re-generate the API contract from the Java backend.

Web UI Environment Variables

The web app reads these variables at build/start time:

Variable	Default	Used In	Purpose
AGENTPASSVAULT_API_URL	none	Dev + Production	Canonical backend API base URL. Preferred variable for scripts, CI, and static builds.
VITE_API_URL	none	Dev + Production	Backward-compatible backend API base URL. Used when AGENTPASSVAULT_API_URL is not set.
VITE_API_MOCKING	false (real mode) / true (mocked mode)	Dev	Enable MSW mocked API handlers.
VITE_API_CLIENT_FALLBACK	false (real mode) / true (mocked mode)	Dev	Fallback to mock responses on network failures in selected flows.
VITE_API_PROXY	true (real mode) / false (mocked mode)	Dev	Use Vite /api proxy to backend (VITE_API_URL target).
VITE_DEV_HTTPS	true	Dev	Enable HTTPS for local Vite dev server.
VITE_DEV_HTTPS_CERT	auto-generated by start_vite.sh	Dev	Path to local HTTPS cert (only when VITE_DEV_HTTPS=true).
VITE_DEV_HTTPS_KEY	auto-generated by start_vite.sh	Dev	Path to local HTTPS key (only when VITE_DEV_HTTPS=true).
VITE_PORT	5173	Dev helper	Local Vite port in start_vite.sh.
VITE_HOST	0.0.0.0	Dev helper	Local Vite host bind in start_vite.sh.

Start Web UI Locally

cd frontend
./start_vite.sh mocked
./start_vite.sh real

To point real mode to local integration backend:

cd frontend
AGENTPASSVAULT_API_URL=http://localhost:58080 ./start_vite.sh real

Cloudflare Pages (Staging/Prod) Required Variables

Set these in your CI/build environment before creating the static assets:

AGENTPASSVAULT_API_URL=https://<your-api-domain>
VITE_API_MOCKING=false

Recommended explicit values:

VITE_API_CLIENT_FALLBACK=false
VITE_API_PROXY=false

Notes:

• VITE_API_PROXY only works in Vite dev mode and is not used in production bundles.
• Production startup now fails fast if neither AGENTPASSVAULT_API_URL nor VITE_API_URL is provided.
• If you still get fetch failed, verify backend CORS allows your Cloudflare Pages origin.

Working with the Agent CLI

Tip

Are you an automated agent looking for integration instructions? Check out the Agent Integration Guide (GUIDE.md) for a quick overview of required values, secure CLI commands, and JSON parsing.

Local Execution

After building the project (pnpm build), you can run the CLI directly using Node.js without installing it globally:

cd frontend/apps/cli
node dist/index.js --help

Common Agent CLI Commands

# Prefer reuse before requesting a new secret
agentpassvault secret list
agentpassvault secret search --name "GitHub PAT"

# Create request with context/schema hint
agentpassvault request create "GitHub PAT" --context "CI release" --schema "login"

# Check request and fetch secret
agentpassvault request get <requestId>
agentpassvault secret get <secretId>

Legacy aliases are still supported for backward compatibility, but are deprecated (request-secret, get-request, get-secret, search-secrets).

Running Tests

The CLI has two types of tests:

• Unit Tests: Logic tests that don't require a server. pnpm test:unit
• Integration (E2E) Tests: Full lifecycle tests against the running Docker backend. pnpm test:integration

Global Link (Optional)

To make the agentpassvault command available everywhere on your system:

cd frontend/apps/cli
npm link

Download Prebuilt CLI Binary (Recommended)

For users/agents, the easiest path is downloading from the latest release:

• Releases page: https://github.com/joshua5201/AgentPassVault/releases/latest
• Linux binary asset naming: agentpassvault-linux-v<version>

Example (v0.3.4):

curl -fL -o agentpassvault-linux \
  https://github.com/joshua5201/AgentPassVault/releases/download/v0.3.4/agentpassvault-linux-v0.3.4
chmod +x agentpassvault-linux
./agentpassvault-linux --help

Compiling to a Single Executable (Developer)

If you want to build the AgentPassVault CLI binary yourself:

cd frontend/apps/cli
npm install -g pkg
pkg package.json

The compiled binaries will be generated in the frontend/apps/cli folder.

Troubleshooting

If you encounter weird build errors or type mismatches after a git pull:

1. pnpm clean
2. pnpm install
3. pnpm build

License & Commercial Usage

Backend

The server side application is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details. All source files must contain the standard AGPL v3.0 license header.

For commercial inquiries, custom licensing terms, or enterprise support, please contact: joshua841025 at gmail.com

Fronted (SDK, CLI, Web UI)

Licensed under the GNU General Public License v3.0 (GPLv3). See the frontend/LICENSE file for details.

Contributing

We welcome all contributions! To ensure legal clarity for all users, all contributors must agree to our Contributor License Agreement (CLA) when submitting a Pull Request.

All source files must contain the appropriate license header.