Daemon Configuration

Configure the Trix daemon with caching, sync intervals, file watching, and more.

Updated Oct 6, 2026

Configuration Overview

The daemon is configured via ~/.trix/daemon.yaml. Configuration can also be set via environment variables, which take precedence over the config file.

After modifying the configuration, restart the daemon for changes to take effect: trixd restart

API Configuration

Configure how the daemon connects to the Trix API:

api:
  # Trix API base URL (required) — default is http://localhost:3737 (self-hosted).
  # Point at the hosted API when using the SaaS:
  url: https://api.trixdb.com

  # Authentication - use ONE of these:
  key: gdb_abc123...        # API key (recommended)
  token: eyJhbGc...          # JWT token (alternative)

  # Request timeout in seconds (default: 30)
  timeout: 30

  # Skip TLS verification (not recommended for production)
  insecure_skip_tls: false

Never commit API keys to version control. Use environment variables for sensitive values in shared environments.

Cache Configuration

Configure the local cache for offline access and faster queries:

cache:
  # Enable local caching (default: true)
  enabled: true

  # Cache storage directory (default: ~/.trix/cache)
  dir: ~/.trix/cache

  # Maximum cache size in MB (default: 500)
  max_size_mb: 500

  # Time-to-live for cache entries in hours (default: 24)
  ttl_hours: 24

Cache Behavior

TTL (Time-to-Live) - Entries expire after ttl_hours and are refreshed on next sync
LRU Eviction - When cache exceeds max_size_mb, least recently used entries are removed
Persistence - Cache survives daemon restarts; stored as JSON files
Safe to Delete - The cache directory can be safely deleted; it will be repopulated on next sync

Sync Configuration

Configure how often and how the daemon syncs with the Trix API:

sync:
  # Enable periodic sync (default: true)
  enabled: true

  # Sync interval in seconds (default: 30)
  interval_secs: 30

  # Number of memories to fetch per sync cycle (default: 100)
  batch_size: 100

  # Number of retry attempts on failure (default: 3)
  retry_attempts: 3

Tuning Sync Performance

Frequent updates - Lower interval_secs (e.g., 10) for near real-time sync
Battery saving - Increase interval_secs (e.g., 300) for laptops
Large datasets - Increase batch_size for faster initial sync

File Watcher Configuration

Configure automatic memory ingestion from watched directories:

watcher:
  # Enable file watching (default: false for security)
  enabled: false

  # Directories to watch for changes
  directories:
    - ~/Documents/notes
    - ~/Projects/docs

  # File patterns to match (glob syntax)
  patterns:
    - "*.md"
    - "*.txt"
    - "*.pdf"

  # Skip files older than this (hours)
  ignore_hours: 24

  # Debounce delay for rapid changes (milliseconds)
  debounce_ms: 500

  # Ignore patterns - exclude files/directories (gitignore-style)
  ignore_patterns:
    - "**/node_modules/**"
    - "**/vendor/**"
    - "**/.git/**"
    - "*.tmp"
    - "**/build/**"

  # Enable .trixignore file discovery (default: false)
  check_ignore_files: true

  # Custom ignore file name (default: .trixignore)
  ignore_file_name: ".trixignore"

Ignore Patterns

Use ignore_patterns to exclude files and directories from ingestion. Patterns follow gitignore syntax:

Pattern	Effect
`*.tmp`	Ignore all `.tmp` files
`/node_modules/`	Ignore `node_modules` at any depth
`build/`	Ignore directories named `build`
`!important.md`	Re-include `important.md` (negation)
`# comment`	Comment line (ignored)

.trixignore Files

When check_ignore_files is enabled, the daemon looks for .trixignore files in watched directories. These work like .gitignore but for Trix file watching.

# Example .trixignore file
# Build artifacts
build/
dist/
*.o

# IDE and editor files
.idea/
.vscode/
*.swp

# But include important config
!.vscode/settings.json

# Temporary and cache files
*.tmp
*.bak
*~
__pycache__/

See .trixignore Guide for detailed documentation.

