realm-spawn¶

The realm factory - automated generation of new AI agents

Realm-spawn is a meta-agent that creates new F3L1X realms on demand. Give it a blueprint (purpose, capabilities, integrations) and it scaffolds a complete Django application with pre-configured architecture, patterns, and integration hooks—ready to deploy in minutes.

What It Does¶

Realm-spawn automates realm creation:

1. Project Scaffolding - Generate Django project structure
2. Configuration - Set up settings, database, environment
3. Integration - Wire up Herald, Redis, PostgreSQL connections
4. Patterns - Apply HackSoftware architecture and conventions
5. Testing - Generate test suite stubs
6. Documentation - Create CLAUDE.md, README, specs

Think of realm-spawn as your development team multiplied—it creates quality Django projects in seconds that would take hours to set up manually.

Key Capabilities¶

Project Generation¶

• Django Structure: Automatic config/ and apps/ directories
• Settings Split: Separate base, local, production configurations
• ASGI/WSGI: Full async support with Daphne configured
• WhiteNoise: Static file serving pre-configured
• Environment Vars: .env template auto-created

Architecture Setup¶

• HackSoftware Pattern: Industry-standard Django structure
• Service Layer: services.py for write operations pre-scaffolded
• Selectors: selectors.py for read operations template
• Models: Base models with UUID primary keys
• Admin: Django admin pre-configured
• Testing: Pytest integration ready

Integration Hooks¶

• Herald Connection: Pre-configured to join message network
• Redis Connection: Async tasks, caching ready
• PostgreSQL: Database config with migrations
• Celery: Async task queue optional integration
• MCP Tools: Template for exposing realm as MCP tool

Customization Options¶

• App Templates: Create additional Django apps
• Models: Generate model skeletons with fields
• Views: Generate view templates for common patterns
• Forms: Auto-generate forms from models
• Admin: Register models in admin automatically

Accessing realm-spawn¶

Web Dashboard¶

URL: http://127.0.0.1:8029

The realm-spawn dashboard shows:
- Realm creation wizard
- Configuration builder
- Generated realm preview
- Deployment checklist

Command Line Interface¶

# Interactive realm creation
python manage.py spawn

# Create realm from template
python manage.py spawn --name my-new-realm --template django-service

# Create realm with specific port
python manage.py spawn --name my-realm --port 8042

# Dry run (preview without creating)
python manage.py spawn --name test --dry-run

Spawn API¶

Common Use Cases¶

Use Case 1: Create New Service Realm¶

Goal: Quickly scaffold a new Django application

python manage.py spawn \
  --name transcriber-v2 \
  --template django-service \
  --port 8031

Realm-spawn generates:
- Complete Django project at /active/transcriber-v2/
- Configured to join Herald network
- Database migrations ready
- Tests framework set up
- Documentation in README and CLAUDE.md

In 30 seconds, what would take hours manually.

Use Case 2: Create API Realm¶

Goal: Build a REST API service

python manage.py spawn \
  --name api-gateway \
  --template django-rest \
  --port 8044 \
  --apps users,products,orders

Realm-spawn generates:
- Django REST Framework configured
- Automatic CRUD endpoints for specified models
- Authentication via Herald JWT
- Pagination, filtering, sorting
- API documentation (Swagger/OpenAPI)

Use Case 3: Create Async Worker Realm¶

Goal: Build background job processor

python manage.py spawn \
  --name worker-tasks \
  --template django-celery \
  --port 8045 \
  --queue-name heavy-work

Realm-spawn generates:
- Celery task definitions
- Redis connection configured
- Task monitoring dashboard
- Retry logic and error handling
- Async logging

Use Case 4: Create Tool Wrapper Realm¶

Goal: Wrap external tool as MCP marketplace tool

python manage.py spawn \
  --name whisper-transcriber \
  --template mcp-tool \
  --port 8046 \
  --tool-name transcriber

Realm-spawn generates:
- MCP tool handler
- Herald marketplace registration
- x402 payment integration
- Tool validation and error handling
- Pricing configuration interface

Important Notes¶

Templates Available¶

Port Assignment¶

Realm-spawn suggests the next available port:
- Essential realms: 8000-8090 (reserved)
- Custom realms: 8091+ (automatically assigned)

You can override with --port flag but verify port isn't in use first.

Generated Structure¶

Every spawned realm includes proper Django structure with config/ and apps/ directories for HackSoftware pattern, including CLAUDE.md, spec.md, init.sh, and comprehensive testing setup.

Customization After Generation¶

After realm-spawn creates your realm, you customize:

1. Models - Add fields to apps/{app}/models.py
2. Views - Implement logic in apps/{app}/views.py
3. Services - Create services.py functions for business logic
4. Templates - Add HTML in apps/{app}/templates/
5. Tests - Write tests in apps/{app}/tests/

Realm-spawn provides the scaffolding; you add the logic.

Troubleshooting¶

Port already in use¶

Symptom: Realm creation fails with "port already in use"
Fix: Use different port with --port flag, or identify and stop existing service

Template not found¶

Symptom: Specified template does not exist
Fix: Run python manage.py spawn templates to see available templates

Virtual environment creation fails¶

Symptom: venv/ directory not created
Fix: Verify Python 3.13+ installed: python --version

Database migrations not applied¶

Symptom: Created realm shows migration errors
Fix: Run python manage.py migrate in new realm directory

Can't connect to Herald¶

Symptom: Realm created but cannot join Herald network
Fix: Verify Herald is running on :8014, check .env HERALD_HOST setting

Related Realms¶

• herald - Newly spawned realms automatically register with Herald
• worker-bee - Monitors newly spawned realms for health
• doc-u-me - Can index documentation of spawned realms
• pipeline-go - Defines standards that realm-spawn enforces

Further Reading¶

• Creating Custom Realms
• Django Architecture & Patterns
• MCP Tool Development