trading_agent.configuration.agent_configuration

The shape of trading_agent.toml, checked when it is read.

Each class describes one table of the file. Pydantic checks every value against its type and range, so a typing mistake in the file is reported by name when the program starts.

Typical usage example:

configuration = AgentConfiguration.model_validate(parsed_toml) port = configuration.gateway.port

TELEGRAM_NOTIFICATIONS module-attribute

TELEGRAM_NOTIFICATIONS = ('fills', 'rejections', 'model_switches', 'job_results', 'desk_reports', 'messages', 'alerts', 'halts', 'errors', 'daily_summaries')

PUSH_NOTIFICATIONS module-attribute

PUSH_NOTIFICATIONS = ('fills', 'rejections', 'model_switches', 'job_results', 'desk_reports', 'messages', 'alerts', 'halts', 'errors', 'requests')

GatewayConfiguration

Bases: BaseModel

Where the gateway's web server listens.

Attributes:

Name	Type	Description
host	str	The address to listen on. 127.0.0.1 keeps the gateway reachable from this machine only.
port	int	The TCP port to listen on.
frontend_directory	Path	The built web page, served at every address that is not part of the API.
allowed_origins	list[str]	The other web origins whose pages may call the API, such as "https://localhost" for the Android app; empty allows none.

DeskConfiguration

Bases: BaseModel

One trading desk, which is one independent agent.

Attributes:

Name	Type	Description
name	str	The desk's name, used in folder names, order tags and the web interface.
enabled	bool	Whether the desk starts with the gateway.
backend_order	list[str]	The backends the desk may use, most preferred first, by their names in [backends].
heartbeat_minutes	int | None	Minutes between heartbeats while NSE equities trade, or None for no heartbeat; each heartbeat is a model turn.
rollover_time	str	The India time on trading days, as HH:MM, when the desk's session rolls over with a summary.
scheduled_checks	list[Annotated[str, StringConstraints(pattern='^([01][0-9]|2[0-3]):[0-5][0-9]$')]]	India times on trading days, as HH:MM, when the desk is woken to do what its Persona.md says for that time of day.

AgentLoopConfiguration

Bases: BaseModel

Limits that keep one turn of the agent loop under control.

Attributes:

Name	Type	Description
maximum_rounds	int	The most model calls one turn may make before it is stopped.
maximum_identical_tool_calls	int	How many times one tool may be called with the same arguments in a turn.
tool_timeout_seconds	float	How long one tool call may run before it is stopped.
compression_threshold	float	The share of a model's context window at which, before the next turn, the desk saves what matters and its conversation is compressed into a summary.
emergency_compression_threshold	float	The higher share at which a conversation is compressed in the middle of a long turn, without the memory flush.

SandboxConfiguration

Bases: BaseModel

How the bash terminal's sandbox is built.

Attributes:

Name	Type	Description
command_timeout_seconds	float	How long one bash command may run before the session is restarted.
maximum_output_characters	int	How much of a command's output is returned to the model.
hidden_paths	list[str]	Files and folders replaced by empty ones inside the sandbox, so their contents cannot be read. "~" and "*" are expanded.
passed_environment	list[str]	Names of environment variables passed from the gateway into the sandbox, which otherwise starts with an empty environment. A skill that needs a variable is shown only when it is passed here.

WebConfiguration

Bases: BaseModel

Where web search goes and how pages are fetched.

Attributes:

Name	Type	Description
searxng_base_url	str	The local SearXNG server started by docker-compose.yml.
search_result_limit	int	The most results one search returns.
fetch_timeout_seconds	float	How long fetching one page may take.
maximum_page_characters	int	How much of a page's text is returned to the model.

MarginRatesConfiguration

Bases: BaseModel

The rates used to estimate the margin an order blocks.

The defaults are the deliberately high segment-wide rates UBI's broker selector uses.

Attributes:

Name	Type	Description
intraday_rate	float	The share of an intraday (mis) cash order's value blocked as margin.
index_derivative_rate	float	The share of an index future's value, or of a sold index option's, blocked as margin.
stock_derivative_rate	float	The same for stock futures and options.
commodity_derivative_rate	float	The same for commodity futures and options.
currency_derivative_rate	float	The same for currency futures and options.

RiskConfiguration

Bases: BaseModel

How the risk engine works, apart from the limits in TradingRules.md.

Attributes:

Name	Type	Description
ownership_grace_minutes	float	How long a desk keeps its claim on an instrument it ordered but does not yet hold, before the claim lapses.
margin_rates	MarginRatesConfiguration	The rates used to estimate an order's margin.

SkillsConfiguration

Bases: BaseModel

How the desks' skills are kept.

Attributes:

Name	Type	Description
archive_after_days	int	How many days a desk's own skill may go unused before the daily curator archives it.

BrowserConfiguration

Bases: BaseModel

How each desk's Chrome browser runs.

Attributes:

