🧬 Copilot-LD

Configuration Guide

Comprehensive configuration guide for environment variables and YAML settings across all Copilot-LD components.

Prerequisites

• Node.js 22.0.0 or later
• Git
• GitHub account for authentication and API access

Configuration Files

The Copilot-LD platform uses two primary configuration approaches:

• Environment Variables (config/.env): Runtime configuration for services, networking, and authentication
• JSON Configuration (config/*.json and config/*.yml): Service behavior, tool definitions, and assistant configurations

Environment Variables

Initial Setup

Create your environment configuration:

cp config/.env{.example,}
cp config/config{.example,}.json
cp config/assistants{.example,}.yml
cp config/tools{.example,}.yml

Service Networking

Configure service host and port settings. When using Docker Compose, comment out these variables to use container networking:

Extension Services

# Web Extension (User Interface)
EXTENSION_WEB_HOST=localhost
EXTENSION_WEB_PORT=3000

# Copilot Extension (GitHub Integration)
EXTENSION_COPILOT_HOST=localhost
EXTENSION_COPILOT_PORT=3001

Core Services

# Agent Service (Main Orchestrator)
SERVICE_AGENT_HOST=localhost
SERVICE_AGENT_PORT=3002

# Memory Service (Conversation Storage)
SERVICE_MEMORY_HOST=localhost
SERVICE_MEMORY_PORT=3003

# LLM Service (Language Model Interface)
SERVICE_LLM_HOST=localhost
SERVICE_LLM_PORT=3004

# Vector Service (Embedding Search)
SERVICE_VECTOR_HOST=localhost
SERVICE_VECTOR_PORT=3005

# Tool Service (Function Calls)
SERVICE_TOOL_HOST=localhost
SERVICE_TOOL_PORT=3006

Tool Services

Example tool service configuration:

# Hash Tool Service (Example)
SERVICE_HASH_HOST=localhost
SERVICE_HASH_PORT=3007

GitHub Authentication

Configure GitHub integration for Copilot API access and repository operations:

# GitHub Client ID (20-character string)
GITHUB_CLIENT_ID=your_client_id_here

# GitHub Token (40-character string)
# Alternative: Use scripts/token.js to store in config/.ghtoken
GITHUB_TOKEN=your_github_token_here

Token Generation

Generate a GitHub token using the OAuth device flow:

# Set GITHUB_CLIENT_ID first, then run:
node scripts/token.js

This saves the token to config/.ghtoken which services read automatically. Alternatively, set GITHUB_TOKEN directly in config/.env.

Service Secret

Generate shared secrets for inter-service authentication

# Service Secret (32-character string)
SERVICE_SECRET=your_generated_secret_here

Secret Generation

# Generate and automatically update config/.env
node scripts/secret.js

Storage Configuration

Configure storage backends for data persistence. Supports local filesystem and S3-compatible storage:

Local Storage (Default)

# Use local filesystem (default)
# STORAGE_TYPE=local

S3-Compatible Storage

STORAGE_TYPE=s3

S3_REGION=us-east-1
S3_BUCKET_NAME=copilot-ld
S3_BUCKET_ROLE_ARN=arn:aws:iam::xxxxxxxxxxxx:xxx      # For local development and CI/CD
AWS_ACCESS_KEY_ID=xxx                                 # For MinIO or direct S3 access
AWS_SECRET_ACCESS_KEY=xxx                             # For MinIO or direct S3 access

Development Options

# Enable debug logging for all components
DEBUG=*

# Or enable for specific components
DEBUG=agent

JSON and YAML Configuration

Service Configuration (config.json)

Defines service behavior and operational parameters in JSON format.

{
  "service": {
    "agent": {
      "assistant": "cld:common.Assistant.software-dev-expert",
      "threshold": 0.25,
      "limit": 100,
      "temperature": 0.25,
      "budget": {
        "tokens": 90000,
        "allocation": {
          "tools": 0.1,
          "history": 0.1,
          "context": 0.6
        }
      }
    },
    "llm": {
      "model": "gpt-4o"
    }
  }
}

Tool Configuration (tools.yml)

Defines tool endpoints and their configurations.

sha256_hash:
  method: "hash.Hash.Sha256"
  request: "hash.HashRequest"
  purpose: |
    Create deterministic SHA-256 hash of input text.
  applicability: |
    Use ONLY when user explicitly requests SHA-256 hashing. DO NOT use
    for search or content analysis.
  instructions: |
    Input: Text string in 'input' field. Output: 64-character hexadecimal
    SHA-256 hash.
  evaluation: |
    Returns exactly 64-character hexadecimal string.

Assistant Configuration (assistants.yml)

Defines AI assistant personas and their specialized behaviors.

software-dev-expert:
  descriptor:
    purpose: |
      Provide expert guidance on software development practices, 
      architecture patterns, and best practices
    instructions: |
      Analyze code structure, suggest improvements, provide 
      architectural guidance, and help with implementation patterns.
    applicability: |
      Use for code review, architecture design, refactoring, and 
      software engineering best practices
    evaluation: |
      Success measured by code quality improvements and architectural 
      coherence
  content:
    text: |
      You are a software development expert with deep knowledge of:
      - Software architecture patterns and principles
      - Code quality and maintainability best practices
      - Security considerations in software development

documentation-specialist:
  descriptor:
    purpose: |
      Create, update, and maintain high-quality technical documentation
    instructions: |
      Generate clear, accurate documentation that follows project 
      standards
    applicability: |
      Use for README updates, API documentation, architecture 
      documentation
    evaluation: |
      Success measured by documentation clarity, accuracy, and 
      completeness

Runtime Configuration

Docker Compose Environment

When using Docker Compose, comment out host and port variables to use container networking:

# Comment out for Docker Compose (GNU sed)
sed -i -E '/(HOST|PORT)=/s/^/# /' config/.env

# Start with container networking
docker compose up

Development vs Production

Development Configuration

• Set explicit host/port variables for direct service access
• Use local storage or MinIO for data persistence
• Enable debug logging with DEBUG=*
• Use self-signed certificates for SSL

Production Configuration

• Use container networking (comment out host/port variables)
• Configure S3-compatible storage with proper credentials
• Disable debug logging or set specific namespaces
• Use valid TLS certificates from trusted CA
• Store secrets in AWS Secrets Manager or similar

Environment Variable Reference

SSL Certificate Configuration

For HTTPS support in Docker Compose deployments:

Generate Self-Signed Certificates

# Generate certificates for localhost development
node scripts/cert.js

Use Production Certificates

# Copy your production certificates
cp your-cert.crt data/cert/localhost.crt
cp your-cert.key data/cert/localhost.key

Configuration Validation

Verify your configuration is properly set up:

Test GitHub Authentication

# Test GitHub token validity
node scripts/token.js --validate

Check Service Configuration

# Generate and validate protocol buffer types
mkdir generated
npm run codegen

# Run configuration tests
npm test -- --grep="Config"

Next Steps

Once configuration is complete, proceed to:

• Processing Guide - Set up knowledge base and process content
• Deployment Guide - Deploy to production infrastructure
• Development Guide - Set up local development environment
• Architecture Overview - Understand system components