File watching is disabled by default for security. Only enable it for directories you explicitly trust. See File Watching for details.

IPC Configuration

Configure the Unix socket for local inter-process communication:

ipc:
  # Enable IPC socket for local communication (default: true)
  enabled: true

  # Socket path (default: ~/.trix/daemon.sock)
  socket_path: ~/.trix/daemon.sock

The IPC socket allows the Trix CLI and other local tools to communicate with the daemon. See IPC Integration for protocol details.

HTTP Server Configuration

Configure the health check and metrics server:

http:
  # Enable health check and metrics server (default: true)
  enabled: true

  # Server address (default: 127.0.0.1:9090)
  addr: 127.0.0.1:9090

  # Enable Go pprof profiling (default: false)
  enable_pprof: false

Available Endpoints

GET /health - Returns 200 if daemon is healthy
GET /status - Detailed JSON status
GET /metrics - Prometheus metrics

Logging Configuration

Configure daemon logging:

log:
  # Log level: debug, info, warn, error (default: info)
  level: info

  # Log file path (default: ~/.trix/logs/daemon.log)
  file: ~/.trix/logs/daemon.log

  # Use JSON formatted logs (default: true)
  json: true

Log Levels

error - Only errors
warn - Warnings and errors
info - Normal operation (default)
debug - Detailed debugging information

Full Example

A complete configuration file with all options:

# ~/.trix/daemon.yaml - Complete example
api:
  url: https://api.trixdb.com
  key: gdb_abc123...
  timeout: 30

cache:
  enabled: true
  dir: ~/.trix/cache
  max_size_mb: 500
  ttl_hours: 24

sync:
  enabled: true
  interval_secs: 30
  batch_size: 100
  retry_attempts: 3

watcher:
  enabled: true
  directories:
    - ~/Documents/notes
    - ~/Projects/work/docs
  patterns:
    - "*.md"
    - "*.txt"
  ignore_hours: 24
  debounce_ms: 500
  # Exclude common unwanted directories
  ignore_patterns:
    - "**/node_modules/**"
    - "**/vendor/**"
    - "**/.git/**"
    - "*.tmp"
  check_ignore_files: true
  ignore_file_name: ".trixignore"

ipc:
  enabled: true
  socket_path: ~/.trix/daemon.sock

http:
  enabled: true
  addr: 127.0.0.1:9090

log:
  level: info
  file: ~/.trix/logs/daemon.log
  json: true

Environment Variables

All configuration can be set via environment variables. Environment variables take precedence over the config file.

Variable	Config Equivalent	Description
`TRIX_API_URL`	`api.url`	API base URL
`TRIX_API_KEY`	`api.key`	API key for authentication
`TRIX_TOKEN`	`api.token`	JWT token (alternative to API key)
`TRIXD_LOG_LEVEL`	`log.level`	Logging level
`TRIXD_CACHE_ENABLED`	`cache.enabled`	Enable/disable cache (true/false)
`TRIXD_CACHE_DIR`	`cache.dir`	Cache directory path
`TRIXD_SYNC_ENABLED`	`sync.enabled`	Enable/disable sync (true/false)
`TRIXD_SYNC_INTERVAL`	`sync.interval_secs`	Sync interval in seconds
`TRIXD_HTTP_ADDR`	`http.addr`	HTTP server address
`TRIXD_CONFIG`	-	Path to config file

Example Usage

# Run with environment variables
TRIX_API_KEY=your-key TRIXD_LOG_LEVEL=debug trixd run

# In a .env file or shell profile
export TRIX_API_KEY="gdb_abc123..."
export TRIXD_SYNC_INTERVAL=60
export TRIXD_CACHE_DIR="/var/cache/trix"

# Docker example
docker run -e TRIX_API_KEY=your-key trix/daemon

Configuration Precedence

Configuration values are resolved in this order (highest to lowest priority):

Command-line flags (e.g., --config, -v)
Environment variables (TRIX_*, TRIXD_*)
Configuration file (~/.trix/daemon.yaml)
Built-in defaults

Use trixd doctor to see the effective configuration after all sources are merged.