> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Define an environment in YAML

> Parse a readable environment definition with the same create fields and validation errors.

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.

```ts theme={null}
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](/environments/create) and [snapshot reuse](/snapshots/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.