Going to production

Transition from local device-based auth to production environment variables for CI/CD and hosting platforms

Local development uses device-based authentication — each developer is uniquely identified via npx stash init. Production and CI/CD environments don't have a physical device or interactive login, so they use environment variables instead.

How auth differs between environments

Environment	Auth mechanism	How it works
Local development	Device-based	`npx stash init` creates a device and client key. No env vars needed.
CI/CD pipelines	Environment variables	Application client key identified by `CS_CLIENT_ID` and `CS_CLIENT_KEY`.
Production hosting	Environment variables	Same as CI/CD. Application client keys have keyset access without a device.

Setting up production credentials

Create an application client key

In the CipherStash Dashboard, navigate to Clients and create a new client key.

This is an application client key — it has no device attached and is identified solely by its client ID and key.

Save the Client ID and Client Key. The client key is shown only once.

Create an access key

Navigate to Access Keys and create a new access key.

Use the member role for production workloads. This follows the principle of least privilege and only allows encrypt/decrypt operations.

Role	Use case
Member	Application workloads — encrypt, decrypt, list keysets
Control	Infrastructure automation — manage keysets and client keys
Admin	Full access. Not recommended for production.

Save the access key. It is shown only once.

See Access keys for details on roles and scopes.

Grant keyset access

Ensure the application client key has access to the appropriate keyset(s).

By default, new client keys are granted access to the default keyset. For multi-tenant deployments, grant access to specific keysets as needed.

See Keysets for details on managing keyset access.

Set environment variables

In your hosting platform or CI/CD system, set the following environment variables:

CS_WORKSPACE_CRN=crn:region.aws:your-workspace-id
CS_CLIENT_ID=your-application-client-id
CS_CLIENT_KEY=your-application-client-key
CS_CLIENT_ACCESS_KEY=your-access-key

These four variables are required for all CipherStash products (Encryption SDK, Secrets, and Proxy) in production.

Set a writable config path (if needed)

In serverless or containerized environments, the default config directory may not be writable. Set CS_CONFIG_PATH to a writable location:

CS_CONFIG_PATH=/tmp/.cipherstash

This has been tested on Vercel, AWS Lambda, and Docker containers.

CI/CD pipeline examples

GitHub Actions

env:
  CS_WORKSPACE_CRN: ${{ secrets.CS_WORKSPACE_CRN }}
  CS_CLIENT_ID: ${{ secrets.CS_CLIENT_ID }}
  CS_CLIENT_KEY: ${{ secrets.CS_CLIENT_KEY }}
  CS_CLIENT_ACCESS_KEY: ${{ secrets.CS_CLIENT_ACCESS_KEY }}

Docker

CS_WORKSPACE_CRN=crn:region.aws:your-workspace-id
CS_CLIENT_ID=your-application-client-id
CS_CLIENT_KEY=your-application-client-key
CS_CLIENT_ACCESS_KEY=your-access-key

services:
  app:
    env_file:
      - .env.production

Never commit .env.production or any file containing credentials to version control. Add it to your .gitignore.

Avoid using environment variables locally

Setting CS_* environment variables for local development is an anti-pattern.

Device-based auth provides:

Per-developer identity — audit trails show who performed each operation
No shared secrets — each developer has their own device credentials
Automatic session management — no manual credential rotation

If you have CS_* variables in a local .env file, remove them and run npx stash init instead.

Bundler configuration

Production deployments often require bundler configuration to ensure @cipherstash/stack is not bundled with your application code. See Bundling for setup instructions for Next.js, webpack, esbuild, and SST.

Next steps

Bundling for production — Configure your bundler for deployment
Deploying Proxy to AWS ECS — Run CipherStash Proxy in production
Access keys — Understand access key roles and scopes
Team onboarding — Set up per-developer access for your team

Going to production

On this page