Environments

Every Culvii tenant has three environments: dev, sandbox, and prod. They are fully isolated from each other.

Environment	What it's for
dev	Iteration. The target of culvii dev. Use it to write code, watch it run, fix bugs, repeat.
sandbox	Pre-production. Run integration tests with realistic data and real external services. Used by your team and your CI.
prod	Production. Real triggers, real data, real consequences. Deploy here only after sandbox is green.

What "isolated" means

Each environment is backed by its own database. There is no cross-environment query. A workflow deployed to dev does not exist in sandbox until you explicitly deploy it there. An API key issued for prod does not work against sandbox.

This means three things:

• Versioning is per-environment. A workflow can be at v3 in dev, v2 in sandbox, and v1 in prod simultaneously. Each culvii deploy creates a new version in the target environment only.
• Workspaces are per-environment. A workspace named procurement in dev is a different workspace from procurement in prod. They share a name; nothing else.
• Access is per-environment. A team member can be granted access to specific workspaces in specific environments. A developer might have access to three workspaces in dev, one in sandbox, and none in prod.

How the CLI knows which environment to target

The CLI reads the active environment from your local config (~/.culvii/config). You can also override it per command with --env:

culvii deploy quote-review.ts --env sandbox --workspace procurement

For culvii dev, the environment is always dev. You cannot live-sync against sandbox or prod, intentionally — those are not iteration environments.

API keys are environment-scoped

API keys carry a prefix indicating their environment:

Environment	Prefix	Example
dev	ck_dev_	ck_dev_a3f9b8e6c2d4...
sandbox	ck_sandbox_	ck_sandbox_a3f9b8e6c2d4...
prod	ck_prod_	ck_prod_a3f9b8e6c2d4...

When the SDK initializes via initConfig, it infers the target environment from the key prefix. There is no separate --env flag to forget.

See Authentication for the full key model.

Promoting code through environments

Promotion in Culvii is just redeploying the same source file to a different environment:

culvii deploy quote-review.ts --env dev      --workspace procurement
culvii deploy quote-review.ts --env sandbox  --workspace procurement-uat
culvii deploy quote-review.ts --env prod     --workspace procurement

Each deploy creates an independent version record in that environment. Three deploys mean three separate records.

Workspace names can differ across environments — sandbox might use -uat suffixed workspaces, for example. The CLI doesn't infer this; you specify the target workspace explicitly in each command.

What about CI/CD?

Promotion to sandbox and prod is usually wired through CI. The pattern most teams use:

• A merge to main triggers culvii deploy --env sandbox.
• A manual workflow dispatch with env=prod triggers culvii deploy --env prod.

The CLI authenticates in CI via an API key, not via OAuth. You provision a ck_sandbox_ key for the sandbox pipeline and a ck_prod_ key for the prod pipeline; each lives in the corresponding GitHub Environment (or equivalent) as a secret.

See How-to → Set up CI/CD for culvii deploy for a worked example.

What's not promotable

In v1, promotion is per-resource (workflow, agent). There is no culvii workspace promote that bulk-moves everything. You ship the code; the workspace structure is provisioned independently.

That's intentional. Workspace shape is an operational decision (workflow ownership, access boundaries) and shouldn't be coupled to source-controlled artifacts.