agentic-flow 1.8.15 → 1.9.0

package/agentic-flow/docs/guides/DEPLOYMENT.md

@@ -0,0 +1,906 @@
+# 🚀 Deployment Options: Complete Guide
+
+**5 deployment strategies • Local to cloud scale • Production-ready**
+
+---
+
+## 📑 Quick Navigation
+
+[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md) | [MCP Tools ←](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MCP-TOOLS.md) | [Agent Booster →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/AGENT-BOOSTER.md)
+
+---
+
+## 🎯 Deployment Strategy Overview
+
+Choose the right deployment based on your needs:
+
+| Deployment | Best For | Setup Time | Cost | Scale |
+|------------|----------|------------|------|-------|
+| **Local (npx)** | Development, testing | 30 seconds | Free | 1-10 agents |
+| **Local (Global)** | Personal projects | 2 minutes | Free | 10-50 agents |
+| **Docker** | CI/CD, production | 10 minutes | Low | 50-500 agents |
+| **Kubernetes** | Enterprise scale | 30 minutes | Medium | 500-10K+ agents |
+| **Flow Nexus Cloud** | Instant scale, managed | 5 minutes | Pay-as-you-go | Unlimited |
+
+---
+
+## 1️⃣ Local Development (npx)
+
+**Perfect for**: Quick experiments, one-off tasks, development
+
+### Quick Start
+
+```bash
+# No installation needed - run directly
+npx agentic-flow --agent coder --task "Build a REST API"
+
+# With specific model
+npx agentic-flow \
+  --agent researcher \
+  --task "Analyze microservices trends" \
+  --model "claude-3-5-sonnet-20241022"
+
+# With streaming output
+npx agentic-flow \
+  --agent coder \
+  --task "Create web scraper" \
+  --stream
+```
+
+### Configuration
+
+Set environment variables:
+
+```bash
+# API Keys
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENROUTER_API_KEY=sk-or-...
+export GOOGLE_GEMINI_API_KEY=...
+
+# Optional: Model preferences
+export PROVIDER=anthropic  # anthropic, openrouter, gemini, onnx
+export MODEL=claude-3-5-sonnet-20241022
+
+# Optional: Cost optimization
+export ROUTER_ENABLED=true
+export ROUTER_PRIORITY=balanced  # cost, quality, speed, balanced
+```
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Zero installation
+- ✅ Perfect for quick tasks
+- ✅ Always latest version
+- ✅ No configuration needed
+
+**Cons:**
+- ❌ Slower startup (downloads on each run)
+- ❌ No persistent configuration
+- ❌ Limited to single agent tasks
+
+---
+
+## 2️⃣ Local Installation (Global)
+
+**Perfect for**: Regular use, personal automation, local development
+
+### Installation
+
+```bash
+# Install globally
+npm install -g agentic-flow
+
+# Verify installation
+agentic-flow --version
+agentic-flow --help
+```
+
+### Configuration
+
+Create `~/.agentic-flow/config.json`:
+
+```json
+{
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-3-5-sonnet-20241022",
+  "router": {
+    "enabled": true,
+    "priority": "balanced",
+    "maxCost": 1.00
+  },
+  "providers": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}",
+      "baseUrl": "https://api.anthropic.com"
+    },
+    "openrouter": {
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "baseUrl": "https://openrouter.ai/api/v1"
+    },
+    "gemini": {
+      "apiKey": "${GOOGLE_GEMINI_API_KEY}"
+    }
+  },
+  "reasoningbank": {
+    "enabled": true,
+    "dbPath": "~/.agentic-flow/memory.db"
+  }
+}
+```
+
+### Usage
+
+```bash
+# Run agents directly
+agentic-flow --agent coder --task "Build API"
+
+# List available agents
+agentic-flow --list
+
+# MCP server management
+agentic-flow mcp add weather 'npx @modelcontextprotocol/server-weather'
+agentic-flow mcp list
+agentic-flow mcp remove weather
+
+# ReasoningBank commands
+agentic-flow reasoningbank init
+agentic-flow reasoningbank status
+```
+
+### Advanced Configuration
+
+Create `~/.agentic-flow/agents/custom-agent.md`:
+
+```markdown
+# Custom Developer Agent
+
+## Role
+Full-stack developer specializing in React and Node.js
+
+## Capabilities
+- Frontend: React, TypeScript, Tailwind
+- Backend: Node.js, Express, PostgreSQL
+- DevOps: Docker, GitHub Actions
+
+## Instructions
+You are an expert full-stack developer. Always:
+1. Write TypeScript with strict types
+2. Include comprehensive tests
+3. Follow clean code principles
+4. Document all public APIs
+```
+
+Then use it:
+
+```bash
+agentic-flow --agent custom-developer --task "Build dashboard"
+```
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Fast startup (no downloads)
+- ✅ Persistent configuration
+- ✅ Custom agents support
+- ✅ Full MCP tool access
+
+**Cons:**
+- ❌ Manual updates needed
+- ❌ Single machine only
+- ❌ Limited to local resources
+
+---
+
+## 3️⃣ Docker Deployment
+
+**Perfect for**: CI/CD pipelines, reproducible environments, production
+
+### Basic Dockerfile
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+# Install dependencies
+RUN apk add --no-cache \
+    git \
+    python3 \
+    make \
+    g++
+
+# Create app directory
+WORKDIR /app
+
+# Install agentic-flow
+RUN npm install -g agentic-flow
+
+# Copy configuration
+COPY config.json /root/.agentic-flow/config.json
+
+# Set environment variables
+ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+ENV OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+
+# Entry point
+ENTRYPOINT ["agentic-flow"]
+CMD ["--help"]
+```
+
+### Build and Run
+
+```bash
+# Build image
+docker build -t agentic-flow:latest .
+
+# Run single agent
+docker run --rm \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  agentic-flow:latest \
+  --agent coder \
+  --task "Build REST API"
+
+# Run with volume mount (for persistent memory)
+docker run --rm \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  -v $(pwd)/memory:/root/.agentic-flow \
+  agentic-flow:latest \
+  --agent researcher \
+  --task "Analyze trends"
+```
+
+### Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  agent:
+    build: .
+    image: agentic-flow:latest
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+      - ROUTER_ENABLED=true
+      - REASONINGBANK_ENABLED=true
+    volumes:
+      - ./config:/root/.agentic-flow
+      - ./data:/data
+    command: --agent coder --task "Build API"
+
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=agentic_flow
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+  redis_data:
+```
+
+Run with:
+
+```bash
+docker-compose up -d
+docker-compose logs -f agent
+docker-compose down
+```
+
+### CI/CD Integration
+
+#### GitHub Actions
+
+Create `.github/workflows/agent.yml`:
+
+```yaml
+name: Run Agentic Flow
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  code-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Run code review agent
+        uses: docker://agentic-flow:latest
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          args: --agent reviewer --task "Review PR changes"
+
+      - name: Run tests
+        run: npm test
+```
+
+#### GitLab CI
+
+Create `.gitlab-ci.yml`:
+
+```yaml
+stages:
+  - review
+  - test
+
+code-review:
+  stage: review
+  image: agentic-flow:latest
+  script:
+    - agentic-flow --agent reviewer --task "Review MR $CI_MERGE_REQUEST_IID"
+  only:
+    - merge_requests
+  variables:
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+```
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Reproducible environments
+- ✅ Easy CI/CD integration
+- ✅ Version control for config
+- ✅ Isolated dependencies
+
+**Cons:**
+- ❌ Docker overhead
+- ❌ More complex setup
+- ❌ Resource limits per container
+
+---
+
+## 4️⃣ Kubernetes Deployment
+
+**Perfect for**: Enterprise scale, high availability, auto-scaling
+
+### Prerequisites
+
+```bash
+# Install kubectl
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+
+# Install Helm
+curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+```
+
+### Kubernetes Manifests
+
+#### 1. ConfigMap (`config.yaml`)
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: agentic-flow-config
+  namespace: agentic-flow
+data:
+  config.json: |
+    {
+      "defaultProvider": "anthropic",
+      "router": {
+        "enabled": true,
+        "priority": "balanced"
+      }
+    }
+```
+
+#### 2. Secret (`secrets.yaml`)
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: agentic-flow-secrets
+  namespace: agentic-flow
+type: Opaque
+stringData:
+  anthropic-api-key: sk-ant-...
+  openrouter-api-key: sk-or-...
+```
+
+#### 3. Deployment (`deployment.yaml`)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: agentic-flow-agent
+  namespace: agentic-flow
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: agentic-flow
+  template:
+    metadata:
+      labels:
+        app: agentic-flow
+    spec:
+      containers:
+      - name: agent
+        image: agentic-flow:latest
+        env:
+        - name: ANTHROPIC_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: agentic-flow-secrets
+              key: anthropic-api-key
+        - name: OPENROUTER_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: agentic-flow-secrets
+              key: openrouter-api-key
+        - name: ROUTER_ENABLED
+          value: "true"
+        volumeMounts:
+        - name: config
+          mountPath: /root/.agentic-flow
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "500m"
+          limits:
+            memory: "2Gi"
+            cpu: "2000m"
+      volumes:
+      - name: config
+        configMap:
+          name: agentic-flow-config
+```
+
+#### 4. Service (`service.yaml`)
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: agentic-flow-service
+  namespace: agentic-flow
+spec:
+  selector:
+    app: agentic-flow
+  ports:
+  - protocol: TCP
+    port: 8080
+    targetPort: 8080
+  type: LoadBalancer
+```
+
+#### 5. HorizontalPodAutoscaler (`hpa.yaml`)
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: agentic-flow-hpa
+  namespace: agentic-flow
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: agentic-flow-agent
+  minReplicas: 3
+  maxReplicas: 100
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70
+  - type: Resource
+    resource:
+      name: memory
+      target:
+        type: Utilization
+        averageUtilization: 80
+```
+
+### Deploy to Kubernetes
+
+```bash
+# Create namespace
+kubectl create namespace agentic-flow
+
+# Apply manifests
+kubectl apply -f config.yaml
+kubectl apply -f secrets.yaml
+kubectl apply -f deployment.yaml
+kubectl apply -f service.yaml
+kubectl apply -f hpa.yaml
+
+# Verify deployment
+kubectl get pods -n agentic-flow
+kubectl get svc -n agentic-flow
+
+# View logs
+kubectl logs -f deployment/agentic-flow-agent -n agentic-flow
+
+# Scale manually
+kubectl scale deployment/agentic-flow-agent --replicas=10 -n agentic-flow
+```
+
+### Helm Chart
+
+Create `helm/agentic-flow/values.yaml`:
+
+```yaml
+replicaCount: 3
+
+image:
+  repository: agentic-flow
+  tag: latest
+  pullPolicy: IfNotPresent
+
+resources:
+  requests:
+    memory: "512Mi"
+    cpu: "500m"
+  limits:
+    memory: "2Gi"
+    cpu: "2000m"
+
+autoscaling:
+  enabled: true
+  minReplicas: 3
+  maxReplicas: 100
+  targetCPUUtilization: 70
+  targetMemoryUtilization: 80
+
+config:
+  defaultProvider: anthropic
+  router:
+    enabled: true
+    priority: balanced
+
+secrets:
+  anthropicApiKey: ""  # Set via --set secrets.anthropicApiKey=sk-ant-...
+  openrouterApiKey: ""
+```
+
+Install with Helm:
+
+```bash
+helm install agentic-flow ./helm/agentic-flow \
+  --namespace agentic-flow \
+  --create-namespace \
+  --set secrets.anthropicApiKey=sk-ant-... \
+  --set secrets.openrouterApiKey=sk-or-...
+```
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Auto-scaling (3-100+ pods)
+- ✅ High availability
+- ✅ Rolling updates
+- ✅ Health checks & self-healing
+- ✅ Enterprise-grade
+
+**Cons:**
+- ❌ Complex setup
+- ❌ Higher infrastructure cost
+- ❌ Requires Kubernetes expertise
+
+---
+
+## 5️⃣ Flow Nexus Cloud
+
+**Perfect for**: Instant scale, managed infrastructure, zero DevOps
+
+### Quick Start
+
+```bash
+# Install Flow Nexus CLI
+npm install -g flow-nexus
+
+# Register account
+npx flow-nexus register
+
+# Login
+npx flow-nexus login
+
+# Deploy swarm
+npx flow-nexus swarm create \
+  --topology mesh \
+  --max-agents 10 \
+  --strategy balanced
+```
+
+### Cloud Deployment via MCP
+
+```javascript
+// Initialize cloud swarm
+await query({
+  mcp: {
+    server: 'flow-nexus',
+    tool: 'swarm_init',
+    params: {
+      topology: 'mesh',
+      maxAgents: 50,
+      strategy: 'adaptive'
+    }
+  }
+});
+
+// Spawn cloud agents
+await query({
+  mcp: {
+    server: 'flow-nexus',
+    tool: 'agent_spawn',
+    params: {
+      type: 'coder',
+      name: 'cloud-backend-dev'
+    }
+  }
+});
+
+// Create cloud sandbox for execution
+await query({
+  mcp: {
+    server: 'flow-nexus',
+    tool: 'sandbox_create',
+    params: {
+      template: 'node',
+      env_vars: {
+        DATABASE_URL: '...',
+        API_KEY: '...'
+      }
+    }
+  }
+});
+```
+
+### Features
+
+- **Instant Scale**: 0 to 1000+ agents in seconds
+- **Managed Infrastructure**: No servers to maintain
+- **E2B Sandboxes**: Isolated execution environments
+- **Neural Network Training**: Distributed GPU acceleration
+- **Real-time Monitoring**: Live execution streams
+- **Pay-as-you-go**: Only pay for what you use
+
+### Pricing
+
+| Tier | Price | Agents | Features |
+|------|-------|--------|----------|
+| **Free** | $0/month | 5 concurrent | Basic features |
+| **Pro** | $29/month | 50 concurrent | Neural networks, sandboxes |
+| **Team** | $99/month | 200 concurrent | Priority support, SLA |
+| **Enterprise** | Custom | Unlimited | Dedicated, custom SLA |
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Zero infrastructure management
+- ✅ Instant global scale
+- ✅ Built-in neural networks
+- ✅ E2B sandbox integration
+- ✅ Real-time monitoring
+
+**Cons:**
+- ❌ Requires internet connection
+- ❌ Monthly cost (after free tier)
+- ❌ Data leaves your infrastructure
+
+---
+
+## 🔒 Security Best Practices
+
+### API Key Management
+
+```bash
+# Use environment variables
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Use secrets management (Kubernetes)
+kubectl create secret generic api-keys \
+  --from-literal=anthropic=sk-ant-... \
+  --from-literal=openrouter=sk-or-...
+
+# Use HashiCorp Vault
+vault kv put secret/agentic-flow \
+  anthropic_key=sk-ant-... \
+  openrouter_key=sk-or-...
+```
+
+### Network Security
+
+```yaml
+# Kubernetes NetworkPolicy
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: agentic-flow-netpol
+  namespace: agentic-flow
+spec:
+  podSelector:
+    matchLabels:
+      app: agentic-flow
+  policyTypes:
+  - Ingress
+  - Egress
+  ingress:
+  - from:
+    - namespaceSelector:
+        matchLabels:
+          name: agentic-flow
+    ports:
+    - protocol: TCP
+      port: 8080
+  egress:
+  - to:
+    - namespaceSelector: {}
+    ports:
+    - protocol: TCP
+      port: 443  # HTTPS only
+```
+
+### Data Protection
+
+- **Encrypt at rest**: Use encrypted volumes
+- **Encrypt in transit**: TLS 1.3 for all communications
+- **PII scrubbing**: Enable ReasoningBank PII scrubber
+- **Audit logging**: Track all API calls and agent actions
+
+---
+
+## 📊 Performance Optimization
+
+### Local Optimization
+
+```bash
+# Enable caching
+export CACHE_ENABLED=true
+export CACHE_TTL=3600
+
+# Limit concurrency
+export MAX_CONCURRENT_AGENTS=5
+
+# Use local ONNX models
+export PROVIDER=onnx
+export ONNX_MODEL_PATH=./models/phi-4
+```
+
+### Docker Optimization
+
+```dockerfile
+# Multi-stage build for smaller images
+FROM node:18-alpine AS builder
+WORKDIR /app
+RUN npm install -g agentic-flow --production
+
+FROM node:18-alpine
+COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
+COPY --from=builder /usr/local/bin/agentic-flow /usr/local/bin/agentic-flow
+```
+
+### Kubernetes Optimization
+
+```yaml
+# Resource limits
+resources:
+  requests:
+    memory: "256Mi"  # Start small
+    cpu: "250m"
+  limits:
+    memory: "1Gi"    # Allow bursts
+    cpu: "1000m"
+
+# Pod affinity for better locality
+affinity:
+  podAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+    - weight: 100
+      podAffinityTerm:
+        labelSelector:
+          matchLabels:
+            app: agentic-flow
+        topologyKey: kubernetes.io/hostname
+```
+
+---
+
+## 📈 Monitoring & Observability
+
+### Prometheus Metrics
+
+```yaml
+# ServiceMonitor for Prometheus
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: agentic-flow
+  namespace: agentic-flow
+spec:
+  selector:
+    matchLabels:
+      app: agentic-flow
+  endpoints:
+  - port: metrics
+    interval: 30s
+```
+
+### Grafana Dashboard
+
+Import dashboard JSON:
+- Panel 1: Agent count over time
+- Panel 2: Task success rate
+- Panel 3: Average task duration
+- Panel 4: Token usage
+- Panel 5: Cost tracking
+
+### Logging
+
+```yaml
+# Fluentd configuration
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: fluentd-config
+data:
+  fluent.conf: |
+    <source>
+      @type tail
+      path /var/log/agentic-flow/*.log
+      tag agentic-flow.*
+    </source>
+    <match agentic-flow.**>
+      @type elasticsearch
+      host elasticsearch.logging.svc
+      port 9200
+    </match>
+```
+
+---
+
+## 🔗 Related Documentation
+
+### Core Components
+- [← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)
+- [Agent Booster (Code Transformations)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/AGENT-BOOSTER.md)
+- [ReasoningBank (Learning Memory)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/REASONINGBANK.md)
+- [Multi-Model Router (Cost Optimization)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MULTI-MODEL-ROUTER.md)
+- [MCP Tools Reference](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MCP-TOOLS.md)
+
+### External Resources
+- [Docker Documentation](https://docs.docker.com)
+- [Kubernetes Documentation](https://kubernetes.io/docs)
+- [Flow Nexus Platform](https://flow-nexus.ruv.io)
+- [E2B Sandboxes](https://e2b.dev)
+
+---
+
+## 🤝 Contributing
+
+Deployment improvements welcome! See [CONTRIBUTING.md](https://github.com/ruvnet/agentic-flow/blob/main/CONTRIBUTING.md).
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](https://github.com/ruvnet/agentic-flow/blob/main/LICENSE) for details.
+
+---
+
+**Deploy anywhere. Local to cloud. Production-ready.** 🚀
+
+[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)