Concepts

Projects, environments, versions and teams — the four ideas that turboEnv is built out of, in one page.

There are four things to know, and they nest: a team owns projects, a project has environments, and an environment has a history of versions.

Projects

A project is one deployable thing. In practice that means one service or one site — checkout-service, marketing-site — rather than one repository or one company.

Each project has its own encryption key, so the blast radius of a compromised key is one project rather than everything you store.

The project's slug is what you pass to -p on the command line and to the project parameter over HTTP.

Environments

Every new project starts with development, staging and production. You can add others; they sort after the standard three, which are kept in deployment order rather than alphabetically so that production does not appear before staging.

Environments within a project are completely independent sets of variables. There is no inheritance and no overlay, because a value that appears in production only because somebody forgot to override it is the kind of surprise this tool exists to prevent. If two environments share a value, that value is stored twice, deliberately.

Versions

Every save writes a new version containing the complete set of variables, not a diff against the last one.

That sounds wasteful and is not: an env file is a few dozen small rows, so storing the whole thing each time costs almost nothing and buys two useful properties. A version number becomes a stable reference to an exact set of values, so you can pin one for a reproducible deploy:

turboenv run --version 12 -- ./bin/api

And comparing two versions is an ordinary comparison of two complete sets rather than a replay of a chain of deltas.

Rolling back copies an older version forward as a new one instead of deleting what came after, so history only ever grows and the rollback itself is part of the record. Each version stores who saved it and the message they left.

A version is written either from the dashboard or with turboenv push. Both require a person: the tokens that servers and CI hold can read an environment but cannot save one, so the history always has a name in it.

Teams

Projects belong to a team, never to a person. Nothing needs transferring when somebody leaves, and there is no account that becomes a single point of failure because it happens to own production. Working alone means a team of one, which costs nothing and means you never have to migrate later.

Membership is managed through Manage in the team switcher at the top of the dashboard. turboEnv stores nothing about your teammates beyond the team's identifier; the accounts themselves live in Clerk.

Roles are flat. Every member can read and edit variables, roll back, and create and revoke tokens for any of the team's projects. The only split is over administering the team itself — inviting, removing, renaming — which Clerk governs separately.

Flat access is a deliberate choice rather than a missing feature. Per-variable permissions are the part of a secrets platform that generates the most configuration and the least security, because the usual outcome is a policy nobody understands well enough to audit. Version history records who saved what, so flat access still leaves a trail.

Removing somebody from the team does not revoke credentials they created. Tokens belong to the project, which is what lets a deployment keep working after its author moves on. When somebody leaves, revoke their machine under CLI logins first, since that credential reads everything the team holds.

Encryption

Values use AES-256-GCM under a data-encryption key unique to each project. The project's encryption mode is chosen at creation and cannot be changed.

Service-managed is the default. The Worker encrypts values and wraps the project key under a master key held as a Cloudflare secret. The operator can technically decrypt those projects.

Customer-managed projects generate or import a random tenv_key_v1_… key in the browser or CLI. The project key is wrapped and values are encrypted locally; the Worker receives only ciphertext. Back the customer key up before creating the project. turboEnv has no recovery copy, so losing it makes every version permanently unreadable. Rotation rewraps the unchanged project key and does not re-encrypt history.

This protects stored values from a database, backup or instance-master-key compromise. Metadata remains visible. Hosted JavaScript, CLI and MCP clients still handle the key locally, so a compromised distributed client can capture it; customer-managed encryption is not protection from a malicious active service.