Projects and environments

Organizations, projects, environments and keys, and how a command finds its target

The model

Thing What it is Identified by
Organization The tenant. Owns projects, members and machine identities Chosen at sign-in
Project The secrets for one codebase. Belongs to exactly one organization and has its own encryption key A slug, such as my-app
Environment One partition of a project's values A slug: dev, staging, prod
Key A secret's name, such as DATABASE_URL. Exists once per project The name itself
Value What a key holds in one environment, with its version history Key plus environment

A key carries one value per environment, so DATABASE_URL in dev and DATABASE_URL in prod are two values of one key. A few settings belong to the key rather than to a value and so apply in every environment: its expiry and its proxy hosts. Changing those needs write access to the whole project.

Organizations

Every account has a personal organization and can belong to others. Members have one of three roles:

Role Can
Owner Everything an admin can, plus transfer ownership and delete the organization. One per organization
Admin Manage members and invitations
Member Use the organization's projects, except the values of protected environments

A CLI login acts in one organization, picked when you approve the sign-in. A project in another organization is reported as not found. To switch, enveil logout and enveil login again. Owners and admins receive the organization's emails: secrets about to expire and identities that hit their read budget.

Projects

enveil init --project my-app --create creates a project in the organization your login acts in, unless one with that slug already exists. The server derives the slug from the name you pass: lowercase ASCII letters and digits, anything else turned into a hyphen, at most 48 characters. If that slug is taken it adds a suffix (my-app-2), and init writes the slug the server returned.

enveil projects lists the projects the current credential can reach.

Environments

A new project starts with three environments:

Name Slug
Development dev
Staging staging
Production prod

enveil environments lists a project's environments. Commands that work on values act on one environment at a time, so a machine identity can be scoped to my-app:dev without reaching prod.

Protected environments

A protected environment keeps its values away from people with the Member role. A member can still see what is there: enveil list and enveil history work, because they fetch no values. Everything that reads a value or changes the environment is refused: get, export, run (with or without --proxy), pull, reading an old version, set, delete, rollback, and changing a key's proxy hosts or expiry. A change that spans every environment of a project, such as deleting a key everywhere, is refused as soon as one of them is protected.

Role In a protected environment
Owner, Admin Read and change values, as in any other environment
Member List keys and history. No values, no changes

Production starts protected, in new projects and in projects created before protection existed. dev and staging start unprotected.

A refused call returns 403 with Production is protected: only admins can read or change its values, and the CLI exits with code 3, the same as a missing scope. enveil environments marks protected environments in a third column.

Admins and owners turn protection on or off per environment on the project's page in the dashboard. Each change is recorded in the audit log with who made it. There is no CLI command or API endpoint for it.

Keys

Keys end up in .env files and process environments, so they are restricted to the shape a shell accepts: 1 to 255 characters, ASCII letters, digits and underscores, starting with a letter or underscore. STRIPE_SECRET_KEY and _INTERNAL are valid; stripe-key and 2FA_SECRET are not.

.enveil.toml

enveil init writes this file in the current directory:

toml
server = "https://enveil.oxidt.com"
project = "my-app"
environment = "dev"
Field Meaning
server The enveil deployment
project The project slug
environment The environment used when -e is not given
org Optional. The organization a GitHub Actions run exchanges its OIDC token into; see CI with GitHub Actions

Commit it. It holds no secret and no token, and it is what lets everyone on the repository, and every agent, run enveil run -- … without flags.

Commands look for .enveil.toml in the current directory, then in each parent directory, and use the first one found. Running from a subdirectory of a repository, or from a package inside a monorepo, finds the file at the root.

init takes the project from --project (required), the environment from -e (default dev), and the server from --server, then ENVEIL_SERVER, then http://localhost:8080. It refuses to overwrite an existing file. enveil init --agents also appends enveil rules for coding agents to AGENTS.md and CLAUDE.md.

How a command finds its target

Every command takes -p/--project, -e/--environment and --server.

Setting Resolved from, first match wins Default
Project -p, then .enveil.toml None: the command fails and says to pass -p or run enveil init
Environment -e, then .enveil.toml dev
Server --server, then .enveil.toml, then ENVEIL_SERVER None: the command fails and says how to supply one

The file sits above ENVEIL_SERVER on purpose: a project pinned to another deployment stays pointed at it, whatever is set in your shell.

When -p names a different project

With -p, no file is needed, which is what lets a command run from any directory:

sh
enveil run -p accounts -- bunx some-mcp

That suits an MCP server launched from an unrelated repository. A .enveil.toml found there fills in the gaps only if it names the same project. If it names another project, it is ignored completely: its environment, server and org do not leak in. The environment defaults to dev and the server comes from --server or ENVEIL_SERVER:

sh
ENVEIL_SERVER=https://enveil.oxidt.com enveil run -p accounts -e prod -- ./sync.sh

Commands that need no project

login, logout, projects, whoami and identity need a server but no project, so they run anywhere. They take the server from --server, then the .enveil.toml that applies, then ENVEIL_SERVER.