Getting Started with Orbit Playground

Welcome to Orbit Playground - a comprehensive monorepo of beta samples and templates for AI integrations, SaaS API development, and Model Context Protocol (MCP) implementations designed for local development, sandbox testing, and training.

Repository Overview

4 Beta-Ready AI Samples:

Plus: Standalone AI playground for testing endpoints without authentication.

⚡ TL;DR - Fastest Setup

Quick Start:

git clone <repository-url>
cd orbit-ai-resources
docker-compose up -d

# Verify everything is running
curl http://localhost:3001/api/health  # Playground

Result: Complete AI development environment in under 2 minutes:

• Playground: http://localhost:3001 (test AI endpoints)
• SaaS Agent: http://localhost:8000 (MCP + API integration)
• Weather Agent: http://localhost:8001 (structured UI components)
• RAG Agent: http://localhost:8002 (knowledge base retrieval)
• Web Scraper: http://localhost:8003 (ethical web data collection)
• API Testing: Postman collections for comprehensive endpoint testing

Stop: docker-compose down

Quick Start

Step 1: Clone the Repository

# 1. Fork on GitHub: PyxisSoftwareOrg/csiorbit-resources → Your Account
# 2. Clone your fork
git clone git@github.com:<your-username>/csiorbit-resources.git
cd csiorbit-resources

# 3. Add upstream for updates
git remote add upstream git@github.com:PyxisSoftwareOrg/csiorbit-resources.git

git clone git@github.com:PyxisSoftwareOrg/csiorbit-resources.git
cd csiorbit-resources

Step 2: Prerequisites

Required:

• Git - For cloning the repository
• Docker Desktop - Runs all services automatically

Optional (for local development):

• Node.js 18+ and Python 3.11+ - Only needed if running services outside Docker

# Verify installation
docker --version && git --version

Step 3: Start All Services

# Start all services (MongoDB, agents, playground)
docker-compose up -d

# View logs (optional)
docker-compose logs -f

# Stop all services when done
docker-compose down

What you get automatically:

• ✅ All 4 sample agents running
• ✅ Playground interface at http://localhost:3001
• ✅ MongoDB database
• ✅ Pre-configured Orbit Sandbox AWS credentials
• ✅ All dependencies and environment setup

Step 4: Verify Everything Works

# Quick health check
curl http://localhost:3001/api/health  # Playground
curl http://localhost:8000/health      # SaaS Agent
curl http://localhost:8001/healthz     # Weather Agent

# Test the playground
open http://localhost:3001  # macOS
# or visit http://localhost:3001 in your browser

Step 5: API Testing with Postman

For comprehensive testing of all endpoints and features:

# Import Postman collections and environment
# 1. Open Postman
# 2. Import: postman/environments/Orbit.postman_environment.json
# 3. Import: All collections from postman/collections/

What you get:

• ✅ Pre-configured endpoints for all 4 samples
• ✅ Health checks, streaming tests, MCP tool testing
• ✅ Complete API coverage with example requests
• ✅ Observability and metrics testing

Quick test: Run "Health Checks" folder in any collection to verify all services.

See postman/README.md for detailed testing workflows and troubleshooting.

Configuration (Optional)

Custom AWS Credentials

By default, services use pre-configured Orbit Sandbox credentials. To use your own:

# 1. Create custom environment file
cp .env.example .env.local

# 2. Edit .env.local with your credentials
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

# 3. Restart services
docker-compose down && docker-compose up -d

Playground AI Provider Keys

Add optional AI provider keys to test different endpoints:

# Edit playground/.env.local
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key

Service Endpoints

You can immediately access all services:

SaaS Sample Kit:
  • API Server:     http://localhost:4000
  • MCP Server:     http://localhost:3050
  • Python Agent:  http://localhost:8000

Weather Forecast Agent:
  • MCP Server:     http://localhost:3049
  • Python Agent:  http://localhost:8001

RAG Knowledge Base Agent:
  • Python Agent:  http://localhost:8002
  • Health Check:   http://localhost:8002/health

Web Scraper Agent:
  • Python Agent:  http://localhost:8003
  • Health Check:   http://localhost:8003/health
  • API Docs:       http://localhost:8003/docs

Orbit Playground:
  • Web Interface:  http://localhost:3001

Using the Playground

The playground at http://localhost:3001 provides a testing environment for AI endpoints:

Quick Test

1. Visit http://localhost:3001
2. Try the sample endpoints - Pre-configured connections to all 4 agents
3. Add custom endpoints - Test your own APIs, agents, or MCP servers

Creating Custom Endpoints

1. Click "Add Endpoint"
2. Configure:
   • Name: Display name for your endpoint
   • Type: agent (Strands) or api (REST)
   • Base URL: Your service endpoint
   • Credentials: API keys, headers, auth tokens

Supported AI SDKs

• Strands: Custom agent framework with streaming
• AI SDK (Vercel): Modern AI framework with streaming
• OpenAI: Direct OpenAI API integration

Troubleshooting

Quick Fixes

Services not starting:

# Stop and restart
docker-compose down
docker-compose up -d

# Check service status
docker-compose ps

Port conflicts:

# Find what's using a port
lsof -i :3001

# Kill conflicting process
sudo kill -9 <PID>

View logs:

# All services
docker-compose logs -f

# Specific service
docker-compose logs playground
docker-compose logs saas-agent

Reset everything:

# Nuclear option - removes all containers and volumes
docker-compose down -v
docker-compose up -d

Next Steps

Choose Your Learning Path

New to MCP? → Start with Sample 01 (SaaS Sample Kit) - learn MCP basics and dual transport support

Building AI Agents? → Try Sample 02 (Weather Forecast Agent) - structured UI components and Chart.js generation

Need Document Retrieval? → Explore Sample 03 (RAG Knowledge Base) - AWS Bedrock KB integration

Collecting Web Data? → Check out Sample 04 (Web Scraper) - ethical scraping with natural language queries

Testing APIs? → Use the Playground - test different AI SDKs and endpoints

Customization for Your Business

1. Fork the repo - Create your own copy for customization
2. Update business models - Replace sample data with your domain
3. Adapt MCP tools - Modify tools for your specific requirements
4. Customize prompts - Tailor agent system prompts for your use cases

Each sample includes comprehensive documentation in its README.md and API testing collections in postman/.

Advanced Usage

Running Individual Services

Docker (Selective Services)

# Run specific services
docker-compose up -d mongo playground  # Just playground + database
docker-compose up -d saas-agent        # Just SaaS agent
docker-compose up -d weather-agent weather-mcp  # Weather agent + MCP

# Scale specific services
docker-compose up -d --scale saas-agent=2  # Multiple agent instances

Keeping Your Fork Updated

If you forked the repository, you'll want to keep it synchronized with the upstream repository to get updates and new features.

Sync with Upstream

1. Fetch upstream changes:

git fetch upstream

2. Update your local main branch:

git checkout main
git merge --ff-only upstream/main

3. Push updates to your fork:

git push origin main

Working with Feature Branches

Create feature branches for your customizations:

git checkout main
git pull origin main
git switch -c feat/your-customization

# make your changes...
git add -A
git commit -m "Describe your customization"
git push -u origin feat/your-customization

Update feature branches with latest upstream:

git checkout feat/your-customization
git rebase main  # Rebase onto updated main
# If conflicts, fix files, then:
# git add -A
# git rebase --continue
git push -f origin feat/your-customization

Built with ❤️ for sister companies implementing AI-powered systems.