Workspace structure
A reference for every directory and file in a Qoc workspace, with notes on format, ownership, and when each is read or written.
Every workspace follows the same directory layout — a small set of folders, each with a clear purpose, so any agent or developer can navigate the desk without prior knowledge of its contents.
Directory tree
my-desk/
├── desk.toml # Desk config: venues, risk guards, UTA settings
├── entities/ # One file per tracked ticker or company
│ └── AAPL.md
├── inbox/ # Fills, alerts, webhook events — agent triages these
│ └── 2026-07-05-fill-AAPL-BUY.md
├── issues/ # Tasks and questions the desk is working
│ └── 001-rebalance-tech-sleeve.md
├── orders/ # Proposed and executed orders (the "commits")
│ ├── proposed/
│ └── executed/
├── research/ # Free-form notes, theses, data exports
│ └── macro-notes.md
├── schedules/ # Scheduled agent runs
│ └── daily-open.toml
└── snapshots/ # Point-in-time equity and position records
└── 2026-07-05.jsonFolder and file reference
| Path | Format | Owner | Purpose |
|---|---|---|---|
desk.toml | TOML | Human / qoc init | Primary config: venue connections, UTA settings, pre-trade risk guards, agent preferences. |
entities/ | Markdown + YAML frontmatter | Agent + human | One file per tracked ticker or company. Frontmatter holds structured fields; body holds the research thesis. |
inbox/ | Markdown + YAML frontmatter | Qoc runtime | Incoming events: broker fills, price alerts, webhook payloads, system messages. Agent triages and archives. |
issues/ | Markdown + YAML frontmatter | Human + agent | Tasks and research questions. Agent updates the status field as it works. You can open issues manually or via qoc run. |
orders/proposed/ | Markdown + YAML frontmatter | Agent | Orders the agent has drafted but not yet submitted. Requires your approval before execution. |
orders/executed/ | Markdown + YAML frontmatter | Qoc runtime | Immutable record of every order that was sent to a venue, including venue response and fill details. |
research/ | Markdown, JSON, CSV | Human + agent | Free-form notes, downloaded datasets, exported charts, theses that are not yet tied to a specific entity. |
schedules/ | TOML | Human / qoc schedule | Cron-style schedule definitions. Each file describes one recurring agent run: when, which issue or task, which agent. |
snapshots/ | JSON | Qoc runtime | Daily or on-demand position and equity snapshots. Used by the agent to reason about current exposure. |
desk.toml
desk.toml is the only file you must edit by hand when setting up a new desk. It declares which venues are connected, global risk limits (max position size, daily loss limit, etc.), and UTA (Unified Trading Account) settings.
Risk guards defined here run as pre-trade checks before any order leaves the desk. An order that would breach a guard is rejected and written to inbox/ as a blocked-order alert.
Minimal desk.toml
[desk]
name = "my-desk"
version = "0.73.0"
[uta]
base_currency = "USD"
[risk]
max_order_notional_usd = 10000
daily_loss_limit_usd = 500
max_position_pct = 0.10 # 10 % of portfolio per name
[[venues]]
id = "alpaca-live"
type = "alpaca"
env = "live"Do not commit credentials
Venue API keys belong in environment variables or a secrets manager, not in desk.toml. The env field in a venue block tells Qoc which environment variable prefix to look for. Run qoc connect <venue> to configure credentials safely.
Version history
Qoc maintains a built-in git-like log of every file change in the workspace. You do not need to initialise a separate git repository, though you can layer one on top if you want to push to a remote.