Configuration

Enable cloud mode with environment variables:

OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key
OPENSTEER_AUTH_SCHEME=api-key
OPENSTEER_REMOTE_ANNOUNCE=always
OPENSTEER_CLOUD_PROFILE_ID=bp_123
OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE=true

Or use interactive CLI login and saved machine credentials:

opensteer auth login
opensteer auth status

opensteer auth login opens your default browser when possible. Use opensteer auth login --no-browser on remote shells, containers, or CI and paste the printed URL into a browser manually. In --json mode, login prompts go to stderr and the final JSON result stays on stdout.

Saved machine logins remain scoped per resolved cloud API host (baseUrl). The CLI remembers the last selected cloud host, so opensteer auth status, opensteer auth logout, and other cloud commands reuse it by default unless --base-url or env vars select a different host.

These values can be placed in .env files. Opensteer auto-loads .env.<NODE_ENV>.local, .env.local (skipped when NODE_ENV=test), .env.<NODE_ENV>, then .env from your storage.rootDir (default: process.cwd()). Existing process.env values are not overwritten. Set OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true to disable auto-loading.

Opensteer defaults to local mode when OPENSTEER_MODE is unset and cloud is not configured.

You can also force cloud mode in constructor config:

import { Opensteer } from 'opensteer'

const opensteer = new Opensteer({
    cloud: {
        accessToken: process.env.OPENSTEER_ACCESS_TOKEN,
        baseUrl: process.env.OPENSTEER_BASE_URL,
        authScheme: 'bearer',
        browserProfile: {
            profileId: 'bp_123',
            reuseIfActive: true,
        },
    },
})

• Default cloud host: https://api.opensteer.com
• Override host with OPENSTEER_BASE_URL
• Cloud credential can be provided via:
  • cloud.apiKey / OPENSTEER_API_KEY (CI/headless recommended)
  • cloud.accessToken / OPENSTEER_ACCESS_TOKEN
  • saved machine login (opensteer auth login) for interactive CLI commands, scoped per resolved host
• Auth scheme can be configured via cloud.authScheme or OPENSTEER_AUTH_SCHEME
  • Supported values: api-key (default), bearer
• Credential precedence in CLI commands:
  1. explicit flags
  2. environment variables
  3. saved machine login for the resolved host
• Cloud browser profile can be configured via cloud.browserProfile.profileId or OPENSTEER_CLOUD_PROFILE_ID
• Optional profile session reuse can be configured via cloud.browserProfile.reuseIfActive or OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE
• Default cloud announcement policy: always
• Override cloud announcement with cloud.announce or OPENSTEER_REMOTE_ANNOUNCE
  • Supported values: always, off, tty
• cloud in constructor config overrides OPENSTEER_MODE
• Cloud mode is fail-fast and does not fall back to local mode

Cloud Mode

Opensteer defaults to local mode. Enable cloud mode with env or constructor options:

OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=<your_api_key>

• Interactive CLI login:

opensteer auth login
opensteer auth status
opensteer auth logout

• opensteer auth login opens your default browser when possible. Use --no-browser on remote shells, containers, or CI and paste the printed URL into a browser manually. In --json mode, login prompts go to stderr and the final JSON result stays on stdout.

• Saved machine logins remain scoped per resolved cloud API host (baseUrl). The CLI also remembers the last selected cloud host, so opensteer auth status, opensteer auth logout, and other cloud commands reuse it by default unless --base-url or env vars select a different host.

• OPENSTEER_BASE_URL overrides the default cloud host

• OPENSTEER_ACCESS_TOKEN provides bearer auth for cloud commands

• OPENSTEER_AUTH_SCHEME supports api-key (default) or bearer

• Credential precedence: explicit flags > environment variables > saved machine login

• OPENSTEER_CLOUD_PROFILE_ID optionally launches into a specific cloud browser profile

• OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE (true|false) optionally reuses an active profile session

• cloud: true or a cloud options object overrides OPENSTEER_MODE

• Cloud mode is fail-fast (no automatic fallback to local)

• Opensteer.from(page), uploadFile, exportCookies, and importCookies are local-only

Select a cloud browser profile in SDK:

const opensteer = new Opensteer({
  cloud: {
    accessToken: process.env.OPENSTEER_ACCESS_TOKEN,
    browserProfile: {
      profileId: "bp_123",
      reuseIfActive: true,
    },
  },
});

Sync local profile cookies into a cloud profile:

opensteer profile sync \
  --from-profile-dir ~/Library/Application\ Support/Google/Chrome/Default \
  --to-profile-id bp_123 \
  --domain github.com

Covered Features

• env:OPENSTEER_ACCESS_TOKEN
• env:OPENSTEER_API_KEY
• env:OPENSTEER_AUTH_SCHEME
• env:OPENSTEER_BASE_URL
• env:OPENSTEER_CLOUD_PROFILE_ID
• env:OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE
• env:OPENSTEER_MODE
• env:OPENSTEER_REMOTE_ANNOUNCE

Related Docs

• Cloud Config Precedence
• Environment Variables
• Cloud Errors and Troubleshooting
• Cloud Launch Context