Configuration, Fuze Docs

Configure Fuze via fuze.toml in your project root, programmatically with configure(), or skip both, every setting has a sensible default.

Full reference

toml

[defaults]
max_retries = 3           # Max retries per guarded function
timeout = "30s"           # Per-call timeout
max_cost_per_step = 1.00  # USD ceiling per individual call
max_cost_per_run = 10.00  # USD ceiling for the entire run
max_iterations = 25       # Hard iteration cap
on_loop = "kill"          # "kill", "warn", or "skip"
trace_output = "./fuze-traces.jsonl"  # Path for local trace output

[loop_detection]
window_size = 5           # Number of recent outputs to compare
repeat_threshold = 3      # Consecutive identical outputs before triggering
max_flat_steps = 4        # Max steps with no cost change before flagging
cost_velocity_window = 60 # Window in seconds for cost velocity check
cost_velocity_threshold = 1.0  # USD/min threshold that triggers an alert

[cloud]
api_key = ""              # API key from app.fuze-ai.tech (or FUZE_API_KEY env var)
endpoint = ""             # Override default endpoint (self-hosted only)

[project]
project_id = "default"    # Project identifier (or FUZE_PROJECT_ID env var)

[daemon]
enabled = false           # Enable local daemon for self-hosted deployments
socket_path = "/tmp/fuze-daemon.sock"   # Unix socket path
# socket_path = "\\\\.\\pipe\\fuze-daemon"  # Windows named pipe
api_port = 7821           # HTTP API port for the daemon

[daemon.budget]
org_daily_budget = 100.00       # Org-wide daily spend ceiling (USD)
per_agent_daily_budget = 20.00  # Per-agent daily spend ceiling (USD)
alert_threshold = 0.80          # Alert at this fraction of ceiling

[daemon.alerts]
dedup_window_ms = 60000   # Suppress duplicate alerts within this window (ms)
webhook_urls = []         # List of webhook URLs for alert delivery

[providers]
# Override default pricing for enterprise discounts
# "openai/gpt-4o" = { input = 0.0020, output = 0.008 }

[compliance]
enabled = false
risk_level = "minimal"    # "minimal", "limited", or "high"
log_pii = false           # Anonymize personal data in traces

Programmatic configuration

Use configure() as an alternative to fuze.toml. Call it before any guard() or createRun() calls:

import { configure } from 'fuze-ai'

configure({
  cloud:    { apiKey: process.env.FUZE_API_KEY },
  project:  { projectId: 'my-agent' },
  defaults: { maxCostPerRun: 5.00, maxIterations: 50 },
})

Values set via configure() override fuze.toml. Per-function guard options override both.

Configuration priority

Settings are merged in this order (last wins):

Built-in defaults, sensible values for all options
fuze.toml, project-level configuration
configure(), programmatic override
Dashboard tool config, per-tool overrides fetched from the Fuze cloud (see Tools)
Per-function options, guard(fn, { maxCost: 0.50 }) has highest precedence

Sections

`[defaults]`

Key	Type	Default	Description
`max_retries`	number	`3`	Maximum retry attempts
`timeout`	string	`"30s"`	Per-call timeout
`max_cost_per_step`	number	`1.00`	USD ceiling per call
`max_cost_per_run`	number	`10.00`	USD ceiling per run
`max_iterations`	number	`25`	Hard iteration cap
`on_loop`	string	`"kill"`	Behavior on loop detection: `"kill"`, `"warn"`, or `"skip"`
`trace_output`	string	`"./fuze-traces.jsonl"`	File path for local trace output

`[loop_detection]`

Controls how Fuze detects repetitive agent behavior.

Key	Type	Default	Description
`window_size`	number	`5`	Number of recent outputs to compare
`repeat_threshold`	number	`3`	Consecutive identical outputs before triggering
`max_flat_steps`	number	`4`	Max steps with no cost change before flagging
`cost_velocity_window`	number	`60`	Window in seconds for cost velocity check
`cost_velocity_threshold`	number	`1.0`	USD/min threshold that triggers an alert

`[cloud]`

Connects the SDK to Fuze Cloud for remote configuration and telemetry. Leave unset for free in-process-only mode.

Key	Type	Default	Description
`api_key`	string	`""`	API key from app.fuze-ai.tech. Can also be set via `FUZE_API_KEY` env var
`endpoint`	string	`"https://api.fuze-ai.tech"`	Cloud API endpoint. Override only for self-hosted deployments

`[project]`

Key	Type	Default	Description
`project_id`	string	`"default"`	Project identifier shown in the dashboard. Can also be set via `FUZE_PROJECT_ID` env var

`[daemon]`

Self-hosted only. Connects the SDK to a locally-running Fuze daemon for cross-process budget enforcement and audit logging without sending data to the cloud.

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable daemon connection
`socket_path`	string	platform default	UDS socket path (Unix) or named pipe (Windows)
`api_port`	number	`7821`	HTTP API port for the daemon

`[daemon.budget]`

Key	Type	Default	Description
`org_daily_budget`	number	`100.00`	Organization-wide daily spend ceiling (USD)
`per_agent_daily_budget`	number	`20.00`	Per-agent daily spend ceiling (USD)
`alert_threshold`	number	`0.80`	Alert at this fraction of the ceiling

`[daemon.alerts]`

Key	Type	Default	Description
`dedup_window_ms`	number	`60000`	Suppress duplicate alerts within this window (ms)
`webhook_urls`	array	`[]`	List of webhook URLs for alert delivery

`[compliance]`

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable compliance features
`risk_level`	string	`"minimal"`	AI system risk classification
`log_pii`	boolean	`false`	Store raw args/results (GDPR warning)