Define an environment in YAML

Use YAML when an environment’s app selection and task metadata belong in configuration. parseEnvironmentYaml() turns a YAML document into input for sm.environments.create().

Write a create definition

The document uses the fields of the create input. The example defines a name, one app, and a string label, then passes the parsed input to the SDK.

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

const input = parseEnvironmentYaml(`
name: CRM integration
apps:
  - salesforce
labels:
  suite: integration
`);
const sm = new StateMachines();
const env = await sm.environments.create(input, { wait: false });

try {
  const running = await sm.environments.wait(env.id, { status: 'running' });
  console.log(running.id, running.status);
} finally {
  await env.delete();
}

For a file-based configuration, read the file as UTF-8 and pass its text to parseEnvironmentYaml(). File access belongs to your application. The parser does not load files or process environment variables for you. Use named app objects when the same app appears more than once. For snapshot-based creation, provide snapshotId instead of an app list. See Create the apps your task needs and snapshot reuse for the respective inputs.

Handle validation before creating resources

Invalid YAML or invalid create input throws StateMachinesError with code invalid_request and a null HTTP status. The fields property maps dotted field paths to messages. The parser requires a top-level mapping, string keys, and exactly one of apps and snapshotId. Top-level fields are name, labels, apps, snapshotId, workspaceId, timeLimitMinutes and tokenInUrl. An app entry is a string or a mapping with app, name and settings. The parser rejects any other field. Labels must be strings. Quote values such as "true" or "123" when they are labels. The parser refuses anchors, aliases, tags, and duplicate keys. Keep the definition explicit so the effective app settings do not depend on YAML expansion rules.

Keep secrets outside the definition

An environment definition describes apps, settings, and metadata. The management API key belongs in the process or runtime secret store, not the YAML file. Avoid storing tokens or customer data in names and labels. Those fields are resource metadata, not secret storage. App settings are passed to the app unchanged and still need to satisfy that app’s accepted configuration. Parsing checks field shapes. The API still validates app IDs, unique app names, size constraints, numeric bounds, workspace access, and snapshot availability. Parsing a document does not start an environment or validate every app-specific setting. A refused app setting can still fail startup with invalid_settings. Keep waiting and cleanup inside the same try and finally, as the example does.

​Write a create definition

​Handle validation before creating resources

​Keep secrets outside the definition

Write a create definition

Handle validation before creating resources

Keep secrets outside the definition