Integrations

Rotating a credential and handing over the new one

Rotation is two jobs at once: replacing a credential, and getting the replacement to whoever needs it. Doing them in the wrong order causes an outage. Doing the handover carelessly leaves the new credential in a chat log, which defeats the point of rotating.

The vanisec-share-secret skill covers the two Vanisec tools and how to choose between them. This skill is about the sequence.

The order, and it is not negotiable

1. Create the new credential. Prefer vanisec_generate_secret, so the new value never enters this conversation. Use vanisec_create_secret only when the value has to be issued by the system that owns it (an AWS access key, a token minted by a provider console or CLI) and it is therefore already in hand.
2. Send the link and the password through different channels. Together they grant access, so splitting them is what makes the handover safe.
3. Wait for the recipient to confirm they have the new credential and that it works. The link opens once and is then destroyed. If it expired, or the wrong person opened it, go back to step 1 and issue another credential. Confirmation has to come from the recipient; there is no retrieval tool and no way to check from here whether a link was opened.
4. Only then revoke or delete the old credential.

Revoking first is the failure worth avoiding. The moment the old credential is gone, everything still using it breaks: running services, cron jobs, CI pipelines, other people's local setups. If anything then goes wrong in steps 2 or 3, nobody has a working credential at all, and the fastest way out is usually somebody pasting a secret into a chat window.

The exception is an active compromise. If the credential is known to be in the wrong hands, revoke immediately and accept the outage. Say so explicitly when you make that call, so the user knows the breakage is deliberate.

Before step 4, list what else holds the old value

A credential is rarely used in one place. Ask for or work out the full list and give it to the user before anything is revoked:

• configuration files and environment files on servers and laptops
• CI and CD variables, and repository or organisation level secrets
• secret managers and parameter stores
• running services that read the value at startup and need a restart
• container images or manifests that carry it
• scheduled jobs, monitoring integrations, third party webhooks

Anything on that list that is not updated will break at step 4 rather than at step 1, which is why the list has to exist before the revoke.

Generating the replacement

Reach for vanisec_generate_secret whenever the new value is something you are free to choose:

• database and service passwords, type: "password"
• API tokens and bearer tokens, type: "token"
• signing keys, encryption keys and webhook secrets, type: "hex"

Defaults are 24 characters for password, 32 for token and 64 for hex. Only override length when the receiving system enforces its own limit, and never downward for convenience. Set expiresIn short (1 or 6 hours) when the recipient is waiting, since a rotation handover is usually time boxed anyway.

The tool puts the link password on the system clipboard and returns only the URL. If it reports that no clipboard is available, do not fall back to pasting the credential into the conversation. See the share skill for the options.

When the provider issues the value

Some credentials cannot be generated locally. A cloud access key, an OAuth client secret, a managed database password reset by the provider: in each case the provider hands you the value, and it exists before Vanisec is involved.

Run the provider's own command or console flow, then pass the result to vanisec_create_secret. Be honest about the cost: the value is in the transcript from the moment it is passed in. Keep it out of intermediate steps where you can, for example by having the user capture the output themselves rather than printing it into the conversation.

Typical shapes of the commands involved, as illustration only. Check the provider's current documentation rather than copying these:

• Cloud access keys: create a new key for the identity, verify it, then delete the old key by its identifier.
• Managed databases: modify the instance or role with a new password, then restart or reload whatever pools connections.
• Git hosting and SaaS APIs: mint a new token with the same scopes, replace it everywhere, then revoke the previous one from the tokens page.

Never write out a value that looks like a real credential, in a command, in an example or in a summary. Refer to it by name.

Closing out

Once the old credential is revoked, confirm two things and say them plainly:

• the old value no longer authenticates anywhere
• every consumer from the list above is on the new value

If the rotation was triggered by a leak, also note where the old value was exposed, so the same channel is not used for the handover.

Self-hosting Vanisec

Vanisec is a Next.js app with Redis behind it. Redis stores ciphertext and a hash of a verifier, nothing else, so the server cannot read a secret even with full access to its own database. Self-hosting does not change the encryption model, it changes who runs the box.

Everything below is what is in the repository at https://github.com/clouddrove/vanisec. There is no separate configuration service and no database other than Redis.

