Configuration and Monitoring

1. Common Configuration

These settings are commonly used for installation and maintenance. Change them as needed and keep package defaults for settings not listed.

Scenario	Setting and default
Separate dangerous-operation approvals	TIMECHO_APPROVAL_DANGER_APPROVER_ROLES=DB_ADMIN; default DB_ADMIN,ADMIN
Approval wait time	TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS=600
Query timeout	TIMECHO_CLI_TIMEOUT_SECONDS=30
Gateway without streaming support	TIMECHO_LLM_STREAM=false; default true
Longer timeout for slow models	TIMECHO_LLM_REQUEST_TIMEOUT_SECONDS=120
Block private-network model addresses	TIMECHO_SECURITY_BLOCK_PRIVATE_MODEL_ENDPOINTS=false; consider true if the model gateway is not on the internal network
Default daily budget	TIMECHO_BUDGET_DAILY_TOKENS_PER_USER=0 (unlimited); individual user settings take precedence
Budget day boundary	TIMECHO_BUDGET_ZONE=Asia/Shanghai
Audit retention	TIMECHO_AUDIT_RETENTION_DAYS=180; 0 means permanent; nonzero retention cannot be less than 180 days
Backend memory	BACKEND_MEM_LIMIT=2g
Metrics scraping	TIMECHO_SECURITY_METRICS_TOKEN; if set, at least 32 bytes
Four-eyes approval	TIMECHO_APPROVAL_FOUR_EYES=off/write/all
Approve every write separately	TIMECHO_APPROVAL_SESSION_AUTO_WRITE=false
Trash retention	TIMECHO_SESSIONS_TRASH_RETENTION_DAYS=30
Automatic summary threshold	TIMECHO_AGENT_SUMMARY_TRIGGER_RATIO=0.8
Forecasting service	TIMECHO_AI_BASE_URL=https://ai.timecho.com, TIMECHO_AI_MAX_ROWS=2000
Query exports	TIMECHO_EXPORT_MAX_ROWS=100000, TIMECHO_EXPORT_MAX_BYTES=52428800 (50 MB, specified in bytes)
Conversation document size	TIMECHO_DOCUMENTS_MAX_BYTES=20971520 (20 MB)
Documents per conversation	TIMECHO_DOCUMENTS_MAX_PER_SESSION=20
Scan recognition	TIMECHO_DOCUMENTS_OCR_ENABLED=true, TIMECHO_DOCUMENTS_OCR_MAX_PAGES=20
External tools master switch	TIMECHO_MCP_ENABLED=true
Allowed external tool hosts	TIMECHO_MCP_ALLOWED_HOSTS; comma-separated; empty by default, meaning unrestricted
Block private external tool addresses	TIMECHO_MCP_BLOCK_PRIVATE=false; true rejects private-network and loopback services
API documentation	TIMECHO_API_DOCS_ENABLED=false; only platform administrators can access it when enabled
Sign-in cookie security	TIMECHO_SECURITY_COOKIE_SECURE=auto; do not set true for plain HTTP

To add backend environment variables, create docker-compose.override.yml in deploy/, for example:

services:
  backend:
    environment:
      TIMECHO_APPROVAL_DANGER_APPROVER_ROLES: DB_ADMIN
      TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS: "900"

Load configuration: Set COMPOSE_FILE in .env to docker-compose.prod.yml:docker-compose.override.yml, then run docker compose config -q and docker compose up -d.

Note: Adding a line to .env alone does not guarantee that the variable reaches the backend. A plain restart also does not load new environment variables.

2. Enable Metrics Monitoring

Configure Prometheus as follows. The metrics endpoint and local port mapping have internal test records; the scraping configuration below has not itself been tested and must be verified in the target environment.

1. Set TIMECHO_SECURITY_METRICS_TOKEN in the controlled .env to a random value of at least 32 bytes. You can generate one with openssl rand -hex 24. Store it securely and do not use it as a user password.

2. Merge this port mapping into docker-compose.override.yml. If backend already exists, merge its fields rather than defining services/backend twice:

   services:
     backend:
       ports:
         - "127.0.0.1:8090:8090"

3. Set COMPOSE_FILE as described in Common Configuration, run docker compose config -q, then docker compose up -d.

4. Merge this scrape job into the configuration of Prometheus running on the same host, replace the token, and reload it according to your Prometheus management procedure:

   scrape_configs:
     - job_name: timecho-agent
       metrics_path: /actuator/prometheus
       authorization:
         credentials: <METRICS_SCRAPING_TOKEN>
       static_configs:
         - targets: ["127.0.0.1:8090"]

Restrict read permissions on the token configuration file. If Prometheus runs on another host or in a container, 127.0.0.1 refers to that host or container itself. Prometheus can join the application's internal network and use backend:8090; do not expose the backend port publicly.

Success: The Prometheus target is up and returns JVM, CPU, HTTP, or connection-pool metrics. For a 404, check whether the token is configured and whether the request went through the frontend. For a 401, check that the correct metrics token is used.

Verify database execution readiness from the same host:

curl -fsS http://127.0.0.1:8090/actuator/health/readiness

After the health check succeeds, also verify a real query through the model.