Getting Started

What is Tokengate?

Tokengate is an end-to-end encrypted environment variable manager for development teams. It replaces insecure practices like sharing .env files over Slack, email, or password managers with a purpose-built CLI and web dashboard.

Every environment has its own encryption password. Secrets are encrypted on your machine before they ever leave it. The Tokengate server stores only ciphertext and can never read your plaintext values. This is true zero-knowledge architecture.

How It Works

Tokengate uses a layered encryption model built on Web Crypto API standards:

• Each workspace has a workspace key (AES-256) generated at creation time
• The workspace key is wrapped per-device using RSA-OAEP 2048-bit key pairs
• Revision data is encrypted with a random per-revision data key (AES-256-GCM)
• Each data key is wrapped by the workspace key using AES-KW
• Content integrity is verified with SHA-256 content hashes

The result: your secrets are encrypted client-side, transmitted as ciphertext, and stored as ciphertext. Only devices with the workspace key can decrypt them.

Quick Start

Installation

The Tokengate CLI is distributed as an npm package. Install it globally so the tokengate command is available everywhere.

With Bun (recommended)

With npm

Verify Installation

CLI Commands

Configuration

Tokengate uses two configuration files: a project config in your repository and a global config on your machine.

.tokengate.json (Project Config)

Created by tokengate init in the root of your project directory. This file should be committed to version control so all team members share the same project and environment mappings. It does not contain any secrets.

Global Config

Stored at ~/.config/tokengate/config.json with file permissions 0600 (owner read/write only). This file contains your device credentials and should never be shared or committed to version control.

Environment Variables

Multi-file Sync

Most projects use multiple .env files for different purposes: .env for shared defaults, .env.local for developer overrides, .env.production for production secrets. Tokengate handles all of them in a single workflow.

File Scanning

When you run tokengate init or tokengate push, the CLI scans the current working directory for files matching the pattern .env or .env.*. This includes files like:

• .env - default environment variables
• .env.local - local developer overrides
• .env.development - development-specific variables
• .env.staging - staging environment variables
• .env.production - production secrets
• .env.test - test environment variables

Any file in the working directory that matches the /^\.env(\..+)?$/ regex pattern will be discovered. The scan is non-recursive and only checks the top-level directory.

Environment Mapping

During tokengate init, each discovered file is mapped to a remote environment within your project. A single environment can only be mapped to one local file. These mappings are stored in the .tokengate.json file and persist across push/pull operations.

If you add a new .env file later, run tokengate init again to add the new mapping. Your existing mappings are preserved.

Change Detection

Tokengate uses SHA-256 content hashing to detect changes efficiently. When you push, the CLI computes a hash of each local file and compares it to the content hash stored on the remote revision. Only files with different hashes are uploaded, saving bandwidth and avoiding unnecessary revisions.

The same mechanism works in reverse during pull: the CLI compares the remote content hash to a hash of your local file and only downloads files where the remote has changed.

Push/Pull Workflow

The typical workflow is straightforward:

1. Edit your local .env files as needed
2. Run tokengate push to upload changes
3. Team members run tokengate pull to get the latest
4. Use tokengate status to check sync state at any time

Encryption

Tokengate implements a layered encryption architecture designed so the server never has access to plaintext secrets. All cryptographic operations use the Web Crypto API, a battle-tested standard available in all modern runtimes.

Workspace Key Model

Each workspace has a 256-bit AES workspace key generated at creation time. This key is the root of the encryption hierarchy and never leaves client devices in plaintext. When a new device is registered, the workspace key is wrapped (encrypted) using the device's RSA-OAEP 2048-bit public key, and the wrapped copy is stored on the server.

When the CLI needs the workspace key, it downloads the wrapped copy and unwraps it locally using the device's private key (which is stored only in ~/.config/tokengate/config.json).

Per-Revision Encryption

Each time you push a revision, the following process occurs entirely on your machine:

1. A random 256-bit data key is generated for this specific revision
2. A random 96-bit IV (initialization vector) is generated
3. Your env file content is encrypted using AES-256-GCM with the data key and IV
4. The data key is wrapped using the workspace key via AES-KW (Key Wrap)
5. A SHA-256 content hash of the plaintext is computed for change detection
6. The ciphertext, wrapped data key, and content hash are uploaded to the server

Zero-Knowledge Architecture

