How EnvBox Works: Invites, Encryption and the CLI
The workflow, security choices and technology behind EnvBox, from invite tokens to the npm CLI — and why we designed it to feel like git pull for env vars.
Last updated 2026-09-25T08:51:30.964Z
The workflow
- Create an account and verify email.
- In the dashboard, create a project and add environment variables.
- Generate a one-time invite token, limited to specific environments, and share it any way you like.
- A teammate runs npx envbox-cli join <token>. EnvBox writes a local .envboxrc (API key + server URL) and adds it to .gitignore automatically.
- From then on: npx envbox-cli pull dev (or staging, or prod) fetches only the environments that person is allowed to see.
Default environments are dev, staging and prod.
Instead of this | Do this |
|---|---|
“Hey, can you send me the .env?” | npx envbox-cli join <token> |
“Is this the latest version?” | npx envbox-cli pull dev |
“Who has production access?” | Invite tokens scoped by environment |
“They left the team” | Revoke the API key |
Why a CLI, not only a dashboard
The product had to feel usable inside the repo. Opening a website every time a key changed was part of the original pain. Publishing a small CLI on npm meant:
- no global install required for a first try (npx)
- the same mental model as pulling code
- a place to encode “join once, pull often”
That choice drove a large part of the engineering work: not only the dashboard API, but how a published package talks to the server and how to test that path before trusting a publish.
Security decisions
Concern | Decision |
|---|---|
Stored variables | Encrypted at rest with AES-256-GCM; the encryption key is not stored in the database |
API keys | Stored hashed with SHA-256, the way passwords are |
Sharing access | Invite tokens are single-use and expire after 1, 6 or 24 hours |
Least privilege | Members only access environments they were approved for |
Offboarding | Access can be revoked per key or per member |
EnvBox is an MVP. It is built for small-team convenience and learning, not as a claim that it replaces a reviewed enterprise secrets program. Use it with that scope in mind.
Stack
- Dashboard: Next.js 16, TypeScript, Tailwind CSS, shadcn/ui, react-hook-form, Zod
- Back end: Next.js API routes, Better-Auth, Drizzle ORM, PostgreSQL (Neon)
- CLI: Commander.js, published on npm as envbox-cli
- Email: Resend
- Hosting: Vercel (dashboard), Neon (database), npm (CLI)
What was hard to build
Roughly three weeks went into the first usable version. The awkward parts were not only “features on a page”:
- An early design assumed a heavier REST-style boundary than we needed once the CLI and server were both under our control. That path was simplified when it became clear the problem was “package ↔ our API,” not a generic public API product.
- Shipping and testing an npm CLI — running the real join/pull flow before and after publish — took more care than the dashboard screens.
- Encryption and hashing needed time to understand why each step exists, not only which library to call. Guidance and comparisons helped, but the responsibility for the choices stayed with us.
Seventeen Vitest unit tests focus on encryption, token hashing and API key generation — the places where a silent mistake hurts most.
What we left out on purpose
The MVP does not try to be a full secrets platform. There is no push for marketing SEO on the product site, and many platform features you would expect from Doppler-class tools are simply not there yet. The bar was: we can use it daily with my brother on projects that need shared env values.
Was this page helpful?