secretcarousel

# SecretCarousel

[![npm version](https://img.shields.io/npm/v/secretcarousel.svg)](https://www.npmjs.com/package/secretcarousel)
[![MCP](https://img.shields.io/badge/MCP-stdio_+_SSE-blue)](https://secretcarousel.com/docs/quickstart/remote-mcp.html)
[![Zero-Knowledge](https://img.shields.io/badge/mode-zero--knowledge-8b5cf6)](https://secretcarousel.com/#security)
[![smithery badge](https://smithery.ai/badge/jyswee/secretcarousel)](https://smithery.ai/servers/jyswee/secretcarousel)

**The secret vault your coding agents run themselves — store, rotate, and hand off credentials from any agent, so they stop passing keys in plain text.**

> **git for your code. sc for your agents' secrets.**

Your agent touches credentials all day — a database URL here, an API key there — and the moment its context resets, those secrets end up pasted into a `.env` file in Slack, echoed into a log, or left in the transcript. *You* become the vault. SecretCarousel is the vault the agent runs itself: one command, and it stores secrets encrypted, rotates them on a schedule, and — the part nothing else does — hands a secret to another agent through a one-time, scoped, expiring **claim token**, even across companies. No plain-text value ever crosses the boundary.

**Works with:** Claude Code · Cursor · Cline · Windsurf · Aider · Codex · any MCP client

## Install

```bash
npm install -g secretcarousel
```

The npm package is `secretcarousel`; the command is `sc`.

Or self-provision a vault in one command — no email, no card:

```bash
npx secretcarousel signup my-project --local
```

## Quick Start

```bash
# Self-provision a tenant (API key saved to .sc/config.json)
sc signup my-project --local

# Store a secret — AES-256-GCM encrypted at rest; returns an id, never echoes the value
sc secret "DATABASE_URL" "postgres://user:pass@host/db" -t database-credentials

# Retrieve by id — decrypted on demand, access-logged
sc secret show sec-abc123

# List / search — ids + names, never values
sc secrets
sc search stripe

# Rotate now
sc rotate sec-abc123

# Full reference
sc --help
```

## Claim tokens — how agents hand off secrets

This is the part nothing else does. One agent mints a **one-time, scoped, expiring** token; another agent — different project, even different company — redeems it exactly once; the token burns; the whole exchange is audit-logged. The plain-text value never crosses the boundary as a copy-pasteable string.

```bash
# Agent A: hand a secret to another tenant/agent
sc claim "<the-secret-value>" --to partner-tenant --contract CTR-ID

# Agent B: redeem the token you were handed (once, audited)
sc claim redeem CLM-TOKEN

# List the tokens you've minted + their status
sc claims
```

No more DMing a key and hoping the other side deletes it. The token is single-use, time-boxed, and revocable, and every mint/redeem lands in the audit trail.

## Zero-knowledge mode — even we can't read it

By default, secrets are encrypted at rest with AES-256-GCM. Flip on **zero-knowledge mode** and encryption happens *on your machine, before the value ever reaches the server* — SecretCarousel stores only ciphertext and never holds the key to unlock it. A database breach leaks gibberish.

```bash
# Store a zero-knowledge secret (encrypted client-side)
sc secret "SIGNING_KEY" "$(cat key.pem)" --e2e

# Retrieve — auto-decrypts locally with your device key
sc secret show sec-def456
```

Multiple agents can share one zero-knowledge vault via an enrollment handshake — the vault key is passed device-to-device, never to the server:

```bash
sc enroll init                 # first device bootstraps the vault
sc enroll create --minutes 15  # mint an enrollment token for another agent
sc enroll redeem <token>       # joining agent unlocks the same vault
sc enroll status               # vault + local device state
```

## Rotation — set it and forget it

```bash
# Rotate immediately
sc rotate sec-abc123

# Schedule rotation with alerts
sc rotate set sec-abc123 --schedule "30d" --email ops@myproject.dev
```

## Sharing — time- and view-limited links for humans

```bash
# One-hour, single-view link a teammate can open in a browser
sc share sec-abc123 --hours 1

# List active shares
sc shares
```

## Environments — .env in, .env out

```bash
# Export a project's secrets as a .env file
sc env pull --env production > .env

# Promote secrets from one environment to another
sc env promote --from staging --to production
```

## MCP Server

Prefer tools over a CLI? `sc` ships an MCP server. Point Claude Code (or any MCP client) at it and your agent gets the full toolset — store, retrieve, list, search, rotate, share, and the claim-token handoff — with structured JSON responses.

```bash
claude mcp add secretcarousel -- sc mcp-serve
```

For clients that use a JSON config (Cline, Cursor, Windsurf), pass your API key via the `SC_API_KEY` environment variable. The MCP server runs outside your project directory, so it will not pick up `.sc/config.json`:

```json
{
  "mcpServers": {
    "secretcarousel": {
      "command": "sc",
      "args": ["mcp-serve"],
      "env": { "SC_API_KEY": "sc_your_key_here" }
    }
  }
}
```

No key yet? Start it without one — the server boots in onboarding mode with an `sc_signup` tool that provisions a vault instantly (48-hour activation window; the emailed $0 card check starts the 7-day free trial), then the full toolset unlocks in place.

### Remote MCP — zero install

No CLI at all? Claude Web, Claude Desktop, Raycast, or any hosted MCP client can connect straight to our remote server. Same toolset, same API key, nothing to install:

```
URL:  https://mcp.secretcarousel.com/sse
Auth: Authorization: Bearer sc_YOUR_API_KEY
```

Connect without the header and it starts in onboarding mode — call `sc_signup` to self-provision a vault mid-session (48-hour activation window, 7-day free trial via emailed $0 card check). Setup guide: [Remote MCP quickstart](https://secretcarousel.com/docs/quickstart/remote-mcp.html).

## Audit trail — provable, exportable

Every store, retrieve, rotate, share, mint, and redeem lands in an immutable event log. Read it from the terminal or export it for compliance.

```bash
sc audit --limit 50
sc audit export --format csv > audit.csv
```

## Features

- **Secrets** — store, retrieve, update, delete; AES-256-GCM at rest; typed (database-credentials, api-key, certificate, and more)
- **Zero-knowledge mode** — client-side encryption; the server only ever sees ciphertext, multi-device vaults via an enrollment handshake
- **Claim tokens** — hand a secret to another agent/tenant via a one-time, scoped, expiring, audited token
- **Rotation** — rotate now or on a schedule, with email alerts
- **Sharing** — time- and view-limited links for humans
- **Environments** — export as `.env`, promote secrets between environments
- **Scoped API keys** — read/write/admin per key, project-scoped
- **MCP server** — local (`sc mcp-serve`) or fully remote (`mcp.secretcarousel.com`): Claude Code, Claude Web, Cursor, Raycast, any MCP client
- **Audit trail** — immutable event log, exportable as CSV or JSON
- **Agent self-signup** — an agent provisions its own vault mid-session, no human in the loop

**Pricing:** 7-day free trial. Card required (secure Stripe checkout), nothing charged during the trial — cancel before it ends and you pay nothing. After that, from $9/mo: Starter $9 · Pro $29 · Scale $99, each with included secrets plus low overage. **Unlimited agents on every plan**, no per-seat pricing. [Details](https://secretcarousel.com/#pricing).

## Per-Project Config

```bash
sc login --local --key YOUR_KEY    # saves to .sc/config.json (project-local)
sc me                              # show tenant info + plan + usage
```

Config is per-project and auto-loaded from `.sc/config.json`. Add `.sc/` to your `.gitignore`.

## Agent Integration

Add to your CLAUDE.md, .cursorrules, .clinerules, .windsurfrules, or AGENTS.md:

```
## SecretCarousel
This project uses SecretCarousel as its secret vault.
Use the `sc` CLI. Config is in .sc/config.json (auto-loaded).
If not configured: sc login --local --key YOUR_KEY

Never paste a secret value into code, logs, or chat — store it with
`sc secret "NAME" "VALUE"` and retrieve by id at the moment of use.
To hand a secret to another agent, mint a claim token — never send the raw value.
```

## Why this exists

Every coding agent handles credentials, and every one of them eventually leaks one — into a `.env` committed by mistake, a log line, a Slack paste, a transcript that outlives the session. I wanted the agent to own its secrets the way it owns its code: a vault it runs itself, where the value is fetched only at the moment of use and handed off without ever becoming a copy-pasteable string. It's early and iterating fast — if something's rough or missing, [open an issue](https://github.com/jyswee/secretcarousel/issues).

## Documentation

- [Quickstart Guides](https://secretcarousel.com/docs/quickstart.html)
- [Full Reference](https://secretcarousel.com/llms.txt)

## License

Proprietary — Tyga.Cloud Ltd. See [LICENSE](./LICENSE).