tasq/node_modules/agentic-flow/docs/guides/DEPLOYMENT.md

🚀 Deployment Options: Complete Guide

5 deployment strategies • Local to cloud scale • Production-ready

---

📑 Quick Navigation

← Back to Main README | MCP Tools ← | Agent Booster →

---

🎯 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

# 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:

# 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

# Install globally
npm install -g agentic-flow

# Verify installation
agentic-flow --version
agentic-flow --help

Configuration

Create ~/.agentic-flow/config.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

# 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:

# 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:

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:

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

# 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:

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:

docker-compose up -d
docker-compose logs -f agent
docker-compose down

CI/CD Integration

GitHub Actions

Create .github/workflows/agent.yml:

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:

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

# 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)

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)

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)

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)

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)

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

# 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:

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:

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

# 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

// 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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
• Agent Booster (Code Transformations)
• ReasoningBank (Learning Memory)
• Multi-Model Router (Cost Optimization)
• MCP Tools Reference

External Resources

• Docker Documentation
• Kubernetes Documentation
• Flow Nexus Platform
• E2B Sandboxes

---

🤝 Contributing

Deployment improvements welcome! See CONTRIBUTING.md.

---

📄 License

MIT License - see LICENSE for details.

---

Deploy anywhere. Local to cloud. Production-ready. 🚀

← Back to Main README