Environments

Source: sheptra.core/docs/management-api.md § POST /v1/environments, GET /v1/environments/placements, GET /v1/environments/plan, suspend/resume, DELETE /v1/environments/{id} · sheptra.core/docs/decision_records/environments-in-cell.md § 4.6 What isolation means, § 4.7 Placement · sheptra.core/docs/management-api.md § The worker environment block · sheptra.core/authentication.md § environments:manage

An environment is one isolated space of your organization: its own process definitions, instances, jobs, tasks and history, its own address in Drive, and its own machine bindings. Two environments never see each other’s data, even when they run on the same infrastructure. Your administrators manage them from Environments in Drive’s environment switcher; every action on this page needs the environments:manage permission, which the Organization Admin role carries.

Create#

Give the environment a name (Staging), a label (staging) and a placement: a shared class — Standard (nonprod), Production or Sandbox — or Dedicated when your organization has its own infrastructure. The class is what you are billed for and what the switcher shows; a class your plan does not include is shown disabled with the reason. On the shared classes the infrastructure is chosen for you and never named.

Where an environment lands#

Every environment runs on one of Sheptra’s engines — each with its own database, each holding many environments. Which one yours lands on is the placement you choose when you create it, and there are two kinds:

• Shared. Standard, Production and Sandbox environments land on infrastructure of that class that many organizations share. You never see or pick which: the API chooses, among the ones your plan allows, the one holding the fewest environments, and that choice holds until Sheptra moves the environment. Classes never mix on shared infrastructure — a Production environment only ever sits beside other Production environments, and a Standard or Sandbox one never beside production.
• Dedicated. An Enterprise organization with infrastructure of its own sees a fourth option naming it by label and region, with the places still free on it. Several environments may land there — production with a pre-production beside it is the usual shape — and if your organization has more than one, Drive asks which. Placing an environment there needs no support ticket; getting the infrastructure in the first place is a contract. Before placing a Standard environment beside your production, Drive says once what the two will share.

The same list is one call away for an administrator — each option carries allowed and, when it is not, the reason the dialog shows:

GET https://<management-host>/v1/environments/placements
Authorization: Bearer <access_token>

[
  { "kind": "shared", "class": "nonprod", "allowed": true },
  { "kind": "shared", "class": "prod", "allowed": false,
    "reason": "No capacity is available for a new prod-class environment right now. Contact support to have capacity added — your request is the signal that grows the pool." },
  { "kind": "shared", "class": "sandbox", "allowed": true },
  { "kind": "dedicated", "cellId": "acme", "label": "Acme", "region": "fra1",
    "class": "prod", "remaining": 3, "allowed": true }
]

On a shared placement, two refusals a create can meet: 409 Plan upgrade required when the placement is not in your plan — the dialog shows it disabled with the reason before you try — and 409 No environment capacity when every shared engine of that class is full, which is Sheptra’s to fix, not yours. A dedicated placement can also meet 400 Dedicated cell required when your organization has several and the request names none, 404 Cell not found for one your organization is not placed on, and 409 Cell not available or 409 Cell at capacity when that infrastructure is not taking environments right now. Your plan’s included environments are a soft number: creating past them succeeds, and the environment shows as an extra on the plan card below.

What two environments share, and what they never do#

Two environments on the same engine — one of yours and another organization’s, or two of yours — never see each other’s data. Every row the engine stores is keyed by the environment it belongs to, and the database enforces that, not only the application: definitions, decisions and forms, instances and their history, jobs, user tasks, incidents, messages and signals, partition grants and pauses, machine bindings and the archive are all per environment. A worker bound to dev never receives a qa job, even on the same engine, and the same process key can be deployed to both at different versions. What they do share is the engine’s infrastructure — its database connections, its scheduler, your organization’s request budget there and its release channel — so a very busy environment can slow its neighbours. Dedicated infrastructure is how an organization stops sharing that too.

The plan card#

Drive’s plan card lists your environments by line — shared Standard, shared Production, shared Sandbox, and one line per dedicated engine — with how many your plan includes on each and which are extras. A shared environment is billed by its class; every environment on your dedicated infrastructure is on that engine’s line, whatever its class, and never draws on the shared allowance. Sheptra publishes no prices yet; the card shows counts and lines, and the terms are in your contract.

Suspend and resume#

Suspending a shared environment keeps everything in it but stops it serving; resuming brings it back as it was, with nothing to re-provision. Environments on dedicated infrastructure are suspended through support.

Delete#

A nonprod or sandbox environment can be deleted from the Environments dialog. Drive asks you to type the environment’s name, then removes every row it holds — definitions, decisions and forms, instances and their history, jobs, user tasks, incidents, messages and signals, partition grants and pauses, and the machine bindings that admitted workers to it — and finally the environment itself. When it finishes Drive shows how many rows went, table by table; the environment disappears from the switcher, from discovery and from your plan, and if you were working inside it Drive moves you to another. Your other environments are not touched. Deleting cannot be undone.

Production stays a support conversation. A production-class environment has no Delete button and the API refuses it, as it refuses deleting your organization’s last environment. Ask support for either.

An administrator can do the same over the management API. The delete answers at once with a run to follow; the counts arrive when the environment’s engine has finished.

DELETE https://<management-host>/v1/environments/qa-2?confirm=QA%202
Authorization: Bearer <access_token>

HTTP/1.1 202 Accepted
Location: /v1/environments/qa-2/delete/7f3c…

{
  "runId": "7f3c…",
  "clusterId": "qa-2",
  "displayName": "QA 2",
  "environment": "qa",
  "status": "running",
  "startedAt": "2026-10-09T14:02:11Z",
  "completedAt": null,
  "totalDeleted": 0,
  "tables": [],
  "environmentRemoved": false,
  "error": null
}

GET https://<management-host>/v1/environments/qa-2/delete/7f3c…

{
  "runId": "7f3c…",
  "clusterId": "qa-2",
  "status": "completed",
  "completedAt": "2026-10-09T14:02:19Z",
  "totalDeleted": 1843,
  "tables": [
    { "table": "jobs", "deleted": 212 },
    { "table": "process_instances", "deleted": 96 },
    { "table": "machine_bindings", "deleted": 2 },
    …
  ],
  "environmentRemoved": true,
  "error": null
}

A run that does not finish answers failed with an error saying what to do: deleting again resumes where it stopped, and the environment stays out of service in between. Every delete lands an EnvironmentErased row in your organization’s admin trail naming who deleted it, with the counts per table.

What a deleted environment means for workers#

The environment’s machine bindings are revoked in the same sweep as its data, and the cell records which credentials it unbound, so a worker bound to it is refused on its next call with 403 Machine credential revoked — whether it names the deleted environment in X-Sheptra-Cluster, another of your environments, or none, and whether or not your organization requires machine credentials to be bound. The refusal stands for 90 days after the delete; naming an environment an administrator has since bound the credential to is the one way in. The API client itself is organization-wide and survives — bind it to another environment and point its SHEPTRA_ENVIRONMENT there, or revoke it on the API clients page. The workers guide lists every refusal a worker can receive.