The Tokengate server stores only:

• Encrypted ciphertext (AES-256-GCM output)
• Wrapped data keys (AES-KW output, only useful with the workspace key)
• Content hashes (SHA-256 of plaintext, used for change detection only)
• Wrapped workspace keys (RSA-OAEP output, one per device)

The server never sees your plaintext secrets, the workspace key in unwrapped form, or any per-revision data keys. Even with full database access, an attacker cannot decrypt your secrets without the RSA private key stored on an authorized device.

Recovery

When a workspace is created, a recovery phrase is generated from the raw workspace key using Base32 encoding. This phrase allows restoring workspace access if all devices are lost. Store it securely offline. The recovery phrase is shown once during workspace creation and cannot be retrieved again.

Web Dashboard

The Tokengate web dashboard at tokengate.dev/dashboard provides a visual interface for managing your workspaces, projects, environments, and secrets. It complements the CLI for tasks that benefit from a graphical UI.

Workspace / Project / Environment Hierarchy

Tokengate organizes secrets in a three-level hierarchy:

• Workspace - the top-level container, typically one per organization or team. Each workspace has its own encryption key and member list.
• Project - a logical grouping within a workspace, usually mapping to a single code repository or service.
• Environment - a named set of secrets within a project, such as "default", "local", "staging", or "production". Each environment maps to one .env file.

Unlocking Environments

Environments are locked by default in the dashboard. To view or edit secrets, you must unlock the environment by providing the workspace credentials. The decryption happens entirely in your browser using the Web Crypto API. The plaintext is never sent to the server.

Key-Value Editor

Once unlocked, the dashboard presents a spreadsheet-style key-value editor where you can add, edit, or remove individual environment variables. Changes are encrypted and saved as a new revision when you click save. The editor highlights which keys have been modified since the last revision.

Revision History

Each environment maintains a complete revision history. You can view past revisions, see when they were created, and identify which team member pushed each change. This provides a full audit trail for secret changes across your team.

Team Workflows

Tokengate is designed for teams. Multiple developers can push and pull secrets from the same project without stepping on each other's work.

Sharing Environments

To give a team member access to a project's secrets:

1. Add them to the workspace via the web dashboard
2. They install the CLI and run tokengate login to register their device
3. The workspace key is automatically wrapped for their device's public key
4. They clone the repo (which includes .tokengate.json) and run tokengate pull

Because .tokengate.json is committed to version control, new team members automatically get the correct project and environment mappings. They only need to authenticate their device once.

Conflict Detection

Tokengate uses revision numbers to detect conflicts. Each environment has a monotonically increasing revision counter. When you push, the CLI sends the expected revision number. If another team member pushed in the meantime, the server rejects the push and you must pull first to get the latest changes.

This optimistic concurrency model prevents accidental overwrites while keeping the workflow simple. In practice, environment variable changes are infrequent enough that conflicts are rare.

Recommended Team Setup

1. One person creates the workspace via the web dashboard and saves the recovery phrase securely
2. Add team members to the workspace through the dashboard
3. Initialize the project with tokengate init and commit .tokengate.json to your repository
4. Add .env* to .gitignore to prevent accidental commits of secret files
5. Each developer runs tokengate login once, then tokengate pull after cloning the repo
6. Push changes after updating secrets locally, and communicate significant changes to the team

SDK (@tokengate/env)

The @tokengate/env SDK gives you type-safe, validated environment variables with zero-knowledge encryption. Define a schema, and the SDK fetches, decrypts, validates, and types your variables automatically.

Define a Schema

Create tokengate.config.ts in your project root:

Use in Your App

Schema Types

Sources Priority

Variables load from these sources in order (first match wins):

1. Cloud — Tokengate API (E2E encrypted, decrypted locally via TOKENGATE_PASSWORD)
2. File — Local .env file
3. Process — process.env

Generate Types

Next.js Integration

Wrap Your Config

Variables prefixed with NEXT_PUBLIC_ are automatically exposed to client-side code. All others are server-only.

Server Components / API Routes

Vite Integration

Add the Plugin

Variables prefixed with VITE_ are exposed to client code via import.meta.env. All variables are available in process.env during SSR/build.

Secret Scanning

Tokengate can scan your codebase for accidentally hardcoded secret values. It reads your mapped .env files, extracts the values, and searches all source files for matches.