SmythOS Studio: Open-Source Visual AI Agent Builder and deployable runtime stack from SmythOS. Start with an intuitive drag-and-drop workspace, extend with custom code, and deploy your agents anywhere — local, cloud, or edge — with full governance and control.
SmythOS Runtime Server
A unified runtime server that provides comprehensive execution, debugging, and integration capabilities for SmythOS agents.
📚 Table of Contents
- 🚀 Quick Start
- 💡 What is SmythOS Runtime?
- 🏗️ Architecture
- ⚙️ Installation & Usage
- 🔧 Configuration
- 🌐 API Modules
- 🚀 Smart Routing
- 🌐 Deployment
- 🔍 Troubleshooting
🚀 Quick Start
# Install dependencies
pnpm install
# Start development server
pnpm run dev
# Health check
curl http://localhost:5053/health
💡 What is SmythOS Runtime?
The SmythOS Runtime Server is the execution engine for SmythOS agents. It provides:
- Agent Execution: Run and manage SmythOS agents with OAuth authentication
- Debug Capabilities: Debug agent workflows with real-time monitoring
- Integration Hub: Connect agents to external services (ChatGPT, OpenAI, Alexa, etc.)
- API Gateway: Unified API for all SmythOS runtime operations
🏗️ Architecture
The runtime server is organized into three core modules:
src/
├── core/ # Shared infrastructure
│ ├── config/ # Configuration management
│ ├── middlewares/ # Common middleware (CORS, auth, etc.)
│ ├── services/ # Shared services
│ ├── types/ # TypeScript definitions
│ └── utils/ # Utility functions
├── modules/ # Runtime modules
│ ├── agent-runner/ # Agent execution & OAuth
│ ├── debugger/ # Debug capabilities & monitoring
│ └── embodiment/ # External integrations
└── services/ # Additional services
└── code-sandbox.service.ts
Core Components
- Agent Runner: Executes SmythOS agents with authentication and rate limiting
- Debugger: Provides debugging capabilities with component-level tracking
- Embodiment: Handles integrations with external platforms and services
⚙️ Installation & Usage
Development
# Install dependencies
pnpm install
# Start development server with auto-reload
pnpm run dev
# The server will start on http://localhost:5053
Production
# Build the application
pnpm run build
# Start production server
pnpm run start:prod
Available Scripts
| Script | Description |
|---|---|
pnpm run dev |
Development mode with auto-reload |
pnpm run build |
Build for production |
pnpm run start:prod |
Start production server |
pnpm run test |
Run tests |
pnpm run lint |
Lint TypeScript files |
pnpm run clean |
Clean build directory |
🔧 Configuration
Required Environment Variables
# Authentication (LogTo configuration)
LOGTO_M2M_APP_SECRET="your-m2m-app-secret"
LOGTO_M2M_APP_ID="your-m2m-app-id"
LOGTO_SERVER="https://auth.yourdomain.com"
LOGTO_API_RESOURCE="https://api.yourdomain.com"
MIDDLEWARE_API_BASE_URL="http://middleware.yourdomain.com"
Optional Configuration
# Server Configuration
PORT="5053" # Runtime server port
ADMIN_PORT="5054" # Admin interface port
BASE_URL="http://localhost:5053"
UI_SERVER="http://localhost:4000"
# Security
SESSION_SECRET="your-random-secret-here"
# Agent Domain Configuration
DEFAULT_AGENT_DOMAIN="localagent.stage.yourdomain.ai"
PROD_AGENT_DOMAIN="agentid.yourdomain.com"
⚠️ Local Development: For local agent execution, ensure your domain contains
localagent
🌐 API Modules
Agent Runner (/api/*)
- OAuth Authentication:
/oauth/*- Handle OAuth flows - Agent Execution:
/agent/*- Execute and manage agents - File Operations: File upload and processing capabilities
Debugger (/models/*)
- Model Management: Team-based access control for AI models
- Debug Sessions: Real-time agent debugging and monitoring
- Component Tracking: Async component execution tracking
Embodiment (Various endpoints)
- ChatGPT Plugin:
/chatgpt/*- ChatGPT plugin integration - OpenAI Proxy:
/openai/*- OpenAI API proxy - Alexa Skills:
/alexa/*- Amazon Alexa integration - MCP Protocol:
/mcp/*- Model Context Protocol support - API Documentation:
/swagger/*- Interactive API docs - Postman Collections:
/postman/*- Generate API collections
🚀 Smart Routing
The runtime server uses intelligent routing to direct requests to the appropriate module based on HTTP headers:
Quick Examples
# Default behavior (Agent Runner)
curl http://localhost:5053/api/test
# Force specific modules
curl -H "X-FORCE-AGENT-RUNNER: true" http://localhost:5053/api/test
curl -H "X-FORCE-DEBUGGER: true" http://localhost:5053/api/test
# Debug session
curl -H "X-DEBUG-RUN: true" http://localhost:5053/api/test
Routing Headers
| Header | Purpose | Routes To |
|---|---|---|
X-FORCE-AGENT-RUNNER |
Force agent execution | Agent Runner |
X-FORCE-DEBUGGER |
Force debug mode | Debugger |
X-DEBUG-RUN |
Start debug session | Debugger |
X-MONITOR-ID |
Monitor agent execution | Debugger |
Server Modes
Control server functionality with the SERVER_MODE environment variable:
runtime(default): Full functionalityagent: Agent runner onlydebugger: Debugger onlyembodiment: Integrations only
🌐 Deployment
Environment Requirements
Development:
- Node.js 18+
- pnpm 8+
- LogTo authentication server
Production:
- All development requirements
- Redis (for session management)
- SSL certificates
- Load balancer (recommended)
Production Deployment
Build the application:
pnpm run buildSet environment:
NODE_ENV=production PORT=5053 # Add production environment variablesStart server:
pnpm run start:prod
Health Monitoring
Check server health at: http://localhost:5053/health
The health endpoint provides:
- Server status and mode
- Available modules
- Version information
🔍 Troubleshooting
Common Issues
Authentication Failing
- Verify LogTo environment variables
- Ensure LogTo server is accessible
- Check M2M app configuration
Routing Issues
# Test with explicit headers
curl -H "X-FORCE-AGENT-RUNNER: true" http://localhost:5053/api/test
Build Problems
# Increase memory for builds
export NODE_OPTIONS='--max-old-space-size=4096'
pnpm run build
Development Server Issues
# Clean reinstall
rm -rf node_modules
pnpm install
Debug Mode
Enable debug logging by setting routing headers:
# Enable debug mode
curl -H "X-DEBUG-RUN: true" http://localhost:5053/api/test
# Monitor specific session
curl -H "X-MONITOR-ID: session-123" http://localhost:5053/api/test
📊 Monitoring & Logging
The server provides comprehensive logging for:
- Request routing decisions
- Authentication events
- Agent execution status
- Error tracking and debugging
Logs are formatted for easy consumption and include routing reasons for troubleshooting.
🔐 Security Features
- Rate Limiting: Built-in rate limiting for API endpoints
- CORS Protection: Configurable CORS policies
- Authentication: OAuth 2.0 with LogTo integration
- Input Validation: Request validation with Joi schemas
- Error Handling: Secure error responses without sensitive data exposure
🤝 Contributing
When contributing to the runtime server:
- Follow TypeScript best practices
- Add tests for new functionality
- Update documentation for API changes
- Maintain backward compatibility
- Test routing scenarios thoroughly
📄 License
This project is part of the SmythOS ecosystem.