Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt

Use this file to discover all available pages before exploring further.

Clockchain uses environment variables for configuration. Create a .env file in the project root or set variables in your deployment environment.

​
Required Variables

These variables must be set for Clockchain to function:
​
DATABASE_URL
string
required
PostgreSQL connection URL
DATABASE_URL=postgresql://localhost:5432/clockchain
​
SERVICE_API_KEY
string
required
Shared secret for inbound service authentication. All API endpoints (except /health and /) require the X-Service-Key header with this value.
SERVICE_API_KEY=your-secret-key-here
​
FLASH_SERVICE_KEY
string
required
Authentication key for making requests to the Flash service API.
FLASH_SERVICE_KEY=flash-api-key

​
Flash Integration

​
FLASH_URL
string
URL of the Flash service for scene generation.
# Railway internal (default)
FLASH_URL=http://timepoint-flash-deploy.railway.internal:8080

# Local development
FLASH_URL=http://localhost:8080

​
AI Workers

Configuration for autonomous graph expansion and content moderation:
​
OPENROUTER_API_KEY
string
OpenRouter API key for LLM-powered workers (Expander and Judge).
OPENROUTER_API_KEY=sk-or-v1-...
​
OPENROUTER_MODEL
string
default:"google/gemini-2.0-flash-001"
Model to use for AI workers via OpenRouter.
OPENROUTER_MODEL=google/gemini-2.0-flash-001
​
EXPANSION_ENABLED
boolean
default:"false"
Enable the autonomous graph expansion worker. Requires OPENROUTER_API_KEY.
EXPANSION_ENABLED=true
When enabled, the Expander worker:
  • Picks frontier nodes with low degree (< 3 edges)
  • Generates 3-5 related events via LLM
  • Creates causal edges and auto-links
  • Runs every 300 seconds
​
DAILY_CRON_ENABLED
boolean
default:"false"
Enable the “Today in History” daily worker.
DAILY_CRON_ENABLED=true
When enabled:
  • Runs every 24 hours
  • Finds events matching today’s month/day
  • Queues up to 5 events for Flash scene generation

​
Server Configuration

​
PORT
integer
default:"8080"
HTTP server port.
PORT=8080
​
ENVIRONMENT
string
default:"development"
Environment name for logging and behavior.
ENVIRONMENT=production
​
DEBUG
boolean
default:"false"
Enable debug logging.
DEBUG=true

​
Data and Storage

​
DATA_DIR
string
default:"./data"
Directory for seed data files.
DATA_DIR=./data

​
Admin Access

​
ADMIN_KEY
string
Secret key for accessing admin endpoints like bulk generation.
ADMIN_KEY=admin-secret-key

​
Example Configuration

# .env file for local development
DATABASE_URL=postgresql://localhost:5432/clockchain
SERVICE_API_KEY=dev-service-key
FLASH_URL=http://localhost:8080
FLASH_SERVICE_KEY=dev-flash-key
DEBUG=true
ENVIRONMENT=development

​
Configuration Loading

Clockchain uses Pydantic Settings to load configuration:
  1. Reads from .env file in the project root
  2. Overrides with environment variables
  3. Falls back to default values
The configuration is defined in app/core/config.py:6: 
class Settings(BaseSettings):
    SERVICE_API_KEY: str = ""
    FLASH_URL: str = "http://timepoint-flash-deploy.railway.internal:8080"
    FLASH_SERVICE_KEY: str = ""
    # ... other settings
    
    model_config = {"env_file": ".env", "extra": "ignore"}

​
Next Steps

Deployment

Deploy Clockchain to Railway, Docker, or local server

Build docs developers (and LLMs) love

Get started for freeTalk to us