tidepool.yaml

How the server runs. Every key has a default, so the file can be empty or absent. See the project directory for an example.

key	type	default	description
agents	Agents		What agents may do over MCP.
auth	AuthSettings		Where the access tokens come from.
config_writeback	Writeback		What happens to the config directory when a change is applied through the API or the UI.
data_dir	string		Where the server keeps its state. --data overrides it.
durability	Durability	fsync
epoch_interval	Duration	200ms	How often new data becomes visible, at most.
listen	Listen		Where to listen: one address for everything, or one per surface (public, ingest, admin). tidepool serve --listen overrides it with one address.
memory_budget	MemorySize	75%	Memory for data and caches together.
public_url	string		The address people reach the server at, such as https://tidepool.example.com: where a view shown inside an AI app (an MCP App) loads the UI from and connects to. When left out, the address the MCP request came to.

Agents

What an agent's changes over MCP may do without a person (plan §8.5).

key	type	default	description
auto_apply	list of ChangeClassName	["safe"]	Change classes an agent's apply_change applies directly; anything else waits for approval.

AuthSettings

The access tokens (plan §9, §9.2), named by environment variable and read when the server starts. A read or admin level whose variable is unset or empty is open; the admin token is good for every level.

Ingest is either one token for every table and operation (ingest_token_env, open when unset, as before), or a list of named credentials (ingest), each scoped to tables and operations.

key	type	default	description
admin_token_env	string	TIDEPOOL_ADMIN_TOKEN	Changing the config, approving changes.
agent_token_env	string	TIDEPOOL_AGENT_TOKEN	For agents (MCP): reading, and changing the config under agents.auto_apply; it never approves a change, its own or another's.
ingest	list of IngestCredential		Named ingest credentials, in place of ingest_token_env.
ingest_token_env	string		One token for writing and deleting rows in every table, named ingest. Default TIDEPOOL_INGEST_TOKEN; not used with ingest.
read_token_env	string	TIDEPOOL_READ_TOKEN	Reading data, the model and dashboards.

Writeback

Write-back of applied changes (plan §8.1).

key	type	default	description
enabled	boolean	true	Write applied changes to the config files, so the directory always holds what the server runs.
git_commit	boolean	true	Commit them, when the config directory is in a git repository.

Durability

value	description
fsync	Acknowledge ingest after the write-ahead log is fsynced.
async	Acknowledge before the fsync: faster, and a crash can lose the last moments of acknowledged data.

Duration

A duration with a unit: ms, s, m, h or d (e.g. 200ms, 730d).

Type: string.

Listen

Where the server listens (plan §9.2).

One of:

• string: One address serving everything.
• Surfaces: An address per surface.

MemorySize

A share of system memory (75%) or a size (8GiB).

Type: string.

ChangeClassName

A plan's change class, as written in tidepool.yaml.

Type: safe · rebuild · destructive.

IngestCredential

A producer allowed to write rows (plan §9.2): which tables, which operations, and whether from the public listener.

key	type	default	description
limits	Limits		How much it may send.
name	string	required	Its name: in metrics, and the scope of its idempotency keys.
operations	list of IngestOperation		What it may do. Default: append for a public credential, every operation otherwise.
origins	list of string		The browser origins it may write from (CORS), e.g. https://app.example.com.
public	boolean		Whether it may write through the public listener. Its limits then apply with defaults for what they leave out.
tables	list of string	["*"]	The tables it may write; "*" is every table.
token	NoToken		none: no token at all, for a producer that can't keep a secret (a browser). Only for public credentials that only append.
token_env	TokenEnv		The environment variable holding its token, or several: any of them is accepted, for rotating a token without downtime. A credential whose variables are all unset can't be used.

Surfaces

An address per surface. A surface left out is served by admin's address, or by public's when admin is left out too; surfaces given the same address share one listener.

key	type	default	description
admin	string		Everything, including config changes, approvals and /metrics.
ingest	string		Reading data and all ingest: where Kayak and other producers connect.
public	string		The UI, reading data, live dashboards, and ingest for credentials marked public.

Limits

How much a credential may send. Over rate or new_values a request is refused with 429, over batch_rows or body with 413.

key	type	default	description
batch_rows	integer		Rows in one request at most.
body	ByteSize		A request body's size at most, e.g. 1MiB.
new_values	Rate		Values new to a dictionary-encoded column at most, e.g. 1000/min: dictionaries only grow, so this is what keeps unique junk from filling memory.
rate	Rate		Requests (batches) at most, e.g. 200/s.

IngestOperation

A way of writing rows.

value	description
append	POST to an append table.
upsert	POST to an upsert table: rows replace the stored ones by key.
delete	DELETE: rows removed by key.
replace	PUT: the table's whole contents (an empty body empties it).

NoToken

token: none.

Type: none.

TokenEnv

One environment variable, or several.

One of:

• string
• list of string

ByteSize

A size: a number and B, KiB, MiB, GiB or TiB (e.g. 1MiB).

Type: string.

Rate

A count per unit of time: s, min or h (e.g. 200/s).

Type: string.