valetkey

<p align="center">
  <img src=".github/assets/valetkey.png" width="120" alt="valetkey" />
</p>

<h1 align="center">valetkey</h1>

<p align="center"><sup>(Pronunciation: /ˈvæleɪ kiː/)</sup></p>

<p align="center">
  Signed-in dev sessions for coding agents, without handing over credentials.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/valetkey"><img alt="npm version" src="https://img.shields.io/npm/v/valetkey?color=fbbf24&labelColor=101828&label="></a>
  <a href="https://github.com/firatciftci/valetkey/actions/workflows/ci.yml"><img alt="ci status" src="https://img.shields.io/github/actions/workflow/status/firatciftci/valetkey/ci.yml?branch=main&label=ci&labelColor=101828"></a>
</p>

<p align="center">
  <a href="https://valetkey.dev">Documentation</a> · <a href="https://valetkey.dev/getting-started/">Getting started</a> · <a href="https://valetkey.dev/reference/mcp/">MCP tools</a> · <a href="./docs/spec.md">Spec</a>
</p>

<br>

Claude Code, Codex, Cursor, and other coding agents work on the app you are building as a signed-in user (admin, free user, org member) while passwords, secret keys, and magic links stay with you. valetkey mints real sessions from your app's auth layer and hands the agent only a short-lived, origin-pinned session artifact.

A valet key starts the car and drives it, but opens neither the trunk nor the glovebox. Same idea.

<p align="center">
  <img src=".github/assets/flow.svg" width="840" alt="Your app's auth mints through valetkey. Credentials stop at valetkey; the agent's browser receives only a short-lived session artifact." />
</p>

## Quick start

<pre align="center">npx <b>valetkey init</b></pre>
<p align="center">create a user your agent can become</p>
<pre align="center">valetkey <b>persona add</b> admin</pre>
<p align="center">sign the managed browser in</p>
<pre align="center">valetkey <b>login</b> admin --browser</pre>

The next page load is signed in as admin, and `valetkey login free-user` makes the same window the other user. To let the agent do this itself, register the MCP server (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor, `~/.codex/config.toml` for Codex):

```json
{
  "mcpServers": {
    "valetkey": { "command": "npx", "args": ["valetkey", "mcp"] }
  }
}
```

The agent calls `valetkey_login_as` with any persona and browses your app signed in. No tool response ever carries a credential value.

There is also an official agent skill, so your agent knows how to use all of this without being told:

<pre align="center">npx skills add <b>firatciftci/valetkey</b></pre>
<p align="center">or, in Claude Code, the skill and the MCP server together</p>
<pre align="center">/plugin marketplace add <b>firatciftci/valetkey</b></pre>

## How it works

1. You define the app and its auth provider in `valetkey.config.ts`, committed to your repo. `valetkey persona add admin` creates the users your agent can become: profiles in a committed JSON file, credentials in the vault.
2. Provider secrets live in `.valetkey/vault.age`, an age-encrypted vault that is also committed. Each teammate has an identity keypair in their OS keychain; adding a teammate is one `valetkey team add` away, and nobody ever pastes a secret into a chat.
3. `valetkey login admin` calls your auth layer server-side and mints a session, clamped to a short TTL and pinned to your configured dev origins. Production-looking origins and live keys are refused outright.
4. The session reaches your agent either way you like: injected live into a Chrome profile valetkey manages, or written as a Playwright storage-state file (`valetkey login admin --export playwright/.auth/admin.json`). Agents can do it themselves through the MCP server.

## Packages

| Package                 | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `valetkey`              | The CLI, and the `defineConfig` entry point for your config file       |
| `@valetkey/core`        | Personas, encrypted vault, session artifacts, guardrails, audit log    |
| `@valetkey/cdp`         | The managed Chrome profile and live session injection                  |
| `@valetkey/mcp`         | MCP server so agents sign themselves in                                |
| `@valetkey/custom`      | Provider plugin for homegrown auth: bring your own mint function       |
| `@valetkey/record`      | Provider plugin: sign in once by hand, valetkey captures the session   |
| `@valetkey/better-auth` | Provider plugin for Better Auth apps: sign-in, seeding, verify, revoke |
| `@valetkey/authjs`      | Provider plugin for Auth.js v5: local JWT minting, database sessions   |
| `@valetkey/supabase`    | Provider plugin for Supabase: passwordless admin magic-link minting    |
| `@valetkey/clerk`       | Provider plugin for Clerk: sign-in tokens redeemed in the browser      |
| `@valetkey/firebase`    | Provider plugin for the Firebase Auth Emulator: unsigned-token minting |

## See it whole

[`examples/`](examples) holds six small Vite React apps sharing one shell, so the only thing that differs between them is the auth layer: [`better-auth`](examples/better-auth), [`authjs`](examples/authjs), [`supabase`](examples/supabase), [`clerk`](examples/clerk), and [`firebase`](examples/firebase) each use their dedicated plugin, and [`custom`](examples/custom) signs into hand-rolled session auth with a mint function a dozen lines long. Each README is a five-minute walkthrough, and CI drives both with the real CLI on every push.

## Security model, honestly

valetkey guarantees that root credentials (provider secret keys, passwords, JWT secrets) never enter your agent's context, and no MCP tool response carries a cookie or token value. The session the agent can use is still a credential: valetkey makes it short-lived, dev-only, origin-pinned, revocable, and audited (`valetkey audit`), but a compromised agent is not harmless. Keep untrusted content away from agents holding sessions.

Every credential inside valetkey is a `Secret` object that renders as a placeholder when logged and throws on `JSON.stringify`. The raw value takes a deliberate `reveal()` call, restricted by lint to a declared list of boundaries where a credential genuinely has to leave. The [security model](https://valetkey.dev/security/) page spells out the rest, including what valetkey cannot protect you from.

## Status

Early development. Working today: personas, the encrypted team vault, session minting, Playwright storage-state export, a managed Chrome profile with live session injection, an MCP server, the header proxy for authenticated API calls, the `record` provider for signing in once by hand, and first-party Better Auth, Auth.js, Supabase, Clerk, and Firebase plugins. The [roadmap](https://valetkey.dev/roadmap/) tracks the rest, and [the spec](docs/spec.md) holds the full design.

## Contributing

Provider plugins, bug reports from real dogfooding, and documentation fixes are the most useful things right now. [CONTRIBUTING.md](CONTRIBUTING.md) covers the setup, the check chain, and the invariants worth knowing before you touch the credential path. Participation follows the [Code of Conduct](CODE_OF_CONDUCT.md).

Found a security problem? Report it privately through [the Security tab](https://github.com/firatciftci/valetkey/security/advisories/new), not a public issue. [SECURITY.md](SECURITY.md) covers what is in scope and what is a documented property rather than a bug.

## License

[MIT](LICENSE)