fabro/docs/reference/user-configuration.mdx

---
title: "Settings Configuration"
description: "Configure CLI and shared machine defaults with settings.toml"
---

Fabro loads machine defaults from `~/.fabro/settings.toml`. The file is optional. If it does not exist, Fabro falls back to built-in defaults.

On a same-machine setup, the CLI and server both read this file. On a remote setup, each machine has its own `settings.toml` and reads the sections relevant to that process.

<Note>
Legacy `cli.toml`, `user.toml`, and `server.toml` are ignored with a warning. Rename them to `settings.toml`.
</Note>

## File location

The default path is `~/.fabro/settings.toml`.

Use `fabro server start --config /path/to/settings.toml` if the server should read a different file.

## Who reads what

`settings.toml` uses the same schema as `fabro.toml` and `workflow.toml`, but each process only reads the fields it understands.

| Scope | Examples |
|---|---|
| CLI-only | `verbose`, `upgrade_check`, `[server]`, `[exec]`, `[mcp_servers]` |
| Shared defaults | `[llm]`, `[log]`, `[git]`, `[pull_request]`, plus run-default sections like `[setup]`, `[sandbox]`, `[checkpoint]`, and `[vars]` |
| Server-only | `storage_dir`, `max_concurrent_runs`, `[web]`, `[api]`, `[features]` |

See [Server Configuration](/administration/server-configuration) for the server-owned sections.

## Precedence

For CLI commands running on the local machine, precedence is:

1. **CLI flags** — always win
2. **`workflow.toml` / `run.toml`** — per-run overrides
3. **`fabro.toml`** — project defaults
4. **`settings.toml`** — machine defaults
5. **Built-in defaults**

On a same-machine setup, the server reads the same `settings.toml`. On a remote setup, the CLI machine and server machine each use their own local `settings.toml`.

## Full example

```toml title="settings.toml"
verbose = true
upgrade_check = true

[server]
target = "https://fabro.example.com:3000/api/v1"

[server.tls]
cert = "~/.fabro/tls/client.crt"
key = "~/.fabro/tls/client.key"
ca = "~/.fabro/tls/ca.crt"

[exec]
provider = "anthropic"
model = "claude-opus-4-6"
permissions = "read-write"
output_format = "text"

[llm]
model = "claude-sonnet-4-5"

[log]
level = "info"

[git.author]
name = "fabro-bot"
email = "fabro-bot@company.com"

[pull_request]
enabled = true

[mcp_servers.filesystem]
type = "stdio"
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
startup_timeout_secs = 15
tool_timeout_secs = 90

[mcp_servers.filesystem.env]
NODE_ENV = "production"

[mcp_servers.sentry]
type = "http"
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.sentry.headers]
Authorization = "Bearer sk-xxx"
```

All fields are optional. Include only the sections and keys you want to override. On a same-machine install, this same file can also include server sections such as `[web]` and `[api]`.

## `upgrade_check`

Controls whether Fabro runs a daily background check for new releases. The check runs during `run`, `exec`, `init`, and `install` commands and prints a notice to stderr when a newer version is available.

| Value | Description |
|---|---|
| `true` | Check for new releases (default) |
| `false` | Disable automatic upgrade checks |

