Settings

Every setting, its environment variable, its athanore.toml key, its type and its default. Generated from the settings model, so a default here is the default that runs. Precedence is command-line flags first, then the environment, then athanore.toml in the root path, then these defaults.

Setting	Environment variable	athanore.toml	Type	Default	Description
root_path	ATHANORE_ROOT_PATH	root_path	Path	the working directory	The directory everything else is anchored to: the database, the .athanore/ state directory, athanore.toml, and a workflow's default project directories. Unset, it is the working directory the process was started in.
db_url	ATHANORE_DB_URL	db_url	str \| None	unset	The SQLAlchemy URL of the store. Unset, it resolves to sqlite+aiosqlite:///{root_path}/athanore.db; a Postgres install sets postgresql+asyncpg://... and needs the postgres extra.
host	ATHANORE_HOST	host	str	'127.0.0.1'	The interface to bind. A loopback bind needs no operator credential; binding anywhere else requires an operator token.
port	ATHANORE_PORT	port	int	4002	The port to bind.
public_url	ATHANORE_PUBLIC_URL	public_url	str \| None	unset	The base URL agents and plugins are told to reach this server at. Unset, it resolves to http://{host}:{port}; set it when agents run in a container or on another machine.
operator_token	ATHANORE_OPERATOR_TOKEN	refused	SecretStr \| None	unset	The operator credential, sent as a bearer token. Needed only for a non-loopback host or with require_token; athanore token rotate generates one into .athanore/token. Refused in athanore.toml.
require_token	ATHANORE_REQUIRE_TOKEN	require_token	bool	False	Force operator authentication even on a loopback bind — for a reverse proxy sitting in front of one.
body_limit	ATHANORE_BODY_LIMIT	body_limit	int	1048576	The largest request body accepted, in bytes. Beyond it the API answers 413.
sse_replay_cap	ATHANORE_SSE_REPLAY_CAP	sse_replay_cap	int	5000	The most events replayed to a client reconnecting with a cursor before it is told to resynchronise instead.
workers	ATHANORE_WORKERS	workers	int	1	The capacity of the default pool: how many attempts run at once when a workflow names no pool of its own.
max_retries	ATHANORE_MAX_RETRIES	max_retries	int	3	How many times a failed attempt is retried before the task is dead-lettered. A node overrides it per node.
agent_timeout	ATHANORE_AGENT_TIMEOUT	agent_timeout	float	10800	How long one agent run may take, in seconds, before the engine cancels it. A node overrides it per node.
permission_policy	ATHANORE_PERMISSION_POLICY	permission_policy	Literal['ask', 'auto_allow', 'auto_deny'] \| None	unset	A global override of every agent class's permission policy. Unset, each class keeps its own.
agent_command	ATHANORE_AGENT_COMMAND	refused	str \| list[str] \| None	unset	Replaces every ACPAgent.command at spawn — the hook that runs a workflow against a fake agent. Environment and CLI only; refused in athanore.toml.
cors_origins	ATHANORE_CORS_ORIGINS	cors_origins	list[str]	[]	Browser origins allowed to call the API cross-site. For development; empty is the default and the right value in production.
plugin_cdns	ATHANORE_PLUGIN_CDNS	plugin_cdns	list[str]	['https://cdn.jsdelivr.net', 'https://unpkg.com', 'https://esm.sh']	Origins a plugin's custom pane may load scripts, styles and fonts from, on top of 'self'. An empty list is the airtight policy; ["https:"] opens it to any origin over that scheme. connect-src is never widened, so a CDN script may run but may only talk back to this server.
log_format	ATHANORE_LOG_FORMAT	log_format	Literal['pretty', 'json'] \| None	unset	How the log is rendered. Unset, it resolves to pretty when stderr is a terminal and json when it is not.
stream_flush_interval	ATHANORE_STREAM_FLUSH_INTERVAL	stream_flush_interval	float	0.4	How long agent output is batched before it is flushed to the task stream, in seconds.
run_migrations	ATHANORE_RUN_MIGRATIONS	run_migrations	bool	True	Whether the server migrates the schema before it serves. False leaves that to athanore db upgrade.
forwarded_allow_ips	ATHANORE_FORWARDED_ALLOW_IPS	forwarded_allow_ips	str \| None	unset	Which proxies' X-Forwarded-* headers uvicorn trusts, as a comma-separated list of addresses or *. Unset, none are trusted.
retention	ATHANORE_RETENTION	retention	Retention	Retention(events_days=30, stream_days=14)	How long events and stream chunks are kept before the retention job prunes them.

[retention]

A nested table rather than a top-level key, so these have no environment variable of their own: set them in the [retention] table of athanore.toml, or together as JSON in ATHANORE_RETENTION.

Setting	Environment variable	athanore.toml	Type	Default	Description
events_days	none	events_days	int	30	How many days an event is kept before the retention job prunes it.
stream_days	none	stream_days	int	14	How many days a stream chunk is kept before the retention job prunes it.

athanore.toml

One file beside the database. Top-level keys are the settings in the first table above, spelled as their athanore.toml column; agent_command, operator_token are refused there and are set from the environment or the command line instead. An unknown top-level key is an error at startup rather than a silent default. [pools], [workflows] are read by athanore serve rather than by the settings model.

host = "127.0.0.1"
port = 4002
workers = 2

[retention]
events_days = 30
stream_days = 14

[pools]
build = 2

[workflows]
feature_build = { pool = "build" }
chat = { target = "workflows/chat.py:wf" }   # a registration