.env.example

# ============================================================================
# HuggingClip - Paperclip on Hugging Face Spaces
# Configuration Reference
# ============================================================================

# ============================================================================
# Hugging Face Integration (REQUIRED for backup persistence)
# ============================================================================

# Your Hugging Face API token (needed for backup/restore)
# Get it from: https://huggingface.co/settings/tokens
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Your Hugging Face username (optional, auto-detected from token if not set)
# HF_USERNAME=your-username

# ============================================================================
# Paperclip Core Configuration
# ============================================================================

# PostgreSQL connection string
# Format: postgres://user:password@host:port/database
DATABASE_URL=postgres://postgres:paperclip@localhost:5432/paperclip

# Paperclip API port
PORT=3100

# Serve the Paperclip UI (true/false)
SERVE_UI=true

# Node.js environment (development/production)
NODE_ENV=production

# Server bind address
HOST=0.0.0.0

# Paperclip home directory for config/data storage
PAPERCLIP_HOME=/paperclip

# Deployment mode (local/authenticated)
# Use 'authenticated' for production with Better Auth
PAPERCLIP_DEPLOYMENT_MODE=authenticated

# ============================================================================
# Paperclip Agent Providers (varies by setup)
# ============================================================================

# Claude Code — choose one mode or neither:
#
# Subscription mode (Claude Pro/Max — no per-token cost):
#   Generate a long-lived token (valid 1 year) at:
#   claude.ai → Settings → Claude Code → "Create token"
#   Then set: export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxxxxxxxxxxxxxxxxx
#
# API key mode (pay-per-use):
# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
#
# Neither set → Claude Code uses stored OAuth credentials from ~/.claude/
#               (requires first-time login inside the container)

# For other LLM providers (OpenAI, etc.)
# LLM_API_KEY=your-api-key

# Allow Claude Code to use all models (default: restricted)
OPENCODE_ALLOW_ALL_MODELS=true

# ============================================================================
# Cloudflare Proxy (Optional - for bypassing HF Spaces network blocks)
# ============================================================================

# Cloudflare API token for setting up outbound proxy
# Get it from: https://dash.cloudflare.com/profile/api-tokens
# CLOUDFLARE_WORKERS_TOKEN=xxx

# Extra domains to proxy, merged with built-in defaults (Telegram, Discord, WhatsApp,
# Facebook, Google). Comma-separated. Set to "*" to proxy ALL external traffic.
# Leave unset to proxy only the built-in default domains.
# CLOUDFLARE_PROXY_DOMAINS=api.sendgrid.com,slack.com

# ============================================================================
# Database Backup Configuration
# ============================================================================

# Sync interval in seconds (how often to backup to HF Dataset)
# Default: 86400 (24h). Override via Space secret to sync more frequently.
SYNC_INTERVAL=3600

# Maximum file size for individual backups (in bytes)
# Default: 52428800 (50MB)
SYNC_MAX_FILE_BYTES=52428800

# Name of the HF Dataset to store backups
# Will be created as: {HF_USERNAME}/{BACKUP_DATASET_NAME}
BACKUP_DATASET_NAME=huggingclip-backup

# ============================================================================
# Authentication & Security
# ============================================================================

# Better Auth secret for user authentication
# Generate a random secret: openssl rand -base64 32
BETTER_AUTH_SECRET=your-random-secret-here-minimum-32-characters

# Optional: Discord webhook for admin notifications
# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# ============================================================================
# Monitoring & Uptime
# ============================================================================

# Cloudflare proxy & keep-alive: add your Cloudflare API token.
# A Worker is created automatically at boot for both outbound proxying and keep-alive.
# CLOUDFLARE_WORKERS_TOKEN=your_cloudflare_token_here

# Optional: Webhook URL for restart/failure alerts
# WEBHOOK_URL=https://uptime-robot-webhook-url

# ============================================================================
# Telemetry & Privacy
# ============================================================================

# Disable Paperclip telemetry (1 = disabled)
PAPERCLIP_TELEMETRY_DISABLED=1

# Respect Do Not Track header
DO_NOT_TRACK=1

# ============================================================================
# Development-Only Variables (for local testing)
# ============================================================================

# Debug logging (set to anything to enable)
# DEBUG=1

# ============================================================================
# HuggingFace Spaces Specific
# ============================================================================

# These are automatically set by HF Spaces:
# SPACE_ID: your-space-id
# SPACE_PERSISTENT_DIRECTORY: /tmp (ephemeral, 50GB)
# SPACE_AUTHOR_NAME: your-hf-username
# SPACE_RUNTIME: docker