Environment Setup

The Atomemo Plugin SDK uses environment variables to configure runtime behavior, WebSocket connections, and authentication.

Required Environment Variables

Your plugin requires these environment variables to run:

HUB_WS_URL

The WebSocket URL of the Hub Server.

HUB_WS_URL=wss://hub.atomemo.ai

Format:

Must be a valid WebSocket URL
Supported protocols: ws:// or wss://
The SDK appends /{mode}_socket automatically

Examples:

# Production
HUB_WS_URL=wss://hub.atomemo.ai

# Staging
HUB_WS_URL=wss://hub-staging.atomemo.ai

# Local development
HUB_WS_URL=ws://localhost:4000

The SDK automatically determines the deployment environment (production/staging) based on the URL.

HUB_DEBUG_API_KEY

API key for debug mode authentication.

HUB_DEBUG_API_KEY=your_api_key_here

Requirements:

Required when NODE_ENV is not "production"
Must be a non-empty string
Obtain from the Atomemo CLI: atomemo plugin refresh-key

Security:

Never commit API keys to version control
Use .env files (add to .gitignore)
Rotate keys regularly

Optional Environment Variables

HUB_MODE

Sets the plugin runtime mode.

HUB_MODE=debug

Options:

debug (default) - Development mode with dynamic registration
release - Production mode with static registration

Behavior differences:

Feature	Debug Mode	Release Mode
Registration	Dynamic via WebSocket	Static from `definition.json`
Author info	From OneAuth API	From `definition.json`
API key	Required	Not required
Hot reload	Supported	Not supported
Channel	`debug_plugin:{name}`	`release_plugin:{name}__{mode}__{version}`
Definition file	Generated	Required

DEBUG

Enables debug logging.

DEBUG=true

Behavior:

true - Enable verbose logging
false - Minimal logging
Default: true when NODE_ENV !== "production"

Log output includes:

WebSocket connection events
Channel join/leave messages
Incoming/outgoing messages
Error details

NODE_ENV

Sets the Node.js environment.

NODE_ENV=development

Options:

development (default)
production
test

Effects:

Controls default DEBUG value
Affects HUB_DEBUG_API_KEY validation
Influences SDK behavior (e.g., error verbosity)

Configuration File

The SDK reads additional configuration from ~/.choiceform/atomemo.json:

{
  "auth": {
    "production": {
      "endpoint": "https://oneauth.atomemo.ai",
      "access_token": "your_access_token"
    },
    "staging": {
      "endpoint": "https://oneauth-staging.atomemo.ai",
      "access_token": "your_staging_token"
    }
  },
  "hub": {
    "production": {
      "endpoint": "wss://hub.atomemo.ai"
    },
    "staging": {
      "endpoint": "wss://hub-staging.atomemo.ai"
    }
  }
}

Purpose:

Stores authentication tokens for OneAuth API
Provides deployment-specific endpoints
Managed by the Atomemo CLI

Don’t edit this file manually. Use the Atomemo CLI to manage configuration.

Environment File Setup

Create .env file

Create a .env file in your project root:

touch .env

Add environment variables

Edit .env with your configuration:

# Hub Server connection
HUB_WS_URL=wss://hub.atomemo.ai
HUB_DEBUG_API_KEY=your_api_key_here

# Runtime mode
HUB_MODE=debug

# Development settings
DEBUG=true
NODE_ENV=development

Add to .gitignore

Ensure .env is ignored by git:

echo ".env" >> .gitignore

Load environment variables

The SDK automatically loads .env via dotenv/config:

import "dotenv/config"
import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js"

// Environment variables are now available
const plugin = await createPlugin({ /* ... */ })

Environment Validation

The SDK validates environment variables on startup using Zod:

// From src/env.ts
const EnvSchema = z.object({
  HUB_MODE: z.enum(["debug", "release"]).default("debug"),
  HUB_WS_URL: z.url({ protocol: /wss?/ }),
  HUB_DEBUG_API_KEY: z.string().optional().refine(/* ... */),
  DEBUG: z.string().optional().transform(/* ... */),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
})

Validation errors: If validation fails, you’ll see detailed error messages:

Error: Invalid environment configuration
- HUB_WS_URL: Expected string, received undefined
- HUB_DEBUG_API_KEY: Required in non-production environments

The plugin will exit immediately with code 1.

Environment Variables by Use Case

Local Development

# .env
HUB_MODE=debug
HUB_WS_URL=ws://localhost:4000
HUB_DEBUG_API_KEY=dev_key_abc123
DEBUG=true
NODE_ENV=development

Staging Environment

# .env
HUB_MODE=debug
HUB_WS_URL=wss://hub-staging.atomemo.ai
HUB_DEBUG_API_KEY=staging_key_xyz789
DEBUG=true
NODE_ENV=development

Production Environment