Name	Type	Description
headless	bool	Whether Chrome runs without a window. Turn it off to watch a desk browse.
navigation_timeout_seconds	float	How long opening or changing a page may take.
maximum_elements	int	The most clickable elements one snapshot lists.
maximum_text_characters	int	How much of a page's visible text one snapshot returns.

BackendConfiguration

Bases: BaseModel

One model backend that a desk can use.

Attributes:

Name	Type	Description
kind	Literal['ollama', 'openai_compatible', 'deepseek', 'claude_code']	How the model is reached: "ollama", "openai_compatible", "deepseek" or "claude_code".
base_url	str | None	The server address, needed by the ollama, openai_compatible and deepseek kinds.
model	str	The model name the server knows the model by.
context_window	int	How many tokens of context the model is given.
thinking	bool	Whether the model reasons before answering, for models that support it.
effort	Literal['low', 'medium', 'high', 'xhigh', 'max'] | None	How hard Claude thinks ("low", "medium", "high", "xhigh" or "max") for the claude_code kind, or None for Claude Code's default.
api_key_variable	str | None	The environment variable, or .env entry, holding this backend's API key, such as "DEEPSEEK_API_KEY"; None uses TRADING_AGENT_OPENAI_API_KEY.
vision	bool	Whether the model can read pictures; when False, pictures are left out of what it is sent and it is told so.
other_models	list[str]	Other models of the same provider that the chat page's model menu offers for this backend, such as "claude-haiku-5-5".
rupees_per_million_prompt_tokens	float | None	The price of a million prompt tokens, for /usage to show costs, or None.
rupees_per_million_completion_tokens	float | None	The price of a million completion tokens, or None.
usd_per_million_cache_hit_tokens	float | None	For the deepseek kind, the peak-hour price of a million prompt tokens read from the cache, or None.
usd_per_million_cache_miss_tokens	float | None	For the deepseek kind, the peak-hour price of a million other prompt tokens, or None.
usd_per_million_completion_tokens	float | None	For the deepseek kind, the peak-hour price of a million completion tokens, or None.
peak_hours_utc	list[str]	The peak-price periods on weekdays, such as "01:00-04:00", in UTC; outside them the off-peak factor applies.
off_peak_price_factor	float	What off-peak prices are as a share of peak prices, such as 0.5.

ApprovalConfiguration

Bases: BaseModel

Which of the desks' actions wait for the user's permission.

Attributes:

Name	Type	Description
tools	list[str]	The tools whose every call by a desk or subagent waits for the user's permission, such as "flatten_desk"; empty for none.
expiry_minutes	int	How long a permission request stays open before it lapses and the action is not run.

TelegramConfiguration

Bases: BaseModel

The Telegram channel.

Attributes:

Name	Type	Description
enabled	bool	Whether the gateway talks to Telegram; it also needs TRADING_AGENT_TELEGRAM_BOT_TOKEN in .env.
default_desk	str | None	The desk a paired chat talks to until it chooses another with /desk; when left out, the first desk in the configuration.
notifications	list[str]	What is pushed to every paired chat without being asked: fills, rejections, model_switches, job_results, desk_reports, messages, alerts, halts, errors and daily_summaries.
poll_seconds	int	How long one long-poll request to Telegram waits for new messages before asking again.

PushConfiguration

Bases: BaseModel

Push notifications to the Android app through Firebase Cloud Messaging.

Attributes:

Name	Type	Description
enabled	bool	Whether the gateway sends notifications; it also needs TRADING_AGENT_FIREBASE_SERVICE_ACCOUNT_FILE in .env.
notifications	list[str]	What is pushed to every registered phone: fills, rejections, model_switches, job_results, desk_reports, messages, alerts, halts, errors and requests (permissions, questions and plans waiting for the user).

AgentConfiguration

Bases: BaseModel

Everything in trading_agent.toml.

Attributes:

Name	Type	Description
mode	Literal['dry_run', 'live']	"dry_run" sends every order to UBI as a dry run, and "live" sends real orders.
workspace_directory	Path	The folder holding the desks' files, memory and journals.
tradingmachine_environment_file	Path	The .env file that tradingmachine reads its UBI and MongoDB settings from.
mcp_servers_file	Path	The JSON file listing the MCP servers every desk can use.
market_calendar_directory	Path | None	UBI's folder of yearly exchange calendars, or None to know weekends only.
gateway	GatewayConfiguration	Where the web server listens.
desks	list[DeskConfiguration]	The desks to run.
backends	dict[str, BackendConfiguration]	The model backends, keyed by the name desks refer to them by.
agent	AgentLoopConfiguration	The limits of the agent loop.
sandbox	SandboxConfiguration	How the bash terminal's sandbox is built.
web	WebConfiguration	Where web search goes and how pages are fetched.
browser	BrowserConfiguration	How each desk's Chrome browser runs.
risk	RiskConfiguration	How the risk engine works, apart from the limits in TradingRules.md.
skills	SkillsConfiguration	How the desks' skills are kept.
telegram	TelegramConfiguration	The Telegram channel.
push	PushConfiguration	Push notifications to the Android app.
approvals	ApprovalConfiguration	Which actions wait for the user's permission.