Codakey
Play
← Back to poco-agent

How to Deploy & Use poco-agent

Poco Agent Deployment & Usage Guide

1. Prerequisites

Required Software

  • Docker & Docker Compose: For containerized deployment
  • Python 3.12+: Required for some backend components
  • Node.js 18+: For frontend development (if running outside Docker)
  • Git: For cloning the repository

Accounts & API Keys

  • Anthropic Claude API Key: Required for the core AI functionality
  • Optional: AWS S3 or Cloudflare R2 account for external storage

System Requirements

  • Minimum 4GB RAM (8GB recommended)
  • 10GB free disk space
  • Linux, macOS, or Windows with WSL2

2. Installation

Clone the Repository

git clone https://github.com/poco-ai/poco-agent.git
cd poco-agent

Quick Start (Recommended)

The fastest way to get started is using the provided script:

./scripts/quickstart.sh

This script will:

  1. Check for Docker installation
  2. Prompt for your Claude API key
  3. Generate configuration files
  4. Start all services via Docker Compose

Manual Installation

If you prefer to run components directly:

# Install backend dependencies
pip install -r requirements.txt

# Install frontend dependencies
npm install

# Build frontend
npm run build

3. Configuration

Environment Variables

Create a .env file in the project root:

# Required: Anthropic API Configuration
ANTHROPIC_API_KEY=your_claude_api_key_here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Optional: External Storage (S3/R2)
S3_ENDPOINT=https://your-s3-endpoint.com
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_REGION=us-east-1

# Optional: Server Configuration
PORT=3000
API_PORT=8000
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_MESSAGE_POLLING_INTERVAL=3000

Configuration Files

  • docker-compose.yml: Main Docker Compose configuration
  • docker-compose.r2.yml: Alternative config for R2 storage
  • config/: Directory containing service-specific configurations
  • frontend/.env.local: Frontend-specific environment variables

API Key Setup

  1. Get your Anthropic API key from console.anthropic.com
  2. Run the quickstart script or add it to your .env file
  3. The system will validate the key on startup

4. Build & Run

Development Mode

# Using Docker Compose (recommended)
docker-compose up --build

# Or run services separately:

# Backend API (FastAPI)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend (Next.js)
npm run dev

# Worker services
python -m app.worker

Production Build

# Build Docker images
docker-compose build

# Or build individual components:
docker build -t poco-frontend -f Dockerfile.frontend .
docker build -t poco-backend -f Dockerfile.backend .

Running Production

# Using Docker Compose
docker-compose -f docker-compose.prod.yml up -d

# Using the provided production script
./scripts/start-production.sh

5. Deployment

Docker-Based Deployment (Recommended)

Poco is designed for Docker deployment. Choose your platform:

Local/On-Premises

# Persistent deployment with data volume
docker-compose up -d

Cloud Platforms

  • AWS ECS/EKS: Use the provided Docker images
  • Google Cloud Run: Serverless container deployment
  • Azure Container Instances: Simple container deployment
  • Fly.io: Easy deployment with fly launch
  • Railway: One-click deployment from GitHub

Kubernetes (Advanced)

# Apply Kubernetes manifests
kubectl apply -f k8s/

Platform-Specific Guides

Railway

# Install Railway CLI
npm i -g @railway/cli

# Deploy
railway up

Fly.io

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Deploy
fly launch
fly deploy

Docker Swarm

# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.yml poco

Storage Considerations

For production deployments, configure external storage:

# In docker-compose.yml, override volume section:
services:
  backend:
    volumes:
      - type: volume
        source: poco-data
        target: /app/data
volumes:
  poco-data:

6. Troubleshooting

Common Issues

1. Docker Compose Fails to Start

Symptoms: Containers exit immediately or fail to start Solution:

# Check logs
docker-compose logs

# Ensure Docker daemon is running
sudo systemctl start docker

# Check available resources
docker system df

2. API Key Authentication Errors

Symptoms: "Invalid API key" or 401 errors Solution:

# Verify API key format
echo $ANTHROPIC_API_KEY

# Test API key directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'

3. Frontend Cannot Connect to Backend

Symptoms: "Connection refused" or CORS errors Solution:

# Check backend is running
curl http://localhost:8000/health

# Update frontend environment
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" >> frontend/.env.local

# Restart services
docker-compose restart

4. Storage Permission Issues

Symptoms: "Permission denied" when writing files Solution:

# Fix volume permissions
sudo chown -R 1000:1000 ./data

# Or use named volumes
docker volume create poco-storage

5. Memory Exhaustion

Symptoms: Containers killed, "OOM" errors Solution:

# Increase Docker memory limit
# In Docker Desktop: Settings → Resources → Memory
# Or in docker-compose.yml:
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 2G

6. MCP/Skills Not Loading

Symptoms: Tools or plugins not appearing in UI Solution:

# Check MCP server configuration
docker-compose exec backend cat /app/config/mcp_servers.json

# Restart MCP service
docker-compose restart backend

# Check logs for MCP errors
docker-compose logs backend | grep -i mcp

Debug Mode

Enable verbose logging for troubleshooting:

# Set debug environment variables
export LOG_LEVEL=debug
export DEBUG=true

# Restart with debug logging
docker-compose down
docker-compose up

Health Checks

Verify all components are working:

# Check API health
curl http://localhost:8000/health

# Check frontend
curl http://localhost:3000/api/health

# Check Docker containers
docker-compose ps

# View real-time logs
docker-compose logs -f

Getting Help

  • Check the GitHub Issues for known problems
  • Review the documentation for detailed guides
  • Join the community discussions for support

Reset Everything

If all else fails, reset to clean state:

# Stop and remove all containers
docker-compose down -v

# Remove all images
docker rmi $(docker images -q)

# Remove all volumes
docker volume prune

# Start fresh
./scripts/quickstart.sh
← Project overviewView alternatives to poco-agent →