The `--no-upgrade-check` CLI flag overrides this for a single invocation. See [`fabro upgrade`](/reference/cli#fabro-upgrade) for manual upgrades.

## `verbose`

Enable verbose output by default for `fabro run start` and `fabro doctor`, without passing `-v` every time.

| Value | Description |
|---|---|
| `true` | Verbose output on by default |
| `false` | Normal output (default) |

The `-v` / `--verbose` CLI flag always takes effect regardless of this setting.

## `[exec]` section

Defaults for `fabro exec` sessions.

| Key | Description | Values | Default |
|---|---|---|---|
| `provider` | LLM provider | `"anthropic"`, `"openai"`, `"gemini"`, etc. | `"anthropic"` |
| `model` | Model name | Any model ID from `fabro model list` | Per provider |
| `permissions` | Tool permission level | `"read-only"`, `"read-write"`, `"full"` | `"read-write"` |
| `output_format` | Output format | `"text"`, `"json"` | `"text"` |

### Permission levels

- **`read-only`** — auto-approves read tools (`read_file`, `grep`, `glob`, `list_dir`) and subagent tools
- **`read-write`** — adds write tools (`write_file`, `edit_file`, `apply_patch`)
- **`full`** — allows all tools including shell commands

Tools outside the permission level are interactively prompted (if a TTY is present) or denied (with `--auto-approve`).

### Output formats

- **`text`** — human-readable terminal output
- **`json`** — NDJSON event stream

## `[llm]` section

Defaults for workflow model selection in commands like `fabro run` and `fabro preflight`.

| Key | Description | Values | Default |
|---|---|---|---|
| `model` | Model name | Any model ID from `fabro model list` | Per provider |
| `provider` | Provider name | `"anthropic"`, `"openai"`, `"gemini"`, etc. | Auto-inferred from model/catalog |

<Note>
Use `[exec]` to configure provider, permissions, and output format for `fabro exec`. Use `[llm]` for workflow-oriented defaults.
</Note>

## `[log]` section

Configure the default log level. Precedence: `FABRO_LOG` env var > `--debug` flag > `[log]` level > `"info"`.

| Key | Description | Values | Default |
|---|---|---|---|
| `level` | Log level | `"error"`, `"warn"`, `"info"`, `"debug"`, `"trace"` | `"info"` |

## `[git]` section

### `[git.author]`

Customize the git author identity used for checkpoint commits. On same-machine setups, the CLI and server read the same `[git.author]` value. On remote setups, each machine uses its own local `settings.toml`.

| Key | Description | Default |
|---|---|---|
| `name` | Git author name | `"fabro"` |
| `email` | Git author email | `"fabro@local"` |

## `[server]` section

Connection info for commands that target a remote Fabro server.

| Key | Description | Default |
|---|---|---|
| `target` | Server target: `http(s)` URL or absolute Unix socket path | none |

`fabro model` uses `[server].target` by default when no explicit `--storage-dir` is passed. An explicit `--server` flag overrides `server.target`:

```bash
fabro model list --server https://fabro.example.com:3000/api/v1
```

`fabro exec` does not automatically use `[server].target`. It only routes model traffic through a Fabro server when you pass `--server` for that invocation.

### `[server.tls]` section

Optional mTLS configuration for authenticating with the server. When present, the CLI presents a client certificate during the TLS handshake.

| Key | Description |
|---|---|
| `cert` | Path to client certificate PEM file |
| `key` | Path to client private key PEM file |
| `ca` | Path to CA certificate PEM file (to verify the server) |

Paths support `~/` expansion. Example:

```toml title="settings.toml"
[server.tls]
cert = "~/.fabro/tls/client.crt"
key = "~/.fabro/tls/client.key"
ca = "~/.fabro/tls/ca.crt"
```

## `[pull_request]`

Enable auto-PR globally so workflows open a GitHub pull request on successful completion, even when running with a `.fabro` file instead of a `run.toml`.

```toml title="settings.toml"
[pull_request]
enabled = true
```

| Key | Description | Default |
|---|---|---|
| `enabled` | Automatically create a PR after successful runs | `false` |

Precedence: `run.toml` > `fabro.toml` > `settings.toml` > built-in default (`false`).

## `[mcp_servers]` section

Configure [MCP servers](/agents/mcp) to connect to during `fabro exec` sessions. Each server is a named TOML table under `[mcp_servers]`. MCP servers can also be configured per-workflow in [run config TOML](/execution/run-configuration#mcp_servers).

### Stdio transport

Spawn a local process and communicate over stdin/stdout:

```toml title="settings.toml"
[mcp_servers.filesystem]
type = "stdio"
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
startup_timeout_secs = 15
tool_timeout_secs = 90

[mcp_servers.filesystem.env]
NODE_ENV = "production"
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"stdio"` | — |
| `command` | Array: executable + arguments | — |
| `env` | Additional environment variables for the child process | `{}` |
| `startup_timeout_secs` | Max seconds for the MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

### HTTP transport

Connect to a remote MCP server over Streamable HTTP:

```toml title="settings.toml"
[mcp_servers.sentry]
type = "http"
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.sentry.headers]
Authorization = "Bearer sk-xxx"
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"http"` | — |
| `url` | The MCP server endpoint URL | — |
| `headers` | Optional HTTP headers (for example, for authentication) | `{}` |
| `startup_timeout_secs` | Max seconds for the MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

### Sandbox transport

Run an MCP server inside the workflow's sandbox and connect via preview URL. Only available with remote sandbox providers ([Daytona](/integrations/daytona)) that support port previews. Typically configure this in [run config TOML](/execution/run-configuration#mcp_servers) rather than `settings.toml`.

```toml title="run.toml"
[mcp_servers.playwright]
type = "sandbox"
command = ["npx", "@playwright/mcp@latest", "--port", "3100", "--headless"]
port = 3100
startup_timeout_secs = 60
tool_timeout_secs = 120
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"sandbox"` | — |
| `command` | Array: the command to run inside the sandbox | — |
| `port` | Port the server listens on inside the sandbox | — |
| `env` | Additional environment variables for the server process | `{}` |
| `startup_timeout_secs` | Max seconds for startup + MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

See [MCP — Sandbox transport](/agents/mcp#sandbox) for how Fabro launches and connects to sandbox MCP servers.