Configuration reference

File location and format

desk.toml lives at the root of your workspace directory, alongside the entities/, orders/, and research/ directories. It is a standard TOML file — human-readable, comment-friendly, and safe to commit to version control (exclude any secrets by using environment-variable references instead of literal values).

Run qoc init to generate a starter file with sensible defaults. Use qoc status to validate the current file — it reports any missing required keys or type mismatches.

[workspace] section

[account] section

[guards] section

[data] section

[agent] section

[schedule] section

Complete desk.toml example

# desk.toml — Qoc workspace configuration
# Generated by qoc init, edited for production use.

[workspace]
name            = "main-desk"
port            = 7070
log_level       = "info"
log_dir         = "~/.qoc/logs"
history_enabled = true
history_max_snapshots = 90
timezone        = "America/Chicago"

[account]
currency       = "USD"
nav_method     = "live"
margin_enabled = false
day_trade_mode = "pattern_check"

[guards]
max_order_nav_pct    = 0.02      # 2% of NAV per order
max_position_nav_pct = 0.08      # 8% of NAV per symbol
day_loss_limit_pct   = 0.03      # halt at -3% day loss
allow_symbols        = []        # empty = no allowlist filter
deny_symbols         = ["GME", "AMC"]
market_hours_only    = true
require_approval     = true
max_open_proposals   = 3

[data]
quote_source             = "hub"
fundamentals_enabled     = true
news_enabled             = true
news_max_age_hours       = 24
technicals_enabled       = true
technicals_lookback_days = 60
entity_refresh_cron      = "0 7 * * 1-5"

[agent]
mcp_host              = "127.0.0.1"
mcp_port              = 7070
max_concurrent_tasks  = 1
task_timeout_minutes  = 20
research_depth        = "standard"
write_research_files  = true

[schedule]
enabled          = true
max_runs_per_day = 6
run_log_dir      = "schedules/.logs"
notify_on_complete = false
notify_on_error    = true

# Connector blocks are written by `qoc connect <venue>`
# and should not be edited by hand unless you know the connector schema.
# Example (do not copy verbatim — run `qoc connect` to generate):
#
# [connector.paper]
# venue_type = "equities"
# mode       = "paper"

Connector blocks

Connector configuration blocks ([connector.<name>]) are appended to desk.toml by qoc connect <venue>. Each connector block contains the venue type, credentials (referenced via env: variables), and venue-specific settings such as account IDs or sub-account routing.

Do not edit connector blocks by hand unless you understand the connector's TOML schema — an invalid block causes qoc up to refuse to start. If a connector block becomes corrupted, remove it and re-run qoc connect to regenerate it.

Validation and troubleshooting

• Run qoc status after every edit to validate the file — it prints the first error it finds and the offending key.
• TOML is whitespace-tolerant but key names are case-sensitive — Log_Level is not the same as log_level.
• Float values for guard percentages must be written as decimals (0.02), not percentages (2%).
• Cron expressions in entity_refresh_cron and schedule files use five-field standard cron syntax evaluated in the timezone set in [workspace].
• If qoc up exits immediately after a config change, check ~/.qoc/logs/service.log for a parse error with a line number.

Related topics