Environment Variables Reference

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

Overview

WAIIDE uses environment variables for configuration and JupyterHub integration. This document lists all recognized environment variables and their effects in the modern multi-instance architecture.

JupyterHub Variables (Set Automatically)

These variables are set by JupyterHub when spawning containers. Do not override these manually.

Core JupyterHub Variables

Named Server Variables (Multi-Instance)

Modern Multi-Instance Pattern

The new architecture supports multiple instances per user with unique hashed names:

Multiple Instance Examples

User lmata can have multiple instances simultaneously:

ECS Spawner Integration

When using ECS spawners, ensure they set:

This allows WAIIDE to:

• ✅ Serve WAIIDE at root URL (no /WAIIDE/ path needed)
• ✅ Display instance name in logs: “Running as named server: lmata-waiide-abc123 for user: lmata”
• ✅ Handle OAuth correctly with the full instance name
• ✅ Support multiple instances per user without conflicts

See ECS Instance Names for detailed ECS spawner configuration.

WAIIDE Configuration Variables

These variables control WAIIDE behavior:

Service Configuration

Logging

User Environment

Migration from Legacy Variables

❌ Legacy Patterns (Deprecated)

# Old single-instance patterns
JUPYTERHUB_SERVER_NAME=waiide
JUPYTERHUB_SERVICE_PREFIX=/user/lmata/waiide/

✅ Modern Patterns (Current)

# New multi-instance patterns
JUPYTERHUB_SERVER_NAME=lmata-waiide-abc123
JUPYTERHUB_SERVICE_PREFIX=/user/lmata/lmata-waiide-abc123/
JUPYTERHUB_SERVICE_URL=https://hub.example.com/user/lmata/lmata-waiide-abc123/

Environment Variable Validation

WAIIDE validates these environment variables on startup:

Required for JupyterHub Mode

• JUPYTERHUB_USER - Must be set and non-empty
• JUPYTERHUB_API_TOKEN - Must be a valid OAuth token
• JUPYTERHUB_SERVICE_PREFIX - Must end with /
• JUPYTERHUB_SERVICE_URL - Must be a valid URL

Optional but Recommended

• JUPYTERHUB_SERVER_NAME - Used for instance identification and logging
• LOG_LEVEL - Helps with debugging

Troubleshooting Environment Issues

Instance Name Not Detected

# Check if server name is set
echo $JUPYTERHUB_SERVER_NAME
# Should show: lmata-waiide-abc123

OAuth Callback Errors

# Verify callback URL matches service prefix
echo $JUPYTERHUB_OAUTH_CALLBACK_URL  
# Should show: /user/lmata/lmata-waiide-abc123/oauth_callback

WAIIDE Not at Root

# Check service prefix configuration
echo $JUPYTERHUB_SERVICE_PREFIX
# Should show: /user/lmata/lmata-waiide-abc123/

For detailed troubleshooting, see the WAIIDE Configuration Guide.