Pause, resume, and delete environments

An environment exists as soon as State Machines accepts its creation. Its status describes what it can do now. An accepted environment is not yet ready for app requests.

Status and data

Status	Meaning
`starting`	The apps are starting. Wait before sending app requests.
`running`	The apps can receive requests.
`paused`	Compute is released and data remains. Resume before making requests.
`failed`	An environment that previously ran could not start or restart. Its data remains available for a resume attempt. It is deleted one day after it failed.
`deleted`	The environment has ended and data cleanup proceeds. Its metadata remains readable by ID.

If an environment fails before it ever runs, State Machines deletes it with reason failed. The SDK reports that through EnvironmentFailedError.

Pausing keeps the current data

pause() changes the status when the API answers. From then on, the gateway answers app requests with environment_not_running. Pausing releases compute and stops the time limit. The environment keeps its data. Pausing a starting environment fails with invalid_status. resume() starts apps on that same data. The SDK waits for running unless you pass { wait: false }. Resuming counts against the organization’s concurrent limit and can fail with environment_limit_reached. A returned environment object describes one read of the resource. To get its new status, use the object returned by the operation or call refresh().

import { StateMachines } from '@usestatemachines/sdk';

const sm = new StateMachines();
const env = await sm.environments.create(
  { apps: ['salesforce'] },
  { wait: false },
);

try {
  await sm.environments.wait(env.id, { status: 'running' });
  const paused = await env.pause();
  console.log(paused.status);
  const resumed = await env.resume();
  console.log(resumed.status);
  const salesforce = await resumed.connect('salesforce');
  const response = await salesforce.fetch('/services/data/v67.0/limits');

  if (!response.ok) {
    throw new Error(`Salesforce returned ${response.status}`);
  }

  console.log(response.status);
} finally {
  await env.delete();
}

Deleting ends ownership

delete() marks the environment deleted and refuses further app access when the API answers. Compute and data cleanup continue after the response. Repeating delete() is safe, so call it in an awaited finally block. Pause for an interactive break, but delete the environment at the end of a task. The time limit counts time spent in starting and running. sm.me().limits.timeLimitMinutes returns its default and maximum. State Machines deletes the environment when the time limit ends. State Machines deletes a paused or failed environment one day after it paused or failed, with reason expired. expiresAt shows that deadline. A ready snapshot is a separate saved copy. Use snapshots for reusable data that must outlive the source environment.

Read lifecycle timestamps

createdAt records acceptance. startedAt records the first time the environment became running. A resume does not change it. pausedAt records when the current paused or failed period began. expiresAt is the current deletion deadline and is null once deleted. A deleted environment’s reason distinguishes expiration, failure before first startup, and cancellation by staff. A caller-requested deletion has a null reason. If failure is present, it names the affected app and gives its code and message. Pause, resume, and delete are actions. wait() only observes. Waiting for running on a paused environment does not resume it and fails with UnexpectedStatusError. When a resumed app fails, EnvironmentFailedError carries the environment for diagnosis. See SDK errors for polling outcomes.

Cleanup belongs to the caller

An accepted environment keeps running after the caller stops waiting or loses its process. Get the ID with wait: false before the work that needs cleanup. Keep an explicit create key when the acceptance response itself could be lost. An awaited finally handles failures while the process is alive. CI cancellation or a runtime crash can prevent it from running. Persist owned environment IDs with the job, use labels to identify the run, and recover cleanup in a later job. The time limit is a final bound, not confirmation that cleanup succeeded. If deletion fails, keep both the environment ID and the cleanup error, then retry the deletion. Do not reuse an aborted work signal for cleanup, because it cancels the delete request too.

​Status and data

​Pausing keeps the current data

​Deleting ends ownership

​Read lifecycle timestamps

​Cleanup belongs to the caller

Status and data

Pausing keeps the current data

Deleting ends ownership

Read lifecycle timestamps

Cleanup belongs to the caller