# .env
HUB_MODE=release
HUB_WS_URL=wss://hub.atomemo.ai
DEBUG=false
NODE_ENV=production

In production, HUB_DEBUG_API_KEY is not required.

Testing Environment

# .env.test
HUB_MODE=debug
HUB_WS_URL=ws://localhost:4000
HUB_DEBUG_API_KEY=test_key_mock
DEBUG=false
NODE_ENV=test

Reading Environment Variables

The SDK provides a getEnv() function:

import { getEnv } from "@choiceopen/atomemo-plugin-sdk-js"

const env = getEnv()

console.log(env.HUB_MODE)          // "debug" or "release"
console.log(env.HUB_WS_URL)        // "wss://hub.atomemo.ai"
console.log(env.HUB_DEBUG_API_KEY) // "your_api_key" or undefined
console.log(env.DEBUG)             // true or false
console.log(env.NODE_ENV)          // "development", "production", or "test"

TypeScript types:

interface Env {
  HUB_MODE: "debug" | "release"
  HUB_WS_URL: string
  HUB_DEBUG_API_KEY?: string
  DEBUG: boolean
  NODE_ENV: "development" | "production" | "test"
}

Troubleshooting

Connection Errors

Error: Can't connect to the Plugin Hub server Causes:

Invalid HUB_WS_URL
Expired HUB_DEBUG_API_KEY
Network connectivity issues

Solutions:

# Verify WebSocket URL
echo $HUB_WS_URL

# Refresh API key
atomemo plugin refresh-key

# Test connectivity
curl -I https://hub.atomemo.ai

Validation Errors

Error: HUB_WS_URL must be a valid WebSocket URL Solution:

# Wrong
HUB_WS_URL=https://hub.atomemo.ai

# Correct
HUB_WS_URL=wss://hub.atomemo.ai

Missing API Key

Error: HUB_DEBUG_API_KEY must be a string Solution:

# Generate new key
atomemo plugin refresh-key

# Copy to .env
HUB_DEBUG_API_KEY=your_new_key

Environment Not Loaded

Error: Environment variables undefined in code Solution: Ensure dotenv/config is imported:

// Must be first import
import "dotenv/config"
import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js"

Best Practices

Use .env files for local development

# .env
HUB_WS_URL=wss://hub.atomemo.ai
HUB_DEBUG_API_KEY=dev_key_local

Add .env to .gitignore to prevent committing secrets.

Use environment-specific files

.env              # Default
.env.development  # Development
.env.staging      # Staging
.env.production   # Production
.env.test         # Testing

Load with: dotenv -e .env.staging

Validate environment on startup

import { getEnv } from "@choiceopen/atomemo-plugin-sdk-js"

try {
  const env = getEnv()
  console.log("Environment loaded successfully")
} catch (error) {
  console.error("Environment validation failed:", error)
  process.exit(1)
}

Document required variables

Create a .env.example file:

# .env.example
HUB_WS_URL=wss://hub.atomemo.ai
HUB_DEBUG_API_KEY=your_api_key_here
HUB_MODE=debug
DEBUG=true
NODE_ENV=development

Commit this file to help other developers.

Rotate API keys regularly

# Refresh debug API key
atomemo plugin refresh-key

# Update .env
# HUB_DEBUG_API_KEY=new_key_here

Get Started

Core Concepts

Guides

Examples

Required Environment Variables

HUB_WS_URL

HUB_DEBUG_API_KEY

Optional Environment Variables

HUB_MODE

DEBUG

NODE_ENV

Configuration File

Environment File Setup

Environment Validation

Environment Variables by Use Case

Local Development

Staging Environment

Production Environment

Testing Environment

Reading Environment Variables

Troubleshooting

Connection Errors

Validation Errors

Missing API Key

Environment Not Loaded

Best Practices

Next Steps

Debug Mode

Creating a Plugin

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

​Required Environment Variables

​HUB_WS_URL

​HUB_DEBUG_API_KEY

​Optional Environment Variables

​HUB_MODE

​DEBUG

​NODE_ENV

​Configuration File

​Environment File Setup

​Environment Validation

​Environment Variables by Use Case

​Local Development

​Staging Environment

​Production Environment

​Testing Environment

​Reading Environment Variables

​Troubleshooting

​Connection Errors

​Validation Errors

​Missing API Key

​Environment Not Loaded

​Best Practices

​Next Steps

Debug Mode

Creating a Plugin

Build docs developers (and LLMs) love

Required Environment Variables

HUB_WS_URL

HUB_DEBUG_API_KEY

Optional Environment Variables

HUB_MODE

DEBUG

NODE_ENV

Configuration File

Environment File Setup

Environment Validation

Environment Variables by Use Case

Local Development

Staging Environment

Production Environment

Testing Environment

Reading Environment Variables

Troubleshooting

Connection Errors

Validation Errors

Missing API Key

Environment Not Loaded

Best Practices

Next Steps