Docker Compose

The fastest path. docker-compose.yml defines two services:

• redis, from redis:7-alpine, started with redis-server --appendonly yes, persisting to a named redis-data volume, with a redis-cli ping healthcheck
• app, built from the repository Dockerfile, published on port 3000, depending on Redis being healthy, with restart: unless-stopped

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

docker-compose up -d --build
docker-compose logs -f app

The app is then on http://localhost:3000.

Two things about the compose file are worth changing before it goes anywhere real:

• Redis has no password. Authentication is present but commented out: uncomment the requirepass form of the Redis command, then point the app's REDIS_URL at redis://:password@redis:6379/3, and update the healthcheck to pass -a.
• GA_ID defaults to CloudDrove's own Google Analytics measurement ID. Set GA_ID to your own, or to an empty value, unless you want to send traffic data to that property.

Other commands the repository documents:

docker-compose down       # stop
docker-compose down -v    # stop and drop the Redis volume

The container image

Prebuilt images are published to GitHub Container Registry by CI on pushes to master:

docker pull ghcr.io/clouddrove/vanisec:latest

The Dockerfile builds in three stages on node:26-alpine and produces a Next.js standalone output. The runtime stage runs as a non-root user (uid 1001, group 1001), listens on port 3000 with HOSTNAME=0.0.0.0, and starts with node server.js.

The image copies the whole source tree in the builder stage rather than listing paths, so .dockerignore is the single place that decides what stays out. If you add a root level source file, check .dockerignore rather than the Dockerfile.

Environment variables

These are the variables the application code actually reads. Anything not on this list does nothing.

REDIS_URL accepts redis://[password@]host:port[/database]. When the URL path already selects a database, REDIS_DB is ignored, so redis://host/0 is honoured rather than silently overridden.

Set NEXT_PUBLIC_BASE_URL to your own domain. Left at its default, a self-hosted instance advertises the public one in its metadata and sitemap.

TRUSTED_PROXY_HOPS deserves its own paragraph

Rate limiting identifies callers by IP, read from X-Forwarded-For. Every proxy appends to that header, so only the rightmost entries are trustworthy; anything further left came from the caller and can be forged. The app takes the Nth entry from the right, where N is TRUSTED_PROXY_HOPS.

Set too high, it reads an entry the caller controls, and one client can forge unlimited identities and walk past rate limiting entirely. Set too low, everyone behind the proxy shares a bucket and one noisy client rate limits the rest. Count your actual hops.

Kubernetes with the bundled Helm chart

The chart lives at _infra/helm/vanisec. It is a complete chart, not a skeleton: Chart.yaml (apiVersion v2, chart version 1.0.0, appVersion 1.0.0), values.yaml, and templates for the Deployment, Service, Ingress, HorizontalPodAutoscaler, ServiceAccount, and an optional embedded Redis (Deployment, Service and PersistentVolumeClaim in one file).

helm install vanisec ./_infra/helm/vanisec
helm install vanisec ./_infra/helm/vanisec -f my-values.yaml
helm upgrade vanisec ./_infra/helm/vanisec

Defaults worth knowing:

• replicaCount: 2, image ghcr.io/clouddrove/vanisec:latest
• Service is ClusterIP on port 80, targeting container port 3000
• Ingress is disabled by default. Enabling it uses className: nginx and a placeholder host, so set ingress.hosts and ingress.tls yourself.
• Autoscaling is disabled by default. Enabled, it runs 2 to 10 replicas against 80 percent CPU and memory targets.
• Pods run as uid 1001 with runAsNonRoot, all capabilities dropped, no privilege escalation, and a read only root filesystem.
• Liveness and readiness probes both hit /.

Redis, embedded or external

redis.enabled: true (the default) deploys Redis 7-alpine inside the release, with an 8Gi PersistentVolumeClaim when redis.persistence.enabled is true and an emptyDir when it is not. An emptyDir means every unopened secret is lost when the pod moves.

redis.enabled: false skips all of that, and you point env.REDIS_URL at your own Redis or a managed service. That is the right choice for anything production shaped.

