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 (.env files): Runtime configuration for services, networking, and authentication
• JSON/YAML Configuration (config/*.json, config/*.yml, and config/agents/): Service behavior, tool definitions, and agent configurations

Environment Variables

File Organization

Environment variables are organized into multiple files by concern:

Initial Setup

Create your environment configuration from example files:

# Base configuration (required)
cp .env.example .env

# Local development networking (for npm run dev)
cp .env.local.example .env.local

# Docker Compose (for docker compose up)
cp .env.docker.example .env.docker

# Storage backend (choose one)
cp .env.storage.local.example .env.storage.local      # Local filesystem
cp .env.storage.minio.example .env.storage.minio      # MinIO
cp .env.storage.supabase.example .env.storage.supabase # Supabase

# JSON/YAML configuration
cp config/config.example.json config/config.json
cp config/tools.example.yml config/tools.yml

Usage Patterns

Local Development (Local Storage)

# Load environment files
set -a
source .env
source .env.local
source .env.storage.local
set +a

# Start services
npm run dev

Local Development (MinIO Storage)

set -a
source .env
source .env.local
source .env.storage.minio
set +a

npm run dev

Docker Compose (MinIO Storage)

docker compose \
  --env-file .env \
  --env-file .env.docker \
  --env-file .env.storage.minio \
  up

Docker Compose (Supabase Storage)

docker compose \
  --env-file .env \
  --env-file .env.docker \
  --env-file .env.storage.supabase \
  up

Base Configuration (.env)

The base configuration file contains API credentials and secrets required for all deployment modes:

# API Credentials
LLM_TOKEN=your_github_token_with_models_scope
GITHUB_TOKEN=your_github_token
GITHUB_CLIENT_ID=your_client_id
# GitHub Models base URL - API endpoints are organized as:
# - /catalog/models - List available models
# - /inference/chat/completions - Chat completions
# - /inference/embeddings - Embeddings
LLM_BASE_URL=https://models.github.ai

# Service Authentication
SERVICE_SECRET=your_generated_secret
JWT_SECRET=your_jwt_secret

# Debug (optional)
DEBUG=*

GitHub Models Token Generation

Copilot-LD uses GitHub Models for LLM API access. To generate a token with the required models scope:

# Set GITHUB_CLIENT_ID first, then run:
node scripts/env-github.js

This command authenticates with GitHub using OAuth device flow, requests the models scope, and automatically saves both GITHUB_TOKEN and LLM_TOKEN to your .env file. The token is configured to use GitHub Models API by default:

• Base URL: https://models.github.ai
• Model Catalog: GET /catalog/models - List all available models
• Completions: POST /inference/chat/completions - Chat completions
• Embeddings: POST /inference/embeddings - Text embeddings
• Required Scope: models
• Available Models: Visit https://github.com/marketplace/models for the complete list

To use a different LLM provider (e.g., OpenAI):

LLM_TOKEN=your_openai_api_key
LLM_BASE_URL=https://api.openai.com/v1

Secret Generation

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

Local Embedding Service (TEI)

By default, Copilot-LD uses GitHub Models for text embeddings. For faster local inference or offline operation, you can deploy Hugging Face's Text Embeddings Inference (TEI) as a local embedding service.

Installation

Install the TEI binary using Cargo (Rust package manager). TEI requires Rust 1.88.0 or later and the candle feature for CPU inference on macOS:

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Ensure Rust 1.88.0+ is installed
rustup install 1.88.0
rustup default 1.88.0

# Install TEI router with candle feature (required for macOS)
cargo install --git https://github.com/huggingface/text-embeddings-inference \
  --features candle \
  text-embeddings-router

On Linux with pre-built binaries available, a simpler installation works:

cargo install text-embeddings-router

Running TEI Locally

Start TEI with a compatible embedding model:

# Download model on first run and start server
text-embeddings-router --model-id BAAI/bge-small-en-v1.5 --port 8090 --json-output --auto-truncate

The first run downloads the model to ~/.cache/huggingface/. Subsequent starts are faster.

Configuration

Enable local embeddings by setting EMBEDDING_BASE_URL in your environment:

# .env.local - uncomment to use local TEI
EMBEDDING_BASE_URL=http://localhost:8090

When EMBEDDING_BASE_URL is set, the system uses TEI for embeddings while continuing to use GitHub Models for LLM completions. When unset or null, both embeddings and completions use GitHub Models.

Model Selection

TEI supports any Hugging Face sentence-transformer model. For compatibility with the default 1024-dimension vectors:

Smaller models for faster inference (requires re-indexing):

Docker Deployment

For Docker deployments, TEI is included in docker-compose.yml:

tei:
  image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.5
  command:
    --model-id BAAI/bge-small-en-v1.5 --port 8080 --json-output --auto-truncate
  volumes:
    - tei_data:/data
  environment:
    - HF_HOME=/data

Docker automatically configures EMBEDDING_BASE_URL=http://tei.copilot-ld.local:8080.

For GPU acceleration, use the CUDA image:

tei:
  image: ghcr.io/huggingface/text-embeddings-inference:1.5
  deploy:
    resources:
      reservations:
        devices:
          - capabilities: [gpu]

Service Networking (.env.local)

Configure service host and port settings for local development. Do NOT load this file when using Docker Compose—containers use internal DNS for service discovery.

Extension Services

EXTENSION_UI_HOST=localhost
EXTENSION_UI_PORT=3000

EXTENSION_WEB_HOST=localhost
EXTENSION_WEB_PORT=3001
EXTENSION_WEB_URL=http://localhost:3001/web/api

Core Services

SERVICE_AGENT_HOST=localhost
SERVICE_AGENT_PORT=3002

SERVICE_MEMORY_HOST=localhost
SERVICE_MEMORY_PORT=3003

SERVICE_LLM_HOST=localhost
SERVICE_LLM_PORT=3004

SERVICE_VECTOR_HOST=localhost
SERVICE_VECTOR_PORT=3005

SERVICE_GRAPH_HOST=localhost
SERVICE_GRAPH_PORT=3006

SERVICE_TOOL_HOST=localhost
SERVICE_TOOL_PORT=3007

SERVICE_TRACE_HOST=localhost
SERVICE_TRACE_PORT=3008

Docker Proxy (.env.docker)

Proxy configuration for Docker containers to access external APIs:

HTTPS_PROXY=http://gateway.copilot-ld.local:3128
HTTP_PROXY=http://gateway.copilot-ld.local:3128
NO_PROXY=localhost,127.0.0.1,*.copilot-ld.local

Storage Backends

Local Storage (.env.storage.local)

Use local filesystem (default behavior, minimal configuration):

STORAGE_TYPE=local

MinIO Storage (.env.storage.minio)

S3-compatible object storage with MinIO:

STORAGE_TYPE=s3
S3_REGION=us-east-1
S3_BUCKET_NAME=copilot-ld

MINIO_ENDPOINT=http://storage.copilot-ld.local:9000
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=your_password

AWS_ACCESS_KEY_ID=admin
AWS_SECRET_ACCESS_KEY=your_password

Supabase Storage (.env.storage.supabase)

Authentication and S3-compatible storage with Supabase:

STORAGE_TYPE=s3
S3_REGION=local
S3_BUCKET_NAME=copilot-ld

# Database
SUPABASE_DB_PASSWORD=your_database_password

# JWT (shared by Auth and Storage)
SUPABASE_JWT_SECRET=your_jwt_secret

# Auth service keys
SUPABASE_ANON_KEY=your_anon_key_jwt
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_jwt

# Auth settings
SUPABASE_SITE_URL=http://localhost:3000
SUPABASE_DISABLE_SIGNUP=false

# Storage S3 protocol
SUPABASE_S3_ACCESS_KEY=your_s3_access_key
SUPABASE_S3_SECRET_KEY=your_s3_secret_key

# AWS SDK credentials
AWS_ACCESS_KEY_ID=your_s3_access_key
AWS_SECRET_ACCESS_KEY=your_s3_secret_key

# Enable auth in web extension
EXTENSION_WEB_AUTH_ENABLED=true

JSON and YAML Configuration

Service Configuration (config.json)

Defines service parameters, process supervision, and available tools in JSON format.

Process Supervision

The init section configures the process supervision system (svscan and rc):

{
  "init": {
    "log_dir": "data/logs",
    "shutdown_timeout": 3000,
    "services": [
      {
        "name": "agent",
        "command": "npx env-cmd -- npm run dev -w @copilot-ld/agent"
      }
    ]
  }
}

• log_dir: Directory for service logs (default: data/logs)
• shutdown_timeout: Maximum milliseconds to wait for graceful shutdown (default: 3000)
• services: Array of services to supervise with name and command properties

Service Parameters

The service section defines service-specific configuration:

{
  "service": {
    "agent": {
      "agent": "knowledge_graph_agent",
      "tools": ["get_ontology", "search_content", "query_by_pattern"],
      "threshold": 0.25,
      "temperature": 0.25,
      "budget": {
        "tokens": 90000,
        "allocation": {
          "tools": 0.1,
          "resources": 0.1,
          "results": 0.8
        }
      }
    },
    "tool": {
      "endpoints": {
        "get_ontology": {
          "method": "graph.Graph.GetOntology",
          "request": "graph.OntologyRequest"
        },
        "query_by_pattern": {
          "method": "graph.Graph.QueryByPattern",
          "request": "graph.PatternQuery"
        },
        "search_content": {
          "method": "vector.Vector.SearchContent",
          "request": "vector.TextQuery"
        }
      }
    }
  }
}

Tool Configuration (tools.yml)

Defines tool metadata in YAML format:

sha256_hash:
  purpose: |
    Generate a deterministic SHA-256 cryptographic hash of input text for
    security, verification, or identification purposes.
  applicability: |
    SEQUENCING: Independent utility - no sequencing requirements.
    Use ONLY when user explicitly requests SHA-256 hashing functionality.
    DO NOT use for search, content analysis, or similarity detection.
    Reserved for security, verification, and identification use cases.
  instructions: |
    Input: Text string in 'input' field to be hashed.
    Output: Deterministic 64-character hexadecimal SHA-256 hash string.
    Hash is cryptographically secure and suitable for verification purposes.
  evaluation: |
    Returns exactly 64-character hexadecimal string representing the SHA-256
    hash of the input text.

Agent Configuration (config/agents/)

Agents are defined as individual .agent.md files in the config/agents/ directory. Each file uses frontmatter for metadata and markdown for the system prompt.

---
name: knowledge_graph_agent
description: "An expert knowledge graph agent for querying information."
temperature: 0.3
tools:
  - get_ontology
  - get_subjects
  - search_content
  - query_by_pattern
infer: true
handoffs: []
---

You are an expert knowledge graph agent that queries and retrieves information.

## CHAIN OF THOUGHT

Explain your reasoning before taking any action...

Each agent file has:

• Frontmatter (YAML between --- markers):

  • name: Agent identifier (matches filename without .agent.md)
  • description: Brief description of the agent's purpose
  • temperature: LLM temperature setting (0.0-1.0)
  • tools: Optional array of tool function names
  • infer: Whether this agent can be invoked as a sub-agent
  • handoffs: Optional array of handoff configurations

• Markdown Body: System prompt defining the agent's persona and behavior

Handoff Configuration

Handoffs define how an agent can transfer control to another agent:

handoffs:
  - label: "Code Review"
    agent: code_review_agent
    prompt: "Please review the code we discussed."

Each handoff has:

• label: Human-readable label for the handoff
• agent: Target agent name (without path or extension)
• prompt: Message injected when handoff occurs

Runtime Configuration

Variable Precedence

When loading multiple .env files, later files override earlier ones. Load files in this order:

1. .env (base credentials and secrets)
2. .env.local OR .env.docker (networking mode)
3. .env.storage.* (storage backend)

Development vs Production

Development Configuration

• Load .env.local 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

• Load .env.docker for container networking
• 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

Next Steps

Once configuration is complete, proceed to:

• Processing Guide - Transform HTML knowledge into searchable resources
• Deployment Guide - Launch with Docker Compose or AWS CloudFormation
• Development Guide - Run locally with live reloading