Configuration

Most setups only need a workspace plus local or cloud provider settings. The rest is engine selection, browser executable control, and default context behavior.

Environment variables

Variable	Purpose
OPENSTEER_WORKSPACE	Default workspace for CLI commands
OPENSTEER_ENGINE	Engine name, usually playwright or abp
OPENSTEER_PROVIDER	Provider mode: local or cloud
OPENSTEER_API_KEY	Cloud API key
OPENSTEER_BASE_URL	Cloud control API base URL
OPENSTEER_CLOUD_APP_BASE_URL	Cloud app base URL used by record --provider cloud
OPENSTEER_EXECUTABLE_PATH	Default local browser executable path when launch.executablePath is not set explicitly
OPENSTEER_HUMANIZE	Default context.humanize value for supported engines unless you override it in code

There is no OPENSTEER_HEADLESS or OPENSTEER_BROWSER_MODE environment surface in the package API. Headless and attach settings are constructor options or CLI flags.

dotenv loading

The CLI loads .env and .env.local while walking upward from the current working directory before parsing flags.

The SDK resolves .env and .env.local while walking upward from rootDir.

Two important details:

• only OPENSTEER_* keys are loaded
• process.env always wins over file values
• SDK environment resolution returns a merged snapshot and does not mutate global process.env

SDK configuration

Local

const opensteer = new Opensteer({
  workspace: "demo",
  rootDir: process.cwd(),
  engineName: "playwright",
  browser: "persistent",
  launch: {
    headless: false,
    executablePath: process.env.OPENSTEER_EXECUTABLE_PATH,
  },
  context: {
    locale: "en-US",
    humanize: true,
  },
  provider: {
    mode: "local",
  },
});

Cloud

const opensteer = new Opensteer({
  workspace: "demo",
  rootDir: process.cwd(),
  provider: {
    mode: "cloud",
    apiKey: process.env.OPENSTEER_API_KEY,
    baseUrl: process.env.OPENSTEER_BASE_URL,
    appBaseUrl: process.env.OPENSTEER_CLOUD_APP_BASE_URL,
    browserProfile: {
      profileId: "bp_123",
    },
  },
});

browserProfile belongs under provider, not under launch.

CLI runtime flags

Useful CLI flags:

• --workspace <id>
• --engine <name>
• --provider local|cloud
• --headless
• --attach-endpoint <url>
• --attach-header key=value
• --executable-path <path>
• --arg <value>
• --timeout-ms <n>
• --context <json>
• --cloud-base-url <url>
• --cloud-api-key <key>
• --cloud-app-base-url <url>
• --cloud-profile-id <id>
• --cloud-profile-reuse-if-active

Engine rules

• Playwright is the default local engine.
• ABP requires a separate install: npm install @opensteer/engine-abp.
• ABP only supports context.viewport from browser context options.
• ABP is not supported for provider=cloud.

Common cloud errors

If cloud configuration is incomplete, these are the important failures:

• provider=cloud requires OPENSTEER_API_KEY or provider.apiKey.
• provider=cloud requires OPENSTEER_BASE_URL or provider.baseUrl.
• record with provider=cloud requires OPENSTEER_CLOUD_APP_BASE_URL or "--cloud-app-base-url".
• Cloud-specific options require provider=cloud. Set "--provider cloud" or OPENSTEER_PROVIDER=cloud.