Environments

An environment is the governed execution container for ECP (Execution Control Protocol) workflows. Workflows stay portable; environments hold host bindings.

Create and bind

Node host (CLI and server apps):

import { environment, extension, policy } from "@executioncontrolprotocol/node"
import "@executioncontrolprotocol/core/testing"
import "@executioncontrolprotocol/format-toon"

export default (await environment("echo-dev", "Echo development"))
  .withExtensions([
    extension("@executioncontrolprotocol/test").with({}),
    extension("@executioncontrolprotocol/format-toon").with({}),
  ])

Common builder methods:

Method	Role
`.withRuntime(…)`	Override or set runtime
`.withExtensions([...])`	Bind cataloged extensions
`.withPolicies([...])`	Bind policies
`.withHarnesses([...])`	Bind harnesses (common in browser apps)
`.init()`	Return operational Ecp

Import extension packages for side-effect catalog registration before binding by string id.

Init and operational APIs

const env = await environment("dev")
  .withExtensions([extension("@executioncontrolprotocol/test").with({})])

const ecp = await env.init()

await ecp.describe()
await ecp.search("echo")
await ecp.validate(manifest)
await ecp.run(manifest, { input: { value: "hello" } })
await ecp.encode(source).uses("@executioncontrolprotocol/format-toon").to("@executioncontrolprotocol.workflow").process()
await ecp.terminate()

Do not call run/encode on the environment builder — use the Ecp returned by init(). ecp.validate() / ecp validate check the graph and environment only. Run input is validated against workflow.accepts on ecp.run (and --dry-run), not on validate. Also available on Ecp: invoke, test, decode, patch, search, and describe.

Secrets and extension config

Keep credentials out of workflows. Store them with ecp config secrets, then pass secrets("…") into extension .with({…}):

import "@executioncontrolprotocol/secrets"
import { environment, extension, secrets } from "@executioncontrolprotocol/node"

export default (await environment("demo")).withExtensions([
  extension("@executioncontrolprotocol/secrets").with({}),
  extension("@executioncontrolprotocol/openai").with({
    apiKey: secrets("openai/api-key"),
  }),
])

secrets(...) and env(...) helpers are environment setup only. See Security.

Browser hosts

@executioncontrolprotocol/browser provides a slim host (executor, registry, session). Apps bind providers and harnesses. The browser demo is one such app; see Demo providers and configuration.

CLI

Point commands at an environment module:

ecp run workflow.ts --env environment.ts --input input.json
ecp describe --env environment.ts
ecp describe --env environment.ts --capability @executioncontrolprotocol/test.echo
ecp search "echo" --env environment.ts

Bare describe is a light inventory. Pass --capability or --extension with an exact id for full metadata and JSON Schema.

Getting started

Learn

Build

Alternatives

AI tools

Reference

Environments

Environments

Create and bind

Init and operational APIs

Secrets and extension config

Browser hosts

CLI

Next steps

​Environments

​Create and bind

​Init and operational APIs

​Secrets and extension config

​Browser hosts

​CLI

​Next steps

Environments

Create and bind

Init and operational APIs

Secrets and extension config

Browser hosts

CLI

Next steps