Skip to main content

culvii deploy

Deploy agents, workflows, and surfaces to sandbox or prod.

Synopsis​

culvii deploy --env <env> --workspace-slug <slug>

Description​

Evaluates all *.culvii.ts files in the current directory, computes a diff against what's currently deployed in the target workspace and environment, displays the plan, then applies it.

Both --env and --workspace-slug are required - there is no implicit fallback to config. This is intentional: deploy is a consequential operation and the target must always be explicit.

Not for dev: use culvii dev for local iteration. culvii deploy --env dev is rejected.

Accepts an OAuth session. The plan is signed with a short-lived token; apply must follow within the token's expiry window.

Flags​

FlagRequiredDescription
--env✓Target environment: sandbox or prod.
--workspace-slug✓Workspace slug shown in Culvii Console.

Plan display​

tenant: culvii-dev | workspace: payments-sandbox | env: sandbox
Plan for sandbox:
+ payment-processor CREATED
~ invoice-router VERSIONED (42 total, active v3: 5 executions)
- old-classifier DELETE (0 total, active v1: 0 executions)
- old-classifier: deletes all 1 version; active is v1

Changing an agent's id in code is a delete-and-recreate, not a rename. The old slug shows as DELETE and the new one as CREATED - a new UUID, execution history not carried over. Use culvii rename to rename an agent while preserving its UUID and execution history.

Version activation​

Applying a deploy creates a new immutable version in the target workspace and activates it, while deactivating the previous active version. For workflows with already-active poll or webhook triggers, the platform automatically transfers those active triggers to the new version when the trigger step ID is preserved.

Limits​

  • Per-resource limit: Each individual agent, workflow, or surface definition must be under 5 MiB.
  • Total payload limit: The combined deploy plan payload must be under 20 MiB.
  • Compression: Payloads over 512 KiB are automatically gzip-compressed.

Examples​

# Deploy to sandbox
culvii deploy --env sandbox --workspace-slug payments-sandbox

# Deploy to prod with destructive changes
culvii deploy --env prod --workspace-slug payments

Error behaviour​

ConditionMessageExit
--env dev"Use culvii dev for local iteration"1
--env not sandbox or prod"Environment must be sandbox or prod"1
--workspace-slug not provided"--workspace-slug <slug> is required for deploy. Run culvii workspace list."1
Workspace slug not found"Workspace not found: <slug>"1
Dangling secondary agent ref"Deploy failed: agent <slug> references <ref> which is not defined."1
Surface validation issues"Deploy failed: surface <slug> has validation issues."1
Workflow tool on secondary agent"Deploy failed: workflow tool cannot be used on secondary agent."1
Workflow tool target depth"Deploy failed: workflow tool target cannot exceed 3-node depth when containing core.agent."1
Unpinned local surface missing"Deploy failed: unpinned local surface missing."1
Deploy lock held"Deploy already in progress"1
Network drops between plan and apply, or mid-request"Error: Network or unexpected error: <message>." Since plan and apply are separate calls, a drop here doesn't leave a partial deploy - rerun culvii deploy, which recomputes a fresh plan against current state. If enough time passed that the plan token expired, apply is rejected outright and you just get a new plan on retry.1
Single resource definition over 5 MiB"Deploy failed: <type> '<slug>' definition is <size>, which exceeds the 5.00 MiB per-resource limit."1
Deploy plan payload too large (413)"Error: Failed to plan deploy. <reason> — Payload size: <size> across <N> definition(s) (largest: ...)."1