Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.capy.sc/llms.txt

Use this file to discover all available pages before exploring further.

Capy works with Next.js across every runtime (Node, Edge) and every deploy target (Vercel, self-hosted). Wrap next dev and next build with capy run and read process.env as you always have.
1

Install the CLI

brew install capysc/tap/capy
Also add it as a dev dependency so your deploy platform installs it during builds:
bun add -D @capy/cli
2

Sync your secrets

From a project that has a .env:
capy
Capy authenticates you, creates a project on first run, encrypts every value in .env, and gitignores the file. Only keep.lock (a small versioning manifest) is committed.
3

Wrap dev and build in package.json

{
  "scripts": {
    "dev": "capy run -- next dev",
    "build": "capy run -- next build",
    "start": "capy run -- next start"
  }
}
bun run dev / npm run dev / pnpm dev all work as usual. capy run decrypts .env in memory and hands plaintext values to Next via process.env. Both Node and Edge routes read them the standard way:
const db = process.env.DATABASE_URL;
4

Invite a teammate

capy invite teammate@example.com
Capy prints a one-line redeem code. Send it out-of-band. They run capy redeem <code> and now share access.
5

Deploy to Vercel

Run:
capy deploy
Pick Vercel. Capy prints two environment variables - SECRETS_BLOB and PROJECT_KEY - to paste into your Vercel project’s Settings → Environment Variables (or vercel env add). Repeat for Preview / Development if you want Capy to decrypt there too.Next, point next.config.js at Capy’s auto-generated env map:
const capyEnv = require("./.capy/next-env");

module.exports = {
  env: capyEnv,
};
That’s it. On every vercel deploy:
  1. Vercel clones your branch, installs @capy/cli, runs capy run -- next build.
  2. capy run sees SECRETS_BLOB + PROJECT_KEY, enters deployed mode, calls Capy’s service to reconstruct the decrypt key, expands the blob into individual env vars, and writes .capy/next-env.js listing them.
  3. next build runs with plaintext env vars set, and Next inlines every variable named in the env field as a string literal in the compiled bundle.
  4. Runtime functions (Node and Edge) read the inlined literals. No runtime decryption, no service call per request.
Add a secret to .env, run capy, redeploy - Next picks it up automatically from the regenerated next-env.js. No next.config.js churn.

​
Edge vs. Node routes

Both work the same way. Capy values land in process.env at build time via Next’s env config, and Next replaces process.env.X references with string literals during compilation. The resulting code has no runtime env lookup, so it runs identically in Node and Edge isolates.

​
App Router, Pages Router, Middleware

All three read from process.env the standard way. No Capy-specific imports, no initialization call, no runtime library. The only Capy touchpoint in the Next codebase is the two lines in next.config.js.

​
Self-hosted Next.js

Skip the next.config.js change and the Vercel env vars. Just set capy run as the process entrypoint: 
capy run -- next start
In this mode capy run decrypts via the local keyring (dev) or a locally-present SECRETS_BLOB + PROJECT_KEY (containers, long-running servers where you’ve set those manually).

​
What’s next

Deploying

Other platforms, CI/CD patterns, revocation.

capy run

Local and deployed modes in detail.