Environment Variables

Environment Variables

Environment variables are the highest-priority configuration layer in TitanX. They override managed config keys and local config. Useful for:

• Ops tuning (cadences, timeouts, cost caps)
• Dev overrides (local testing with short TTLs)
• Deployment-specific settings that shouldn't be in SQLite

---

How to set them

Set before launching TitanX:

# Foreground
TITANX_DREAM_HOUR=2 open -a TitanX

# Persistent in shell
echo 'export TITANX_DREAM_HOUR=2' >> ~/.zshrc

# For dev
TITANX_LEARNING_PUSH_HOURS=1 bun run start

# Via launch agent (macOS)
# Edit ~/Library/LaunchAgents/ai.titanx.app.plist

---

Complete catalog

All variables are optional; defaults apply when unset.

Dream Mode

Variable	Type	Default	Description
TITANX_DREAM_HOUR	0..23	3	Nightly dream pass hour (local time)
TITANX_DREAM_MAX_COST_CENTS	integer	500	Per-pass LLM cost cap in cents ($5)
TITANX_LEARNING_PUSH_HOURS	1..168	2	Slave learning-push cadence
TITANX_FLEET_LEARNING_DEVICE_QUOTA	integer	500	Trajectories/device/24h quota

Fleet transport

Variable	Type	Default	Description
TITANX_FLEET_JWT_KEY	base64	(derived from device identity)	Override JWT signing key (advanced)

Security

Variable	Type	Default	Description
TITANX_AUDIT_HMAC_KEY	base64	(derived)	Override audit HMAC chain key

MCP

Variable	Type	Default	Description
TITANX_MCP_RATE_LIMIT_MAX	integer	60	Max MCP tool calls per window
TITANX_MCP_RATE_LIMIT_WINDOW_MS	integer	60000	Rate limit window (ms)
TITANX_MCP_SOCKET_IDLE_MS	integer	1800000	MCP socket idle timeout (30 min)
TITANX_MCP_TCP_BUFFER_MAX	integer	1048576	Max TCP buffer size (1 MB)

Agent runtime

Variable	Type	Default	Description
TITANX_WAKE_TIMEOUT_MS	integer	60000	Agent wake loop timeout (1 min)
TITANX_RETRY_DELAY_MS	integer	3000	Base retry delay for failed turns
TITANX_MEMORY_SWEEP_MS	integer	300000	Agent memory prune cadence (5 min)
TITANX_RESPONSE_BUFFER_MAX	integer	10000	Max streaming response chunks buffered
TITANX_TOKEN_CLEANUP_MS	integer	60000	Auth token cleanup cadence

Debug / development

Variable	Type	Default	Description
ACP_PERF	'0' | '1'	0	Enable ACP performance diagnostics
DEBUG_TEAM	'0' | '1'	0	Verbose team orchestration logs
NODE_ENV	'development' | 'production'	(auto)	Influences many defaults

---

Common use cases

Tighten dream cadence for active fleet

# Dream pass every hour instead of threshold+nightly
TITANX_DREAM_HOUR=2
# Slaves push every hour instead of every 2h
TITANX_LEARNING_PUSH_HOURS=1
# Raise cost cap for larger fleets
TITANX_DREAM_MAX_COST_CENTS=2000

Higher trajectory quota for power users

# From 500/day default to 2000/day
TITANX_FLEET_LEARNING_DEVICE_QUOTA=2000

Aggressive MCP rate limit for sandbox testing

# Only 10 calls per 10-second window (very restrictive)
TITANX_MCP_RATE_LIMIT_MAX=10
TITANX_MCP_RATE_LIMIT_WINDOW_MS=10000

Dev mode with fast iteration

# All cadences tightened for manual testing
TITANX_LEARNING_PUSH_HOURS=1
TITANX_DREAM_HOUR=$(( $(date +%H) + 1 ))  # next hour
TITANX_WAKE_TIMEOUT_MS=10000
bun run start

---

Precedence

When TitanX reads a config value, it checks in this order:

1. Env var (if set and valid)
   ↓
2. Managed config from master (if this is a slave)
   ↓
3. Local config in SQLite (ProcessConfig)
   ↓
4. Hard-coded default

First hit wins. So TITANX_DREAM_HOUR=5 set in env always wins over a managed config that says 3.

Exception — security-critical managed keys

Master-mandated learning opt-in (fleet.learning.enabled) is treated slightly differently. Master can required: true which means slaves can't opt out — but env vars can still override (they're on the local device). This is intentional: the operator of a specific slave has ultimate control over their own device.

---

Validation

Invalid env var values are logged + ignored; default is used:

[ProcessConfig] TITANX_DREAM_HOUR=99 is invalid (expected 0-23); using default 3

Log entries with prefix ProcessConfig during startup flag any mis-set env vars.

---

Deployment patterns

Development

# Shell profile
export TITANX_DREAM_HOUR=$(( $(date +%H) + 1 ))
export TITANX_LEARNING_PUSH_HOURS=1

CI / test environments

Unset most env vars so defaults apply. Override only the ones that need tightening:

TITANX_WAKE_TIMEOUT_MS=5000
TITANX_LEARNING_PUSH_HOURS=168  # effectively disable pushes in CI

Production master

Set once via launch plist / systemd unit:

TITANX_DREAM_HOUR=2
TITANX_DREAM_MAX_COST_CENTS=1000
TITANX_FLEET_LEARNING_DEVICE_QUOTA=1000

Production slaves

Typically no env vars; master pushes managed config that governs all tuning.

---

Ops observability

You can verify which env vars TitanX saw at startup via:

Settings → Advanced → Runtime info shows the resolved config values + their source (env / managed / local / default).

Useful when "why is dream not running?" turns out to be "TITANX_DREAM_HOUR was set to 99 which fell back to default but the user expected 2".

---

Related pages

• Configuration Keys — the SQLite-backed layer
• Master Setup Guide — how managed config is published
• Troubleshooting — env-var-related issues
• Source: grep process.env.TITANX_ across src/ for every reader