Enterprise Environments

Separate DEV, UAT, and PROD workspaces so an experiment can never answer a real customer. Promotion moves a tested configuration forward with an audit trail instead of a copy-paste.

Why separate workspaces

A Katexs workspace owns everything an agent touches: prompts, tools, numbers, keys, contacts, and logs. Environments are ordinary workspaces linked by a promotion path, which means isolation is real rather than a flag on a shared record.

• Blast radius — A bad prompt in DEV cannot reach a production number, because the number does not exist there.
• Credential separation — Each environment holds its own integration keys, so a sandbox CRM stays sandboxed.
• Clean data — PROD reporting is never polluted by test calls, so answer rate and cost per outcome mean something.
• Access control — Engineers can own DEV outright while PROD publishing stays with a small group.

The three environments

Set environments up

1. 1

   Create the workspaces

   Settings → Workspaces → New. Name them with a consistent suffix, such as Katexs — DEV, Katexs — UAT, Katexs — PROD.

2. 2

   Link the promotion path

   In each non-production workspace, set Promotes to. This enables the Promote action and the diff view.

3. 3

   Assign roles

   Grant publish rights in PROD to owners and release managers only. Everyone else gets read plus test.

4. 4

   Scope the keys

   Issue separate API keys per environment and name them for the environment. Never reuse a PROD key in CI.

5. 5

   Seed fixtures

   Load the same contact and order fixtures into DEV and UAT so test scenarios behave identically.

The promotion flow

Promotion moves a published version of an Agent, Team, or Flow — together with its prompts, tools, knowledge base bindings, and test suite — into the next environment. It never moves numbers, credentials, contacts, or logs.

DEV                UAT                     PROD
build ──publish──▶ review diff ──approve──▶ publish (versioned)
                   run test suite            canary %  ──▶ 100%
                   sign-off required         rollback = republish prior version

Promote from CI

curl -X POST https://api.katexs.com/v1/promotions \
  -H "Authorization: Bearer $KATEXS_UAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "agent",
    "resource_id": "agt_7d11c9",
    "version": 42,
    "target_workspace": "ws_prod_2f8a",
    "require_passing_suite": "suite_regression_core",
    "note": "Adds insurance capture to intake"
  }'

With require_passing_suite set, the promotion is rejected unless that suite passed against the exact version being promoted. This is the single most effective guard against shipping a regression on a Friday afternoon.

Canary and rollback

• Canary by percentage — Route a share of PROD traffic to the new version. Ten percent for an hour surfaces most problems.
• Watch the right metrics — Compare containment, transfer rate, and average duration between versions, not just error count.
• Rollback is republish — Selecting the previous version and publishing takes effect within seconds. In-flight calls finish on the version they started.

Audit trail

Every promotion records who approved it, which version moved, the diff, and the test run that justified it. Export the log from Settings → Audit for change-management review.