Skip to content
VelerionVelerion Docs

Workspaces & Environments

A workspace is the tenancy boundary: members, billing, quotas and audit history all belong to exactly one workspace. An environment is a deployment target inside a workspace. Environments share the workspace member list but never share secrets, connections or deployed revisions.

Section titled “Recommended layout”
acme-platform            (workspace)
├── dev                  ephemeral, permissive, low quotas
├── staging              production-shaped, synthetic data
└── prod                 locked down, change-controlled

Most teams need nothing more than this. Create additional environments only when you need a genuinely separate quota or secret scope — for example a sandbox environment shared with an external partner.

Promoting a revision

Section titled “Promoting a revision”

Agent revisions are immutable and promoted by reference, never rebuilt per environment. This is what makes a staging sign-off meaningful.

Terminal window
# Build once, in dev.
velerion deploy --env dev --agent support-triage


# Promote the exact revision that passed review.
velerion promote --agent support-triage --from dev --to staging
velerion promote --agent support-triage --from staging --to prod

Environment configuration

Section titled “Environment configuration”

Configuration is resolved in three layers, later layers winning:

  1. Values committed in velerion.config.ts.
  2. Environment-level overrides set in the Console or with velerion env set.
  3. Secret references resolved at cold start from the workspace secret store.
velerion.config.ts
export default {
  agent: 'support-triage',
  model: 'claude-opus-5',
  environments: {
    dev: { maxConcurrency: 2, tracing: 'verbose' },
    staging: { maxConcurrency: 8, tracing: 'sampled' },
    prod: { maxConcurrency: 64, tracing: 'sampled' },
  },
};