The default env.REDIS_URL is redis://vanisec-redis:6379/3, which matches the embedded Redis Service only when the release is named vanisec. Install under any other release name and you have to update env.REDIS_URL to match, because the Service is named after the release.

Setting redis.password adds --requirepass to the embedded Redis and passes -a to its probes, but it does not flow into the app. Set env.REDIS_PASSWORD as well, or put the password in env.REDIS_URL, or the app will not authenticate.

Two gaps in the chart to know about

• The Deployment template renders only NODE_ENV, REDIS_URL, REDIS_PASSWORD, NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_GA_ID and GA_ID. There is no TRUSTED_PROXY_HOPS in values.yaml or in the template, so behind an ingress the app falls back to its default of 1. Add it to the template if your hop count is different.
• Secrets go into the Deployment as plain values from values.yaml, not through a Kubernetes Secret. If you set env.REDIS_PASSWORD or redis.password, it is readable in the rendered manifest and in helm get values.

A third thing to check when redis.enabled is true: the app Service selects on the chart's name and instance labels only, while the embedded Redis pods carry those same labels plus a component label. Verify the Service endpoints after install and narrow the selector if it has picked up the Redis pod.

Local development

For running from source rather than a container:

• Node.js 20.x or higher, Redis 7.x or higher
• npm install, then npm run dev, with a .env.local holding REDIS_URL and NEXT_PUBLIC_BASE_URL
• npm run build then npm start for a production build

Redis on its own is enough to develop against: docker run -d -p 6379:6379 redis:7-alpine.

Pointing the MCP server at your instance

The @clouddrove/vanisec-mcp package targets https://vanisec.clouddrove.com unless VANISEC_BASE_URL says otherwise. Set it in the env block of the client's MCP configuration:

{
  "mcpServers": {
    "vanisec": {
      "command": "npx",
      "args": ["-y", "@clouddrove/vanisec-mcp"],
      "env": {
        "VANISEC_BASE_URL": "https://vanisec.example.com"
      }
    }
  }
}

Trailing slashes are stripped, so either form works. The server posts to {base}/api/secrets and returns links of the form {base}/secret/{id}. It logs the base URL it is targeting to stderr at startup, which is the quickest way to confirm the variable took effect.

Your instance also serves the hosted MCP endpoint at POST {base}/api/mcp for clients that cannot run a local process. That endpoint offers vanisec_create_secret only and encrypts on the server, so it is not zero-knowledge; prefer the local package. The links it returns come from NEXT_PUBLIC_BASE_URL when that is set, and from the request origin otherwise, which is another reason to set it.

Operational notes

• Secret creation is rate limited to 30 per 10 minutes per IP, and the hosted MCP endpoint to 20 per 10 minutes per IP. Rate limit counters live in the same Redis instance.
• Payloads are capped: 16MB on the request body, and 12,000,000 characters of ciphertext.
• Secrets are stored with a Redis TTL matching their expiry, and retrieval is an atomic fetch and delete, which is what makes them one-time. A racing second reader gets nothing.
• Terminate TLS at your ingress or reverse proxy. Encryption happens in the browser or in the MCP client, but the link and the password still travel over the wire.
• Back up Redis only if you have a reason to. Its entire contents expire on their own, and a backup of ciphertext plus verifier hashes is of no use to anyone without the passwords.

Sharing a secret with Vanisec

Vanisec turns a secret into a one-time link. Opening the link once destroys the secret. Encryption happens on the machine running the MCP server, so Vanisec only ever stores ciphertext, never the plaintext, the password or the key.

Two tools exist. Choosing the wrong one is the mistake this skill exists to prevent.

Choose the tool before anything else

If the secret does not exist yet, call vanisec_generate_secret. It creates the value in process, shares it, and writes the link password to the system clipboard. Neither the value nor the password is ever returned to you, so neither one enters the conversation.

Call vanisec_create_secret only when the secret already exists somewhere else and the person asking already has it in hand. Rotating a database password they typed out, forwarding a key issued by a cloud console, passing on a config value from a file: those are cases where the value already exists and vanisec_generate_secret cannot produce it.

Never make up a value yourself and pass it to vanisec_create_secret. That is the same as generating it, except the value is now permanently in the transcript.

