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.

Running capy deploy generates a double-wrapped deploy token - half lives with your platform, half lives with the Capy service, and the service never sees your master key. At build or boot time your app presents its half to the service to reconstruct the project key in memory.

​
The flow

capy deploy
  1. Capy opens a setup page in your browser.
  2. You pick the platform you’re deploying to.
  3. The CLI generates a fresh deploy token, wraps your project key with it, and registers the outer-wrapped blob with the Capy service.
  4. The setup page shows you the exact environment variables - SECRETS_BLOB and PROJECT_KEY - to paste into your platform’s secret store.
You paste those into the platform’s UI (or its CLI equivalent), redeploy, and capy run decrypts them at build or boot time.

​
What gets injected

Two env vars on your platform:
  • SECRETS_BLOB - base64 of the deploy ID, the service-held outer blob, and the encrypted env map. Self-contained.
  • PROJECT_KEY - hex-encoded 32-byte project key. Never traverses the wire.
At build or boot time, capy run detects both vars, sends the outer blob to the Capy service (the service verifies the deploy token isn’t revoked and returns a derived service key), combines it with PROJECT_KEY locally to reconstruct the decrypt key, and decrypts the env map in process memory. See Cryptography → Deploying for the exact construction.

​
Two deployment patterns

PatternWhen to useHow it works
Runtime entrypointLong-running servers (Fly, Railway, Render, Heroku), containers (Docker, Kubernetes)capy run -- <your command> is the process entrypoint. Decrypts at boot, serves forever.
Build-time inlineServerless / Edge (Vercel, Cloudflare Workers, AWS Lambda)capy run -- <framework build> in the build step. Values baked into the compiled bundle as string literals.
The split is dictated by whether you control the process entrypoint. Platforms that invoke your handler directly (serverless, Edge) don’t let you wrap with capy run at request time, so you decrypt at build and inline the results.

​
Revocation

Deploy tokens can be revoked server-side. A revoked token stops bootstrapping new builds or cold starts immediately. Any process that has already resolved the project key keeps serving traffic until it recycles - Capy caches the resolved key for the life of the process. Practical timing:
  • Long-running servers - revocation propagates on next deploy or restart.
  • Containers (Fly, Kubernetes, Docker) - propagates on the next image build or pod cycle.
  • Edge / serverless isolates - propagates as isolates recycle (seconds to minutes under load, longer when idle).
For “revoke right now, no grace period” semantics, rotate the project key instead of revoking the deploy token - any in-memory caches become cryptographic garbage.

​
Platform walkthroughs

Vercel

Next.js + Vercel with build-time env inlining.

Cloudflare Pages / Workers

Framework build on Pages, Workers via build-time inline.

Docker

capy run as the container entrypoint.

Fly.io

Machines + flyctl secrets set.

Railway / Render / Heroku

Long-running hosts with capy run in the start command.

GitHub Actions

Wrap build steps with capy run in CI.

AWS Lambda

Container-image Lambdas and zip-deploy patterns.

​
What’s next

capy deploy (CLI reference)

Command flags and flow details.

Cryptography

The deploy token double-wrap in full.