# Passwd

> passwd.team for AI agents — MCP server, agent-safe CLI, and full CLI. Agents use credentials without ever seeing the raw values.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pepuscz-passwd`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pepuscz](https://agentstack.voostack.com/s/pepuscz)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pepuscz](https://github.com/pepuscz)
- **Source:** https://github.com/pepuscz/passwd
- **Website:** https://passwd.team

## Install

```sh
agentstack add mcp-pepuscz-passwd
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# passwd

[passwd.team](https://passwd.team) for AI agents — your agent uses credentials without ever seeing the raw values.

> **Disclaimer:** This is not officially part of the passwd.team project. It will be merged once it undergoes a security audit. Until then, use at your own risk.

## What it can do

Four tools for different scopes — pick what fits your setup.

| Tool | Can do | Cannot do |
|---|---|---|
| **Claude extension** | Browse secrets, TOTP, use credentials on your behalf (output masked) | Raw credential output, writes |
| **MCP server** | Browse secrets, view details (redacted), pull TOTP codes | Credential output, writes, exec |
| **Agent CLI** | Browse, TOTP, run commands with credentials (stdout masked) | Raw credential output, writes |
| **Full CLI** | Everything — raw values, create, update, delete, share | — |

## Setup

Pick your platform. In all examples below, replace `https://your-deployment.passwd.team` with your passwd.team deployment URL (default is `https://app.passwd.team`).

| Platform | Section |
|---|---|
| Claude app (macOS) | [Claude](#claude) |
| OpenClaw | [OpenClaw](#openclaw) |
| Any MCP client | [MCP server](#mcp-server) |
| AI agents with shell access | [Agent CLI](#agent-cli) |
| Terminal / scripts / CI | [Full CLI](#full-cli) |

### Claude

Claude extension (`.mcpb`). Works in both Chat and Cowork tabs of the Claude macOS app. Credentials never reach the AI — all output is masked.

**1. Download** `passwd.mcpb` from the [latest release](https://github.com/pepuscz/passwd/releases).

**2. Install** — double-click the file.

**3. Configure** — enter your deployment URL (default: `https://app.passwd.team`).

**4. Authenticate** — ask Claude to log in. A browser window opens for Google OAuth.

**Connecting to services** — For services with an MCP server, paste the MCP configuration into the secret's **note** field. The agent detects it and connects automatically.

Example — two messages work best:
1. *"Find my Rohlik credentials in passwd and read the details"*
2. *"Now buy me bananas"*

### OpenClaw

passwd has two OpenClaw integrations — pick based on where the credential is needed:

- **Config field on the [SecretRef supported list](https://docs.openclaw.ai/reference/secretref-credential-surface)?** → Use the **secrets provider** — the gateway resolves it at startup, the agent never sees it.
- **Runtime credential the agent needs** (database login, deploy key, custom API call)? → Use the **agent skill** — the agent injects it into a command via `exec --inject`, without seeing the raw value.

You can use both together.

| Integration | What it does | Package | Agent sees raw credentials? |
|---|---|---|---|
| **Secrets provider** | Resolves SecretRefs at gateway startup (API keys, tokens) | `passwd-cli` | No — gateway holds them internally |
| **Agent skill** | Lets the agent browse vault, check TOTP, inject creds into commands | `passwd-agent-cli` | No — credentials always redacted or masked |

#### Secrets provider (gateway)

Resolve [SecretRefs](https://docs.openclaw.ai/gateway/secrets#secretref-contract) at gateway startup — API keys, service tokens, and other credentials go into the gateway's internal config and never reach the agent.

> **SecretRef coverage is limited.** Only config fields on the [supported list](https://docs.openclaw.ai/reference/secretref-credential-surface) can use SecretRefs. If the credential is needed at runtime (database login, deploy key, custom API call) or the config field isn't on the list, use the **agent skill** below instead.

**1. Authenticate** (the gateway runs `passwd-cli`, not the agent):

```bash
PASSWD_ORIGIN=https://your-deployment.passwd.team npx -y @passwd/passwd-cli@1.6.1 login
```

**2. Add the secrets provider** to `~/.openclaw/openclaw.json`:

```json5
{
  secrets: {
    providers: {
      passwd: {
        source: "exec",
        command: "/usr/local/bin/npx",          // absolute path to npx
        args: ["-y", "@passwd/passwd-cli@1.6.1", "resolve"],
        passEnv: ["PASSWD_ORIGIN", "HOME"],
        allowSymlinkCommand: true,              // needed if npx is a symlink (Homebrew)
        trustedDirs: ["/usr/local", "/opt/homebrew"],
      },
    },
  },
}
```

**3. Reference secrets** in model providers using SecretRefs — the `id` is `SECRET_ID:field` (field defaults to `password`):

```json5
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-4o", name: "gpt-4o" }],
        apiKey: { source: "exec", provider: "passwd", id: "abc123:password" },
      },
    },
  },
}
```

Store your API keys as secrets in passwd.team, then use their IDs in the `id` field. Run `npx @passwd/passwd-cli@1.6.1 list` to find them.

#### Agent skill

Let the agent browse your vault, check TOTP codes, and inject credentials into commands — without ever seeing raw credential values.

> passwd stores tokens encrypted via the platform keychain (macOS Keychain / Linux libsecret). OpenClaw must run as a LaunchAgent (macOS) or systemd user unit (Linux) so the keychain is available.

**1. Authenticate** with the agent-safe CLI:

```bash
PASSWD_ORIGIN=https://your-deployment.passwd.team npx -y @passwd/passwd-agent-cli@1.6.1 login
```

**2. Add the skill** at `~/.openclaw/workspace/skills/passwd/SKILL.md`:

````markdown
---
name: passwd
description: "Authenticate, browse credentials, generate TOTP codes, and inject secrets into commands."
metadata:
  {
    "openclaw":
      {
        "emoji": "🔑",
        "requires": { "env": ["PASSWD_ORIGIN"], "bins": ["npx"] },
      },
  }
---

# passwd

Browse credentials, generate TOTP codes, and inject secrets into commands — from your team's passwd.team vault. Always use `--json` for structured output.

CMD: `npx -y @passwd/passwd-agent-cli@1.6.1`

## Setup

Before first use, ask the user for their passwd.team deployment URL (e.g. https://company.passwd.team). Do not assume a default — wait for their answer. Then set PASSWD_ORIGIN to that URL for all commands.

## Login

Login is interactive — use the exec tool in process mode to keep the session alive:
1. Start CMD login with exec (process mode, not run-and-wait)
2. Poll output to get the OAuth URL
3. Send the URL to the user
4. When the user provides the redirect URL, write it to the process stdin

## Commands

Search:    CMD list -q "search term" --json
Info:      CMD get SECRET_ID --json
TOTP code: CMD totp SECRET_ID
Whoami:    CMD whoami --json
Envs:      CMD envs --json

## Use credentials

Inject a credential into a command without exposing it:
CMD exec --inject DB_PASS=SECRET_ID:password -- psql -h host -U user

Multiple secrets: add more `--inject VAR=ID:field` flags.

## Multi-environment

Use --env NAME with any command to target a specific passwd.team deployment:
CMD list -q "search" --json --env acme
CMD envs --json

## Display

- Never use tables or code blocks
- Bold label, backtick value: **Username:** `value`
- End credential output with 🔐
- One field per line, skip empty fields
- Lists: name and type only
- TOTP: code and remaining seconds only
````

**3. Restart the gateway** so the skill and provider are discovered.

For multiple deployments, log in to each origin separately (`PASSWD_ORIGIN=... npx @passwd/passwd-agent-cli@1.6.1 login`). The agent can then switch with `--env` — see the Multi-environment section in the skill above.

#### MCP servers with credentials

MCP servers that need auth headers (e.g. private APIs) can use `mcp-wrap` to resolve credentials from the vault at startup. No raw values in config files — they're fetched at runtime from the keychain-backed vault.

```json
{
  "name": "my-service",
  "transport": "stdio",
  "command": "npx",
  "args": [
    "-y", "@passwd/passwd-agent-cli@1.6.1", "mcp-wrap",
    "https://mcp.example.com/mcp",
    "x-api-email=SECRET_ID:username",
    "x-api-key=SECRET_ID:password"
  ],
  "env": {
    "PASSWD_ORIGIN": "https://your-deployment.passwd.team"
  }
}
```

Each `header=SECRET_ID:field` mapping resolves the secret field from the vault and passes it as an HTTP header to `mcp-remote`. Stdout is masked.

### MCP server

If you just want read-only access to your vault from any MCP-compatible client — browse secrets, view details (credentials redacted), pull TOTP codes — install the MCP server standalone:

```json
{
  "mcpServers": {
    "passwd": {
      "command": "npx",
      "args": ["-y", "@passwd/passwd-mcp@1.6.1"],
      "env": {
        "PASSWD_ORIGIN": "https://your-deployment.passwd.team"
      }
    }
  }
}
```

The MCP server is read-only (no create, update, delete, or share) and credential fields are always redacted. To run commands with credentials, pair it with the agent CLI (`@passwd/passwd-agent-cli`).

### Agent CLI

The agent CLI (`@passwd/passwd-agent-cli`) is a hardened subset of the full CLI — no command can output raw credential values. It adds `exec --inject` for injecting secrets into subprocesses with stdout always masked. Use it with any AI agent that has shell access (Claude Code, Cowork, or any MCP client paired with the MCP server).

```bash
export PASSWD_ORIGIN=https://your-deployment.passwd.team
npx @passwd/passwd-agent-cli@1.6.1 login
npx @passwd/passwd-agent-cli@1.6.1 list
npx @passwd/passwd-agent-cli@1.6.1 exec --inject DB_PASS=SECRET_ID:password -- psql -h host -U app
```

Credentials are injected as environment variables into the child process. Stdout is always masked — if the subprocess prints a secret value, it's replaced with ``. The raw values never enter the AI context.

### Full CLI

The full CLI (`@passwd/passwd-cli`) has complete access to your vault — including raw credential values via `--field` and unmasked output via `--no-masking`. Use it for terminal sessions, scripts, and CI pipelines where you control the environment.

> **Do not use the full CLI for AI agent integrations.** It can output raw credentials, which means an agent could exfiltrate them. Use `@passwd/passwd-agent-cli` instead — it has the same useful commands but no way to output raw credentials. The only exception is the **secrets provider** (gateway), where the CLI runs as the gateway process, not as the agent.

```bash
export PASSWD_ORIGIN=https://your-deployment.passwd.team
npx @passwd/passwd-cli@1.6.1 login
npx @passwd/passwd-cli@1.6.1 list
npx @passwd/passwd-cli@1.6.1 --help
```

For multiple deployments, log in to each origin separately, then use `--env` to switch. Or use per-project tokens — `passwd login .` in each project directory:

```bash
# Global multi-env (tokens in ~/.passwd)
PASSWD_ORIGIN=https://acme.passwd.team npx @passwd/passwd-cli@1.6.1 login
npx @passwd/passwd-cli@1.6.1 list --env acme

# Per-project (tokens in ./project/.passwd, auto-discovered)
cd ~/project && PASSWD_ORIGIN=https://acme.passwd.team npx @passwd/passwd-cli@1.6.1 login .
```

### Passing sensitive values via stdin

For `--password`, `--totp`, `--credentials`, `--private-key`, `--secure-note`, `--card-number`, and `--cvv-code`, pass `-` as the value to read from stdin instead of exposing the value in the process list:

```bash
echo "s3cret" | passwd create -t password -n "My secret" --password -
```

Only one flag can read from stdin per invocation.

### Building from source

```bash
git clone https://github.com/pepuscz/passwd.git
cd passwd
npm install && npm run build
```

Then use `node packages/passwd-mcp/dist/index.js`, `node packages/passwd-agent-cli/dist/index.js`, or `node packages/passwd-cli/dist/index.js` in place of `npx` commands above.

## Upgrading

Check [releases](https://github.com/pepuscz/passwd/releases) for new versions, then update the version number in your config — OpenClaw gateway config / SKILL.md, or CLI alias — and restart. The desktop extension updates by installing the new `.mcpb` file.

## Authentication

Google OAuth2. On first use, the `passwd_login` tool (MCP) or `passwd login` (CLI) will guide you through authentication. Tokens are encrypted at rest (AES-256-GCM, key in platform keychain) and auto-refresh. Requires macOS Keychain or Linux `secret-tool` (libsecret).

**Per-project tokens** — `passwd login ` saves tokens to `/.passwd/` instead of `~/.passwd`. All commands auto-discover `.passwd/` by walking up from the working directory (like `.git`), so no extra config is needed after login. Useful for Cowork projects where each shared folder can have its own passwd identity.

## MCP tools reference

The MCP server (`@passwd/passwd-mcp`) can be installed standalone — see [MCP server](#mcp-server). It is read-only (no writes) and credential fields are always redacted.

| Tool | Description |
|---|---|
| `passwd_login` | Google OAuth login flow |
| `list_secrets` | Search/list secrets (filter by query, type; paginate) |
| `get_secret` | Get secret details (credentials redacted) |
| `get_totp_code` | Get current TOTP code (ephemeral 30s codes) |
| `get_current_user` | Get authenticated user profile |

The Claude desktop extension (`passwd.mcpb`) includes all 5 tools above plus:

| Tool | Description |
|---|---|
| `run_with_credentials` | Run a command with secrets injected as env vars (stdout/stderr masked) |
| `connect_mcp_service` | Connect to a remote MCP service using credentials from a secret (MCP config extracted from note field JSON) |
| `call_remote_tool` | Call a tool on a connected remote MCP service (credentials injected as HTTP headers, response masked) |

## Agent CLI commands reference

The agent CLI (`@passwd/passwd-agent-cli`, binary `passwd-agent`) is a hardened subset of the full CLI — no command outputs raw credential values. Used by Cowork and OpenClaw integrations.

| Command | Description |
|---|---|
| `passwd-agent login [dir]` | Authenticate with Google OAuth (with `dir`: save tokens to `/.passwd/`) |
| `passwd-agent whoami` | Show current user |
| `passwd-agent list` | List/search secrets (`-q`, `-t`, `--json`) |
| `passwd-agent get ` | Get a secret (always redacted, no `--field`) |
| `passwd-agent totp ` | Get current TOTP code |
| `passwd-agent exec` | Run command with secrets as env vars (`--inject VAR=ID:FIELD`, stdout always masked) |
| `passwd-agent mcp-wrap` | Launch `mcp-remote` with credentials as HTTP headers (`header=ID:FIELD`) |
| `passwd-agent envs` | List known environments (`--json`) |
| `passwd-agent --env ` | Global flag: target a specific environment by name substring |

## Full CLI commands reference

The full CLI (`@passwd/passwd-cli`, binary `passwd`) has complete vault access including raw credential output. For AI agent integrations, use the agent CLI above.

| Command | Description |
|---|---|
| `passwd login [dir]` | Authenticate with Google OAuth (with `dir`: save tokens to `/.passwd/`) |
| `passwd whoami` | Show current user |
| `passwd list` | List/search secrets (`-q`, `-t`, `--json`) |
| `passwd get ` | Get a secret (redacted by default; `--field` for raw value) |
| `passwd create` | Create a secret (`-t`, `-n`, `--group`, `--user`, `--file`, `--visible-to-all`, plus type-specific flags — see `--help`) |
| `passwd update ` | Update a secret (same flags as create, plus `--remove-file`) |
| `passwd delete ` | Delete a secret (`-y` to skip confirmation) |
| `passwd totp ` | Get current TOTP code |
| `passwd share ` | Enable/revoke sharing (`--revoke`) |
| `passwd groups` | List workspace groups |
| `passwd contacts` | List workspace contacts |
| `passwd envs` | List known environments (`--json`) |
| `passwd resolve` | OpenClaw secrets provider — reads JSON from stdin, writes resolved values to stdout |
| `passwd exec` | Run command with secrets as env vars (`--inject VAR=ID:FIELD`, `--no-masking` to disable stdout masking) |
| `passwd --env ` | Global flag: target a specific environment by name substring |

## Configuration

| Variable | Required | Description |
|---|---|---|
| `PASSWD_ORIGIN` | **Yes** | Your passwd.team URL (default `https://app.passwd.team`) |
| `PASSWD_API_URL` | No | API base URL override |
| `PASSWD_

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pepuscz](https://github.com/pepuscz)
- **Source:** [pepuscz/passwd](https://github.com/pepuscz/passwd)
- **License:** MIT
- **Homepage:** https://passwd.team

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pepuscz-passwd
- Seller: https://agentstack.voostack.com/s/pepuscz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.