If the request is ambiguous ("send Priya a password for the staging box"), ask whether the credential already exists. If nobody has issued it yet, generate.

Why the choice matters

vanisec_create_secret takes text and password as arguments. Everything passed to a tool is part of the conversation. It is in the transcript, in whatever the client persists to disk or to a server, and in any context that is later replayed. Deleting the message does not reliably remove it. Encrypting the secret afterwards does not help, because the plaintext was already spoken.

vanisec_generate_secret never returns either value. The conversation ends up holding only a URL, which is useless on its own.

vanisec_generate_secret

password mixes letters, digits and punctuation, so it suits anything a human or a login form will accept. token is letters and digits only, which is usually what you want for API keys, bearer tokens and anything that travels through a URL or a shell. hex is lowercase hex digits, for signing keys, encryption keys and other values a system expects as raw bytes. The defaults are fine unless the receiving system imposes its own limit; do not shorten a credential for convenience.

The tool writes the link password to the clipboard before it creates the link. That ordering is deliberate: if there is no clipboard, the tool fails and no live link is left behind. It uses pbcopy on macOS, wl-copy or xclip on Linux, and clip on Windows.

If it reports that no clipboard is available, the machine is likely a container or an SSH session with no display. Do not try to work around it. Tell the user what happened and give them the two real options:

• run the MCP server somewhere with a clipboard, or
• accept vanisec_create_secret with a password they choose, understanding that the value and the password stay in the transcript.

A human operator can also set VANISEC_ALLOW_INLINE_PASSWORD=1 in their client configuration, which makes the tool return the password in the conversation instead of using the clipboard. That is their decision to make in their own config, not something to suggest as a quick fix, because it removes the protection the tool exists to provide.

vanisec_create_secret

The password must be a real password, not a hint and not something guessable from the surrounding conversation. Anyone who gets the link and guesses the password gets the secret.

Choosing expiresIn

Only 1, 6, 24, 72 and 168 hours are accepted. Any other number is rejected before the request leaves the machine. Omitting it gives 24.

• 1 when the recipient is online now and waiting.
• 6 for the same working day.
• 24 (the default) when you do not know exactly when they will look.
• 72 across a weekend.
• 168 (seven days) when the recipient is away or in a distant timezone. This is the longest the service allows, so treat it as the exception.

Shorter is better. The link is destroyed on first open, so expiry only bounds how long an unopened link stays live.

Getting the link and the password to the recipient

The link and the password together grant access. Either one alone is useless. Send them through different channels, so no single compromised inbox, chat log or screen share yields both.

For example: link in the team chat, password by phone or SMS. Or link by email, password through a voice call. Pasting both into the same thread wastes the entire design.

Tell the recipient two things: the link opens once and is then destroyed, and they should open it somewhere they can actually store the secret, not on a phone in a taxi.

There is no retrieval tool, on purpose

You cannot read a Vanisec secret from here, and no such tool will be added. A retrieved secret would land in this conversation and in the transcript, so a one-time secret would stop being one-time in any way that matters. It would also burn the link, leaving the intended recipient with nothing.

Recipients open the link in a browser and enter the password there. If someone asks you to fetch a secret for them, explain this and send them the link.

When Vanisec MCP is not connected

If neither tool is available, do not paste the secret into the conversation as a fallback. Point the user at one of these instead:

• The web UI at https://vanisec.clouddrove.com, where the secret is encrypted in the browser and never reaches the server in plaintext.
• Installing the local MCP server, which is what makes vanisec_generate_secret possible: claude mcp add vanisec -- npx -y @clouddrove/vanisec-mcp (Node 22 or newer).
• A hosted MCP endpoint exists at POST https://vanisec.clouddrove.com/api/mcp for clients that cannot run a local process. It offers vanisec_create_secret only, and it is not zero-knowledge: the secret and the password reach the server in the request body and are encrypted there. Prefer the local package wherever it can run.

Limits worth knowing

• Secret creation is rate limited to 30 per 10 minutes per IP address. The hosted MCP endpoint is limited to 20 per 10 minutes per IP.
• A create is never retried automatically. A retry of a create that actually succeeded would leave two live one-time links for one secret, and the caller would only learn of one. If a call fails, treat the outcome as unknown before trying again.