Files

Jason Woltje 12abdfe81d feat(#93 ): implement agent spawn via federation

Implements FED-010: Agent Spawn via Federation feature that enables
spawning and managing Claude agents on remote federated Mosaic Stack
instances via COMMAND message type.

Features:
- Federation agent command types (spawn, status, kill)
- FederationAgentService for handling agent operations
- Integration with orchestrator's agent spawner/lifecycle services
- API endpoints for spawning, querying status, and killing agents
- Full command routing through federation COMMAND infrastructure
- Comprehensive test coverage (12/12 tests passing)

Architecture:
- Hub → Spoke: Spawn agents on remote instances
- Command flow: FederationController → FederationAgentService →
  CommandService → Remote Orchestrator
- Response handling: Remote orchestrator returns agent status/results
- Security: Connection validation, signature verification

Files created:
- apps/api/src/federation/types/federation-agent.types.ts
- apps/api/src/federation/federation-agent.service.ts
- apps/api/src/federation/federation-agent.service.spec.ts

Files modified:
- apps/api/src/federation/command.service.ts (agent command routing)
- apps/api/src/federation/federation.controller.ts (agent endpoints)
- apps/api/src/federation/federation.module.ts (service registration)
- apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint)
- apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration)

Testing:
- 12/12 tests passing for FederationAgentService
- All command service tests passing
- TypeScript compilation successful
- Linting passed

Refs #93

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-03 14:37:06 -06:00

3.1 KiB

Raw Blame History

Prerequisites

Required and optional software for Mosaic Stack development.

Required

Node.js 20+

# Install using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Verify installation
node --version  # Should be v20.x.x

pnpm 9+

# Install globally
npm install -g pnpm@9

# Verify installation
pnpm --version  # Should be 9.x.x

PostgreSQL 17+

Option 1: Native Installation (Linux)

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql-17 postgresql-contrib postgresql-17-pgvector

# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verify installation
sudo -u postgres psql --version

Option 2: macOS (Homebrew)

brew install postgresql@17
brew services start postgresql@17

Option 3: Docker (Recommended for Development)

# PostgreSQL will be started via docker compose
# No native installation required

Git 2+

# Ubuntu/Debian
sudo apt install git

# macOS
brew install git

# Verify installation
git --version

Optional

Docker & Docker Compose

Required for containerized deployment and recommended for development.

Linux:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker compose version

macOS:

# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop

# Verify installation
docker --version
docker compose version

Authentik

Required for OIDC authentication in production.

Docker Installation:

# Download Authentik compose file
curl -o authentik-compose.yml https://goauthentik.io/docker-compose.yml

# Start Authentik
docker compose -f authentik-compose.yml up -d

# Access at http://localhost:9000

Or use an existing Authentik instance

See Configuration → Authentik for setup instructions.

Ollama

Required for AI features (optional for core functionality).

Linux:

curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama2

macOS:

brew install ollama

# Pull a model
ollama pull llama2

Or use remote Ollama instance

Configure OLLAMA_MODE=remote and OLLAMA_ENDPOINT in .env.

Verification

Check all required tools are installed:

node --version      # v20.x.x or higher
pnpm --version      # 9.x.x or higher
git --version       # 2.x.x or higher
docker --version    # 24.x.x or higher (if using Docker)
psql --version      # 17.x.x or higher (if using native PostgreSQL)

Next Steps

Proceed to:

Local Setup for native development
Docker Setup for containerized deployment

3.1 KiB Raw Blame History