Configuration
What a person sets to change Fiber's defaults, where it is written, and which
value wins. It also covers the format of a provider's data and of an
extension's manifest. Vocabulary is GLOSSARY.md. Where Fiber home is, and how
its files are written safely, is Fiber home.
Files and format
Every file Fiber reads as configuration is JSON: configuration, an extension's
settings, an extension's manifest and a provider's data. The one exception is
the system prompt files, SYSTEM.md and APPEND_SYSTEM.md
(docs/system-prompt.md): they are configuration files in Markdown. Only
config reads any of them. The parser is
serde_json, which Fiber already uses for everything else
(docs/dependencies.md), so configuration adds no crate. A TOML parser would have added 6
crates and 167 KiB of stripped binary on macOS arm64 (toml 1.1 against
serde_json alone, measured on September 25, 2026).
The JSON is strict: no comments and no trailing commas. Fiber writes to these files itself, as described in "When Fiber writes", so a comment would not survive anyway.
Reading configuration never runs code. A repository's configuration is read
before anyone has approved anything, so Lua is not a configuration format. The
only Lua a provider runs is its optional models(), quota(),
credential(), sign() and cost() functions (docs/model-routing.md,
"Model discovery").
Configuration never holds a secret. Secrets live in credentials/
("Secrets").
Layers
When the workspace's .fiber directory is Fiber home, there is no repository
layer: it is not read, and a write to it fails with usage.
Configuration comes in layers. A later layer wins over an earlier one, key by key:
- built-in defaults
- global:
config.jsonat the top of Fiber home - repository:
.fiber/config.jsonin the workspace - per project:
projects/<key>/config.jsonin Fiber home - per run:
-c key=valueon the command line
~/.fiber/config.json sets "model": "openrouter/anthropic/claude-sonnet-5".
A repository's .fiber/config.json sets "model": "databricks/databricks-claude-opus-5". Sessions in that repository use the
Databricks model, unless the person's projects/<key>/config.json sets
another, or they pass -c model=... for one run.
Objects merge key by key, so a layer changes only the keys it names. Any other
value, a list included, replaces the one below it. Each entry under a provider's
credentials replaces the one below it as a whole: it does not merge key by key.
Two values do not replace. reviewer.context: the reviewer reads the global
value and then the per-project one (docs/permissions.md, "What the person
tells it"). skills.disabled: the global list and the project's list both
apply.
The per-project file is the person's own setting for one project. It lives in
Fiber home, not the repository, so it covers every worktree of the project
(docs/state.md, "Projects"), and a delegate's fresh worktree has it too. A
gitignored file in the working tree would be missing from
every new worktree.
-c works on both doors: fiber ask, and the terminal, which passes it to
each session it asks the hub to start.
The key is a dotted path and the value is JSON, or a bare string when it does
not parse as JSON: -c compaction.tokens=200000, -c model=openai/gpt-5.6. It
may be given more than once. A named flag such as --model is shorthand for
the same thing, read before every -c, so -c model= wins over --model.
FIBER_HOME names Fiber home, and FIBER_CHANNEL names the release channel fiber update follows: the --channel flag beats the environment, and an empty setting means stable. install.sh reads the same channel setting, plus FIBER_INSTALL_DIR and FIBER_VERSION (docs/releasing.md); the shell tool sets FIBER_GREP_MATCHES
for the built-in grep it runs (docs/tools.md, "Shell"); no
environment variable overrides a key. Fiber also honours the platform's proxy
variables (docs/dependencies.md, "Proxies").
What a repository may set
A repository may set a key only when the worst a hostile value can do is cost the person time or money. It never sets a key that widens what runs without asking, changes where requests go, or weakens a safety check. A cloned repository is someone else's text, and it is read before anything is approved. The one exception is code the repository declares, which runs only after a person approves it, pinned to its exact content: those keys are marked "yes, with approval".
Each key says whether a repository may set it. A key that says nothing is
person-only, so a key added without thought stays safe. A repository that sets
a person-only key gets a notice naming the key and the file, and the value
is ignored.
The table in "Keys" marks each key. Two rules settled elsewhere follow from this one:
- A repository cannot declare a provider or change a base URL
(
docs/model-routing.md, "Choosing the model"). - A repository can declare extensions, hooks and MCP servers, and each runs
only after a person approves its exact content (
docs/extensions.md, "Code a repository ships"). It cannot enable an extension a person installed.
Keys
Keys are snake_case and grouped by area. In "Repo", yes means a repository may
set the key. The sandbox.* entries are the OS sandbox in #3027 on Linux
and #3630 on macOS; the build reads them on those platforms.
In an extensions."<name>" key, <name> is the extension's full name or,
for an extension that has one, its short name (docs/extensions.md,
"Names"): extensions."memory".enabled and
extensions."github.com/aakshintala/fiber/extensions/memory".enabled are the
same key. A file that sets one key under both spellings is config_invalid.
| Key | Default | Repo | Meaning |
|---|---|---|---|
model | none | yes | The default model for a new session, as provider/model (docs/model-routing.md, "Choosing the model"). |
thinking | the model's own default | yes | The thinking level for a new session (docs/model-routing.md, "Thinking"). |
model_lists.refresh_after | "24h" | no | How old a provider's cached model list must be before Fiber refreshes it in the background, as a duration such as "7d". The model picker's refresh button ignores it (docs/model-routing.md, "Model discovery"). |
model_lists.models_dev | true | no | Whether Fiber fetches models.dev's catalog to fill in model details, under the same age rule as model_lists.refresh_after; false keeps the details Fiber shipped with (docs/model-routing.md, "Which models exist, and what Fiber knows about them"). |
scoped_models | none | yes | A list of model references the model picker shows; none means every installed model (docs/tui.md, "Swapped views"). |
roles."<name>" | none | yes | A delegate's model reference, such as "fiber:openai/gpt-5.6:xhigh", or an object with model, the reference, and credential, the credential label the delegate uses (docs/delegates.md). A repository's role cannot name a credential: its credential is ignored with a notice. |
hub.port | none | no | The port of 127.0.0.1 an installed hub listens on, as well as its local socket; unset, it listens on its local socket only. fiber hub install --port writes it (docs/invocation.md, "The hub"). |
hub.allowed_origins | [] | no | The web page origins, such as "https://fiber.example.ts.net", whose websockets the hub accepts (docs/invocation.md, "Remote clients"). |
hub.idle_exit_ms | 1800000 (30 minutes) | no | How long a hub a client started stays running with no client connected, the same default as session.idle_exit_ms; an installed hub never exits for being idle (docs/invocation.md, "The hub"). |
hub.default | none | no | On a client, the name of the hub in hubs it uses without --hub; unset, it uses the local hub. |
hubs."<name>".address | none | no | On a client, a hub's address: ws://, wss://, or unix: and a socket path (docs/invocation.md, "Several hubs"). The device token is in credentials/hubs/<name>, never here. |
session.idle_exit_ms | 1800000 (30 minutes) | no | How long a session stays running with no turn, no jobs and no cache warming, whoever is connected (docs/invocation.md, "Lifecycle"). |
session.keep_exited | 10 | no | How many exited sessions each project keeps on home before the hub archives the older ones; 0 keeps them all (docs/invocation.md, "Archiving"). |
reviewer.model | none | no | The reviewer's model: when set it wins, else the provider's saved pick, else the package default (docs/permissions.md, "The reviewer"). |
reviewer.context | none | no | The person's notes about their environment, in prose, which the reviewer reads after its fixed instructions; the global and per-project values are both read, the project's winning where they conflict (docs/permissions.md, "What the person tells it"). Only Fiber home's global and per-project files set it; -c is ignored with a notice. |
reviewer.block_limits.consecutive | 3 | no | Consecutive blocks before a person is asked. |
reviewer.block_limits.session | 20 | no | Blocks in a session before a person is asked. |
compaction.enabled | true | yes | Whether automatic compaction runs (docs/compaction.md). |
compaction.tokens | 400000 | yes | The token trigger. |
compaction.window_fraction | 0.7 | yes | The trigger as a fraction of the model's context window. |
compaction.nudge | true | yes | Whether the nudge is given. |
cache.lifetime | "1h" | yes | The prompt-cache lifetime, "5m" or "1h" (docs/prompt-cache.md). |
cache.warm_idle | false | yes | Whether an idle session keeps its prompt cache warm (docs/prompt-cache.md, "Warming while idle"). |
cache.warm_cap | 2 | yes | How many cache lifetimes after the last turn warming stops, an integer; less than 12 (docs/prompt-cache.md, "Warming while idle"). |
cache.diagnostics | false | yes | Whether a debug http_request line for a model call also carries redacted prefix hashes and the reported cache use (docs/prompt-cache.md, "Cache diagnostics"). |
keys."<action>" | the binding in docs/tui.md | no | A key, or a list of keys, for a terminal action; [] unbinds it (docs/tui.md, "Bindings"). |
retry.attempts | 3 | yes | Retries of a failed model call (docs/model-routing.md, "When a model call fails"). |
retry.initial_delay_ms | 2000 | yes | The first backoff, doubling each retry. |
retry.max_delay_ms | 60000 | yes | The cap on one backoff, and on a wait a server asks for. |
tools."<name>".max_result_bytes | the tool's own, or 16384 | yes | The tool's result cap (docs/tools.md, "Bounded results"). |
tools."<name>".deferred | the tool's own | yes | Whether the tool is deferred (docs/tools.md, "What is deferred by default"). |
skills.disabled | [] | no | Names of skills switched off: left out of the listing, refused by the skill tool and not expanded by /name. The project's list and the global list both apply. The terminal's /skills view writes it (docs/system-prompt.md, "Skills"). |
web_search.backend | the one installed | no | The search backend web_search uses when more than one is installed (docs/tools.md, "Web fetch and web search"). |
shell.read_only."<command>".flags | none | no | Adds a command to the shell classifier's read-only list, with the flags it may take and stay read-only, such as ["--json", "-p"]. <command> is a command name, optionally followed by a subcommand path, such as "gh pr view" (docs/tools.md, "Shell", "Effects", and "Search", "Other command-line tools"). |
sandbox.enabled | false | no | Whether shell calls run inside the opt-in OS sandbox on Linux and macOS (docs/sandbox.md). Set in global config or with -c; a repository's project config cannot turn the sandbox on. |
sandbox.allow_write | [] | no | Extra paths a confined call may write, such as ["~/.pi/agent"], as a list of strings. Person-only, like every sandbox.* key. |
sandbox.deny_read | [] | no | Extra paths a confined call may not read, such as ["~/extra-secret"], as a list of strings. Person-only, like every sandbox.* key. Existing resolved credential paths merge into the same deny set. |
diagnostics.level | "info" | no | How much the diagnostic logs record: "info" or "debug" (docs/state.md, "What each part holds", says what each level writes). Only Fiber home's config.json sets it; a project's file or -c is ignored with a notice. A process reads it when it starts. Timing startup.config starts from one monotonic read taken before the configuration is read; at "info" that read is the only extra cost. |
budget.usd | none | no | The most a session may spend, in US dollars billed per token, its delegates included; unset means no limit (docs/loop.md, "Spending budget"). |
quota.notice_at | 80 | yes | The percent used of a quota window at which the model gets a notice (docs/tools.md, "Provider quota"). |
mcp.servers."<name>" | none | yes, with approval | An MCP server ("MCP servers"). |
repository_extensions | none | yes, with approval | The extension packages the repository ships: a list of objects with path, inside the repository, and required, default false (docs/extensions.md, "Code a repository ships"). Set anywhere but the repository's file, it is ignored with a notice. |
extensions."<name>".enabled | true | no | Whether an installed extension's non-provider parts load; false globally and true in a project's file scopes those parts to that project (docs/extensions.md, "Code a repository ships"). Provider data and discovery ignore this key: credential presence is their switch. In a mixed package, false still suppresses init, commands and hooks. |
extensions."<name>".startup_timeout_ms | 5000 | yes | A process extension's startup deadline. |
extensions."<name>".commands."<command>" | none | yes | A new name for one of the extension's commands, when two extensions clash. |
extensions."<name>".tools.enabled, extensions."<name>".tools.disabled | none | yes | Lists of the extension's tool names to declare or leave out, as an MCP server's tools.enabled and tools.disabled do ("MCP servers"); the terminal's /tools switch writes them (docs/tui.md, "Swapped views"). |
extensions."<name>".hook_timeout_ms | the callback's own | no | Overrides the timeout of every hook and watcher the extension registers, including the entries the hooks extension registers from configuration. |
hooks.order."<hook point>" | none | no | Extension names in the order their hooks run at that point (docs/extensions.md, "When several hooks share a point"). |
providers."<name>".credential | default; fiber login writes the first label it stores | no | The credential label a new session uses (docs/model-routing.md, "Which credential a session uses"). |
providers."<name>".credentials."<label>" | none | no | Where that label's key comes from, when it is not stored in Fiber home ("Secrets"). |
providers.databricks.request_tags | none | no | An object of string values merged into the Databricks-Ai-Gateway-Request-Tags header of the session's Databricks model calls, such as {"run": "r1"} ("A provider's data"). The person's global and project files and -c set it; a repository's value is ignored with a notice. |
providers."<name>".reviewer_model | the package's reviewer_model | no | The provider's saved reviewer pick, written by fiber login ("Secrets"). A reviewed call uses it after reviewer.model and before the package default; the stored ID is local and gains the provider's prefix once. |
tui.panel.cards | ["session", "changed_files", "delegates", "jobs", "quota"] | no | The cards the terminal's panel shows, in order; an extension widget is listed as "<extension>/<widget>", and a widget the list does not name shows after the listed cards (docs/tui.md, "The panel"). The input box's status line, shown while the panel is not, follows the same order. |
tui.rail.shown | true | no | Whether the terminal's rail shows; ⌥R and /rail write it (docs/tui.md, "The rail"). |
tui.rail.width | 15 | no | The rail's share of the screen's width, in percent, kept from 22 to 48 columns; dragging its edge writes it (docs/tui.md, "Layout"). |
tui.panel.width | 21 | no | The panel's share of the screen's width, in percent, kept from 30 to 60 columns; dragging its edge writes it. |
tui.theme | none | no | The theme's name: auto, dark, light or the name of a theme file in Fiber home's themes/ or an installed, enabled extension's themes/. A switched-off extension's themes are not listed, and naming one reads as a missing file. With none or auto, the theme follows the terminal's light or dark appearance (docs/tui.md, "Themes"). |
tui.editor | none | no | The command Ctrl+G and "Open in editor" run, such as nvim or code --wait; with none, $VISUAL, then $EDITOR (docs/tui.md, "The editor"). |
tui.reduced_motion | false | no | Whether every animation takes its still form. Detection is not built yet (see #1506) (docs/tui.md, "Reduced motion"). |
Not built yet: see #1506.
| Key | Default | Needs approval | What it sets |
|---|---|---|---|
tui.attention.notification | true | no | Whether the terminal sends an OSC 9 desktop notification when a session starts waiting on the person (docs/tui.md, "Getting the person's attention"). |
tui.attention.bell | true | no | Whether it rings the bell where OSC 9 is not supported. |
tui.attention.title | true | no | Whether the terminal title shows the session's state. |
tui.hover | true | no | Whether hover highlights the click target under the pointer; false drops mouse mode 1003 (docs/tui.md, "Mouse and hover"). |
tui.inline_images | true | no | Whether images show inline where the terminal speaks kitty's graphics protocol (docs/tui.md, "Images"). |
tui.logo_glyph | "⌇" | no | The glyph before the name in the logo, "⌇" or "≈", for a font without ⌇ (docs/tui.md, "The logo"). |
tui.slots."<slot>" | none | no | The extension that fills a slot two extensions replace, such as tui.slots."ledger_row:shell"; the same for a key two extensions bind, as tui.slots."key:ctrl+k", where the suffix canonicalizes as a key name and an unmatched setting wins nothing (docs/tui.md, "When two extensions want one slot"). |
Hook order and hook timeouts are person-only so that the person keeps the
final say over the hooks they run. Order is precedence, not a security
boundary: every approved hook runs with the account's full rights. Phases put
redaction first whoever ships it (docs/extensions.md, "When several hooks
share a point").
Per model
Some keys can be set for one model. They sit under models."provider/model"
and win over the same key at the top level of the same layer:
{
"compaction": { "tokens": 400000 },
"models": {
"databricks/databricks-claude-opus-5": {
"compaction": { "window_fraction": 0.5 },
"cache": { "lifetime": "5m" }
}
}
}
The keys that may be set per model are compaction.*, cache.lifetime and thinking. A
per-model key may be set by a repository when the top-level key may be.
MCP servers
Each entry under mcp.servers holds what docs/mcp.md ("Configuration")
lists:
| Field | Meaning |
|---|---|
command, args, env | the program of a stdio server; an env value is a string, or { "secret": "<name>" }, which reads credentials/<name> when the server starts. The name must be mcp.<server>.<KEY>, where <KEY> is an environment variable name with no ., so a server reads only its own secrets |
url | a remote server |
required | whether failing to start ends the session, default false |
startup_timeout_ms | the startup deadline, default 5000 |
timeout_ms | the call timeout |
declare_in_full | whether its tools are declared in full rather than deferred, default false |
tools.enabled, tools.disabled | lists of tool names |
tools."<tool>".hints | overrides of that tool's MCP hints |
A server that declares both command and url is not started, and a
notice with code config_invalid says so; a required one fails the
session with config_invalid.
A repository may declare a server, subject to approval of its declaration and
of each file its command or args names inside the repository
(docs/extensions.md, "Code a repository ships"). tools."<tool>".hints
is person-only: a repository that marked a tool readOnlyHint would skip the
reviewer for it.
Extension settings
An extension's own settings live in their own file in each layer, never in
config.json:
| Layer | File |
|---|---|
| global | config/<extension>.json in Fiber home |
| repository | .fiber/config/<extension>.json |
| per project | projects/<key>/config/<extension>.json in Fiber home |
| per run | -c extensions."<extension>".settings.<key>=value |
<extension> is named as in extensions/ (docs/state.md, "What each part
holds"). The layers merge exactly as Fiber's own keys do.
host.config.get(key)returns the merged value.host.config.set(key, value, scope)writes one file.scopeis"machine"for the global file or"project"for the per-project file, the same wordshost.data_dirtakes. It has no default, so the author decides. A model picker can save a choice for one project only.- A repository sets only the keys the extension's manifest lists under
repo_settings. Fiber cannot judge a key it does not know, but the author can, so the author applies the rule in "What a repository may set". Any other key in the repository's file gets anoticeand is ignored. The list comes from the manifest of the installed or approved copy, never from a repository's working files. Thehooksextension listshooks, and each hook a repository declares there is withheld until a person approves it (docs/extensions.md, "Hooks declared in configuration"). Any entry a repository declares there, hook or watcher, may setrequired, default false, read only from the repository's file: a required entry nobody approved fails a run that has nobody to ask, withhook_unapproved. fiber extension removedeletes the extension's file in the global and every per-project layer, asking first in a terminal, as it does for its data directories.
A separate file means an extension never rewrites the person's config.json.
The first-party bedrock extension has one setting, region: the AWS region
its models' base URL names, read from AWS_REGION when it is unset
(docs/model-routing.md, "A per-account host"). Its credential is not a key
source. Its credential() reads AWS_BEARER_TOKEN_BEDROCK, AWS keys from the
environment, or what aws configure export-credentials prints, and the
credential label is the AWS profile name: providers."bedrock".credential
set to my-profile reads that profile, and /credential switches it
(docs/model-routing.md, "Protocols and providers").
The first-party vertex extension has one setting, project: the Google
Cloud project its models' base URL names, read from GOOGLE_CLOUD_PROJECT
when it is unset (docs/model-routing.md, "A per-account host"). Its
credential is not a key source. Its credential() asks the Google Cloud CLI
for a token, and the credential label is a gcloud configuration's name:
providers."vertex".credential set to work takes the token of the
configuration work, and /credential switches it
(docs/model-routing.md, "Protocols and providers").
Secrets
A secret is a file in credentials/ in Fiber home, mode 0600. A provider's
credentials are credentials/<name>/<label>, one file per credential label
(docs/model-routing.md, "Credentials"). An extension's secrets share the
directory as single files: host.secret(name) reads credentials/<name>. An
extension declares each name it reads in its manifest's secrets, and
host.secret reads no other ("An extension's manifest"). By convention, an
extension prefixes its names with its own name, such as acme.api_key.
fiber login <name> stores a declared secret: it reads the value from a
hidden prompt, or from stdin without a terminal, and writes
credentials/<name> with mode 0600. A secret that is already stored is
replaced, and the command says so, because logging in again is how a key is
rotated. A name that is neither a provider nor a secret an installed extension
declares is refused, so a mistyped name is caught rather than stored where
nothing reads it.
This is one namespace, not a wall between extensions. An extension runs with
the account's full rights and could read credentials/ with host.fs anyway
(docs/extensions.md, "Lua extensions"). The credential deny protects the
directory from tool calls, not from extensions
(docs/permissions.md, "Credentials").
A provider's data declares how its default credential is found. A person
adds or overrides a label at providers."<name>".credentials."<label>" in the
global or per-project file, with one of:
{ "env": "OPENROUTER_API_KEY" }
{ "file": "/Users/alice/.secrets/openrouter" }
{ "command": ["op", "read", "op://Private/OpenRouter/key"] }
A command that succeeds runs once per process, and its key is kept. A command
that fails runs again the next time the key is read, so a fixed command works
without restarting Fiber. A command source takes an optional timeout, a
duration such as "2m", defaulting to "30s":
{ "command": ["op", "read", "op://Private/OpenRouter/key"], "timeout": "2m" }
A command still running at its timeout has its whole process group killed, and
reading the key fails with credential_missing. The run is not kept, so the
next read runs the command again. The timeout applies wherever a command
source runs: session start, a switch, the reviewer lookup and a model-list
refresh. A command is named by its program alone in every
message, because its arguments may hold a key. A repository can never set this, because a
command runs a program and a changed source sends the key elsewhere. A
credential stored under the same label comes first. A key from an env
source stays in Fiber's environment, so it is visible to every command the
session runs.
Providers in one package that share a key read one stored credential: each
names the stored directory in its provider data (credential_name, defaulting
to its own name). fiber login <provider> stores the key in the directory
that provider reads, so fiber login opencode-go and
fiber login opencode-zen both store under credentials/opencode/.
At a terminal, fiber login <provider> asks which model reviews that
provider's calls once the credential is stored, listing the provider's
models with the saved pick preselected, else the package default; Enter
keeps it. The answer is written to providers."<name>".reviewer_model
in the global file, one pick per provider, so logging in to a second
provider never overwrites the first. Without a terminal nothing is asked
and nothing is written. A blank answer keeps a preselected pick and asks
again with nothing preselected; end of input keeps the credential, prints
that no reviewer was set and exits 0. A save that fails keeps the
credential, names the key and exits non-zero. When the provider lists no
models the credential stays and no reviewer is written.
fiber logout <provider> deletes the provider's stored credential. When the
provider has several labels, it refuses unless given --as <label> or --all.
When the key comes from an environment variable, a file outside Fiber home or
a command, fiber logout cannot remove it: it names the source and exits
non-zero.
A live session keeps its cached key: only sessions started after the delete fail
with credential_missing, unless a configured source covers the label, which
later sessions then use.
When Fiber reads configuration
Only the config crate reads these files (docs/architecture.md). It reads
them:
- when a session starts
- on
reload(docs/invocation.md, "Driver commands"), which costs the one prompt-cache miss reload already costs (docs/mcp.md, "Reload") - when a session resumes, where changed configuration rebuilds the preamble as
docs/prompt-cache.mddescribes - at each turn start,
skills.disabledonly, with the check for added and removed skills (docs/system-prompt.md, "Added and removed skills")
A reload fails as a start does. One a start would refuse, such as invalid
configuration or a required extension that fails, is rejected with the start's
code and changes nothing: the session keeps its configuration, tools and
extensions, and writes no reloaded. A failure a start goes on past, such as
an extension that is not required failing to load, writes the notice a start
writes, and the rest of the reload applies.
Nothing watches the files, so an idle Fiber does no work. A value written with
host.config.set is visible to that extension at once, and to other sessions
at their next reload.
So a key written while Fiber runs applies, and the terminal's /settings says
when (docs/tui.md, "Swapped views"):
tui.themeat once: the terminal applies the theme it writes- any other
tui.*key when the terminal starts again hub.port,hub.allowed_originsandhub.idle_exit_mswhen the hub starts againhub.defaultandhubs.*at a client's next connection: the nextfibercommand, or the terminal's next startdiagnostics.levelwhen each Fiber process starts againmodel,thinking,models."<provider/model>".thinking,providers."<name>".credential,providers."<name>".credentialsandproviders.databricks.request_tagsfor sessions started after the write: a running session changes model, thinking level or credential only through a switch (docs/model-routing.md), never onreloadskills.disabledat the next turn start- every other key on
/reload, with the one prompt-cache miss it costs
A problem in a file is reported by file and key:
- An unknown key is a
noticeand is otherwise ignored. A repository written for a newer Fiber must not break an older one. A command that runs no session, such asfiber config,fiber loginorfiber models, prints each notice as one line on stderr. - Invalid JSON, or a value of the wrong type, is a startup error. A headless
run fails with
config_invalid. The one exception isproviders.databricks.request_tags: a merged value that is not an object of string values is ignored with oneconfig_invalidnotice that names the key, and the default header is sent.
When Fiber writes
Fiber writes configuration in these places:
- the model picker saves the global
model, and a thinking level asmodels."<provider/model>".thinking, unless the choice is marked as this session only (docs/tui.md, "Swapped views") - dragging the rail's or the panel's edge saves the global
tui.rail.widthortui.panel.width(docs/tui.md, "Layout") - ⌥R,
/rail, or dragging the rail below its floor saves the globaltui.rail.shown(docs/tui.md, "The rail") /credentialsaves the globalproviders."<name>".credential, unless the label is chosen with Ctrl+S in the credential picker (docs/tui.md, "Swapped views"), andfiber login, or the terminal's/login, writes it when it stores a provider's first label (docs/model-routing.md, "Credentials")/scoped-modelssaves the globalscoped_models, and the/keysscreen saves the globalkeys, only the bindings that differ from the defaultshost.config.setwrites an extension's settings filefiber extension install --projectwritesextensions."<name>".enabled:truein the project's file, andfalsein the global file for an extension it installs for the first time (docs/extensions.md, "Code a repository ships")fiber config set <key> <value>writes the global file, the per-project file with--project, or the repository's.fiber/config.jsonwith--repo- the terminal's
/settingswrites a key through the same path asfiber config set, in the layer the person picks among those the key allows (docs/tui.md, "Swapped views") - the terminal's
/toolsswitches write an MCP server's or an extension'stools.enabledandtools.disabledin the project's file or the global file, never a repository's; a file that holds no list starts from the one it inherits (docs/tui.md, "Swapped views") - the terminal's
/skillsswitches write a skill's name toskills.disabledin the project's file or the global file, never a repository's; each file's own list, since both apply (docs/tui.md, "Swapped views") - the terminal's
/rulesdeletes one line of a rules file under the file's lock, leaving every other line as it was (docs/tui.md, "Swapped views"; "Standing rules") fiber mcp addandfiber mcp removewrite an entry undermcp.servers, in the same three files (docs/mcp.md, "Configuration")fiber hub install --portwrites the globalhub.port.fiber hub addandfiber hub removewrite the globalhubsentry. With--default,hub addalso writeshub.default;hub removeclears it when it names that hub (docs/invocation.md, "The hub")
Each write takes the lock, reads the file, changes one key and writes the whole
file back by renaming a temporary file over it (docs/state.md, "Concurrent
access"). Keys are written sorted with a 2-space indent, so a hand-chosen key
order is lost on the first write.
fiber config get <key> prints the effective value and the layer or flag it
came from. fiber config set never touches the network, for any key; it checks
the value's type. fiber config set --repo refuses a key a repository may not
set ("What a repository may set"), before it writes anything.
fiber config set model <ref> also checks the reference against the cached
model list, by the rules in docs/model-routing.md, "Naming a model". A
reference that matches nothing fails with no_model and names the closest
matches. With no cached list, the value is accepted. A reference to a model
left out with model_unconfigured (docs/model-routing.md,
"A per-account host") is written: Fiber prints that notice on stderr as one
line, fiber: and its message, and exits 0, so the person can set the host
next.
cache.warm_cap is refused with config_invalid when it is 12 or more
(docs/prompt-cache.md, "Warming while idle"), whether
it is set with fiber config set or by hand.
Standing rules
Standing rules are not configuration keys. They are two files in Fiber home:
rules at the top level for global rules, and projects/<key>/rules for one
project (docs/permissions.md, "Remembering a decision"). A repository has no rules
file.
Each line is one JSON object:
{"decision":"allow","tool":"shell","prefix":"npm test"}
decision is allow, ask or deny; tool is the tool's name and
prefix what it matches (docs/permissions.md, "What a rule matches"). A
line saved from an approval also carries added, milliseconds since the Unix
epoch, and session_id, the session that added it, which /rules shows.
Unknown keys are ignored and blank lines are skipped. A missing file holds no
rules. A file or line that cannot be read denies calls until it is fixed
(docs/permissions.md, "Scope").
The repository's .fiber/ directory
.fiber/
config.json repository configuration, including repository_extensions
config/<extension>.json settings for an extension, repo_settings keys only
The packages a repository ships may sit in any directory of it;
repository_extensions names them.
An extension's manifest
An extension's manifest is extension.json at the top of its directory. It
holds what docs/extensions.md ("What a package holds") lists:
{
"name": "github.com/acme/fiber-acme",
"version": "v1.4.0",
"fiber": "0.3.0",
"api": 1,
"depends": { "github.com/acme/oauth-helper": "v1.2.0" },
"binaries": {
"darwin-arm64": { "url": "https://...", "sha256": "..." }
},
"process": {
"program": "node",
"args": ["dist/main.js"],
"required": false,
"exit_timeout_ms": 2000
},
"install": ["npm", "ci"],
"memory_mib": 8,
"repo_settings": ["workspace_url"],
"replaces": ["web_search"],
"providers": { "acme": ["https://api.acme.dev/v1"] },
"commands": { "acme-status": { "description": "Show the Acme sync state", "argument_hint": "[project]" } },
"tui": { "session_versions": { "min": "v1.2.0", "before": "v2.0.0" } },
"prompt": "prompt.md",
"secrets": ["acme.api_key"],
"opening": {
"machine": ["index.md"],
"project": ["index.md"],
"budget_bytes": 25000
}
}
fiber is the lowest Fiber version it runs on. api is the extension API's
major version it was written for; Fiber loads it only when that is Fiber's own
(docs/extensions.md, "The extension API version"). process is present only for
a process extension, and exit_timeout_ms has no default. Its program follows the same rule as a Lua host.exec program: a path containing / that is not absolute resolves against the package directory and must stay inside it, a bare name resolves on PATH, and an absolute path is used as written. A Lua extension's
entry script is init.lua at the top of its directory; its provider's Lua is
providers/<name>.lua. Each providers key must be one filename, not a path.
A TUI extension's entry script is tui/init.lua. Its manifest declares tui.session_versions, the session-half version range the TUI extension works with (docs/extensions.md, "Client halves"). The range is an object: min is required and inclusive, before is optional and exclusive, and both are version tags in the form docs/extensions.md, "Versions", uses (v1.4.0) that compare as SemVer. With no before, the range has no upper bound. A session half's version v is in the range when min <= v, and also v < before when before is given. Any other version follows "Client halves": the client half is inert for that session, the built-in draws, and one notice names the extension and both versions. An install reads the range without running Lua, and refuses a range with a missing min, a value that is not a version tag, or before at or below min.
memory_mib raises a
Lua extension's memory cap, in MiB, above the default of 1
(docs/extensions.md, "Loading, and cost when nothing is loaded"). replaces
lists the built-in tools and commands the extension replaces, providers
maps each provider it registers to its base URLs, and commands maps each
command it registers to its description and optional argument hint; all three
default to none, and a
registration beyond what the manifest declares stops the extension loading
(docs/extensions.md, "What a package holds"); for commands that bound
holds only on a lazy start with a declared commands key, and an extension
without that key registers commands at session start as today. A commands
key makes the extension lazy: its
init.lua runs on the first run of one of its commands instead of at session
start, and it registers only the commands the manifest declares
(docs/extensions.md, "Loading, and cost when nothing is loaded"). prompt names a
file in the package whose text goes in the system prompt
(docs/system-prompt.md, "Extension texts"). secrets lists the names the
extension reads with host.secret, and defaults to none ("Secrets").
opening names files whose text
goes in the opening message: machine lists paths in the extension's machine
data directory and project paths in its project data directory
(docs/state.md, "What each part holds"), each relative to that directory
and inside it. budget_bytes is the section's optional byte budget: over it,
Fiber tells the model to prune the files when it builds the opening message
and after a call by the session that declares a writes effect on one of them
(docs/system-prompt.md, "Extension sections"). All three default to none.
A provider's data
Each provider an extension registers as data is providers/<name>.json in the
extension's directory. Its optional Lua is providers/<name>.lua beside that
data file and registers only that provider (docs/extensions.md, "Registering").
The fields are the ones docs/model-routing.md ("What a provider extension
declares") lists:
{
"name": "databricks",
"credential": { "env": "DATABRICKS_TOKEN" },
"placeholders": { "workspace": { "env": "DATABRICKS_HOST" } },
"headers": { "Databricks-Ai-Gateway-Request-Tags": "{\"source\":\"fiber\"}" },
"models": [
{
"id": "databricks-claude-opus-5",
"name": "Claude Opus 5 (Databricks)",
"protocol": "anthropic-messages",
"base_url": "https://{workspace}/ai-gateway/anthropic/v1",
"compat": { "bearer": true },
"deferred_tools": true,
"extra_body": {},
"context_window": 1000000,
"max_output_tokens": 128000,
"input": ["text", "image"],
"cost": { "input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25 }
}
]
}
-
credentialsays how thedefaultkey is found:env,fileorcommandas in "Secrets". A stored credential always comes first (docs/model-routing.md, "Credentials"): the provider reads the directory itscredential_namenames, orcredentials/<name>/when it names none, so providers in one package that share a key name the same directory. A provider whose token expires, such as an OAuth login, declares a Luacredential()function instead. -
headersare sent on every request. FordatabrickstheDatabricks-Ai-Gateway-Request-Tagsheader holds a JSON object of tags,{"source":"fiber"}by default. The keyproviders.databricks.request_tagsadds to it for the session's model calls: an object of string values, set in the global or project file or with-c, and read once when the session starts.fiber ask -c providers.databricks.request_tags='{"run":"r1"}'and a hubstartwith the overrideproviders.databricks.request_tags={"run":"r1"}both send{"source":"fiber","run":"r1"}. Objects merge key by key across layers ("Layers").sourceis alwaysfiber: asourcein the value is dropped. A value that is not an object of string values, such as a bare string, a number, a list, a nested object or an object with a non-string entry, is ignored whole with oneconfig_invalidnotice naming the key ("When Fiber reads configuration"), and the default header is sent. Model discovery requests always send the default header. -
loginisbrowserfor a provider whosefiber loginruns itscredential()login instead of reading a key. Absent means a key. -
credential_labelis for a provider whosecredential()reads nothing Fiber stores:namesis what a credential label names,defaultwhat thedefaultlabel reads (docs/model-routing.md, "What a provider extension declares"). A file that declares it besideloginorcredentialis invalid. Its optionalcredential_pathslists the paths thatcredential()draws secrets from, which the credential deny protects (docs/permissions.md, "Credentials"). Each entry is{"path": "~/.aws/credentials", "env": "AWS_SHARED_CREDENTIALS_FILE", "join": "<name>"}:pathis the location, a leading~read fromHOME;env, when that variable is set and not empty, replacespath;join, one name, is appended after that choice, such as a file in a directory the variable moves.envandjoinmay be left out. A relative path is read from the workspace. Optionalcredential_envis a list of environment variable names. Any listed variable set to a nonempty value, or any resolved declared path, switches this provider on; stored credentials and configured key sources do not count for it. Bedrock listsAWS_BEARER_TOKEN_BEDROCKandAWS_ACCESS_KEY_ID; Vertex lists none and relies on paths. A regular file counts even when empty. A directory needs one entry, checked with one directory read without opening the entry. Declared-path symlinks are followed; failed checks do not prove presence. These checks never runcredential()or a command and do not validate a credential.credential_envis invalid outsidecredential_label. -
compatis a flat object of the flags the protocol reads. Fiber never guesses a flag, and a flag that is absent is not set:Flag Type Read by Effect storeboolean openai-responses,openai-completionssent as the request's store; absent, the request has nostorekeymax_tokensboolean openai-completionsthe output limit goes in max_tokens; absent, it goes inmax_completion_tokensreasoning_objectboolean openai-completionsthe thinking level goes in reasoning: {effort}, as OpenRouter takes it; absent, it goes inreasoning_effortanthropicboolean openai-completionsthe model is Anthropic's, behind a gateway such as OpenRouter: requests carry Anthropic's cache_controlmarkers on content parts, and Anthropic's strict-tool limits applygeminiboolean openai-completionsthe model is Gemini's, behind a gateway such as Databricks: requests carry no stream_optionsorprompt_cache_key, and nullabletypearrays are rewritten, except insideenum,const,defaultorexamplesvaluescache_key_fieldstring openai-completionsa body field that also carries the cache key, such as OpenRouter's session_idcache_key_headerstring openai-responses,openai-completions,anthropic-messages,google-generative-aia header that carries the cache key, such as OpenCode's x-opencode-sessionthinking_budgetboolean anthropic-messagesthe thinking level goes in thinking: {type: "enabled", budget_tokens}(docs/model-routing.md, "Thinking"); absent, it goes inthinking: {type: "adaptive"}andoutput_config: {effort}bearerboolean anthropic-messagesthe key goes in authorization: Bearer; absent, it goes inx-api-keybedrock_invokeboolean anthropic-messagesthe model is Claude on AWS Bedrock's Invoke API: the request goes to <base_url>/model/<id>/invoke-with-response-streamwithanthropic_versionin the body and nomodelorstream, the key goes inauthorization: Bearer, and the reply is read in AWS event-stream framing (docs/model-routing.md, "Bedrock Invoke wire facts")vertex_raw_predictboolean anthropic-messagesthe model is Claude on Google Vertex: the request goes to <base_url>/models/<id>:streamRawPredictwithanthropic_versionin the body and nomodel, and an error body that is a list of one object is read as that object (docs/model-routing.md, "Google Vertex wire facts")cache_pointboolean bedrock-conversethe model takes cachePointblocks: requests carry them where Anthropic's cache markers go, each after a text block (docs/prompt-cache.md, "Cache markers and keys"); absent, no marker is sentreasoning_fieldstring bedrock-conversethe additionalModelRequestFieldsfield that carries the thinking level,reasoning_effortorreasoningConfig(docs/model-routing.md, "Thinking"); absent or any other value, no level is sentopenai-completionssendsstream_options.include_usage: true, because OpenAI sends no usage without it (docs/model-routing.md, "openai-completions facts"); a model withcompat.geminisends nostream_options. -
extra_bodyis added to every request for the model. It may add a field or replace one such asmax_tokens, but may not name a field listed indocs/model-routing.md, "Extra request body fields"; a model that does is left out with the noticemodel_invalid(docs/model-routing.md, "Extra request body fields"). -
A
{name}in abase_urlis a per-account host. Its value is the extension's setting of that name, which only the person sets;placeholdersmay name an environment variable read when the setting is unset. A model whose placeholder has no value, or a value that is not a host, is left out with the noticemodel_unconfigured(docs/model-routing.md, "A per-account host"). -
web_searchis the vendor's hosted-search tool type as it is sent; absent, the model hosts no search. A type its protocol does not read back leaves the model out withmodel_invalid(docs/model-routing.md, "Hosted web search"). -
nameis the model's display name, which the model picker's filter matches beside the provider and id (docs/tui.md, "Swapped views"). Absent, the model is matched on provider and id only. -
context_windowis required. A model without it is left out with the noticemodel_invalid(docs/model-routing.md, "What a provider extension declares"). -
thinking_levelslists the thinking levels the model takes, andthinking_defaultis the model's own default, used when no session choice or configured value names one (docs/model-routing.md, "Thinking"). Absent levels mean the model takes none. A default not among the levels leaves the model out withmodel_invalid. -
deferred_toolsis set only after a probe (docs/tools.md, "Which tools the model sees"), except the Databricks Claude rows set from theirproviders/anthropiccounterparts there. Absent means false. -
costis in US dollars per million tokens. A model priced by request size addstiers, a list of the same four prices, each withinput_tokens_above: the highest threshold the request's whole input exceeds prices the whole call, and below every threshold the base prices apply. The whole input counts cache reads and writes (docs/model-routing.md, "Cost"). Absent means one price at every size. -
subscriptionistruefor a model a subscription login serves; itscostis then the vendor's API prices (docs/model-routing.md, "Cost"). Absent means false.
Importing
fiber import copies configuration from one other harness into Fiber home,
once (docs/invocation.md, "Commands and flags"). It reads ~/.claude
(Claude Code) or ~/.codex (Codex) and copies what maps into Fiber's own
configuration; it never reads the other harness again, and it imports no
past conversations. Every pinned source path is optional: a missing file,
table or directory means nothing to import from it, never an error.
~/.claude.json is state and caches, not configuration, and the import
never reads it.
What each source item maps to:
| Source | Fiber destination |
|---|---|
Claude Code skills/*/SKILL.md | A personal skill: one directory per skill in skills/ in Fiber home, discovered at session start like every other personal skill (docs/system-prompt.md, "Skills") |
Claude Code commands/*.md | A prompt template: the same directory shape holding a synthesized header (its name from the file stem, its description from the first non-empty line, model invocation disabled) plus the file's bytes as the body, so the person runs it by name and the model listing leaves it out |
Claude Code CLAUDE.md | CLAUDE.md at the top of Fiber home |
Claude Code settings.json mcpServers | User-scope MCP servers in the global layer, with the field map docs/mcp.md ("Configuration") lists |
Codex skills/*/SKILL.md | A personal skill, as above |
Codex prompts/*.md | A prompt template, as above |
Codex config.toml [mcp_servers] | User-scope MCP servers in the global layer, read through a narrow subset reader: section headers plus scalar command, args, env, url and required lines only |
Codex AGENTS.md | AGENTS.md at the top of Fiber home |
A Codex server entry outside that subset — another table, another key, or a multi-line or otherwise unparseable value — is refused to the left-behind list with its reason, never interpreted. A refused secret value (an API key, a token, an auth file, a secret block in a server declaration) is named there without its value, and the value reaches neither Fiber's files nor the report. Anything else unmapped — agents, hooks, permissions, sessions, history, todos, credentials — lands in left-behind with its category and reason; nothing is lost silently.
Each source directory (skills/, commands/, prompts/) is read for at most 512 entries. A directory holding more keeps 512 of them, which 512 is unspecified, and adds one left-behind line for that item: "more than 512 entries, keeping the first 512". The kept entries are imported in name order.
The import never overwrites: a colliding skill, command or server name is suffixed and reported, while a colliding instruction target is never suffixed, since a suffixed fixed name is never read — the existing file stands and the item goes to left-behind with the occupied target as its reason. Identical bytes are skipped without error.
A skill Fiber already reads from another source, such as a Claude Code skill whose directory is a link into ~/.agents/skills/ or one whose name is already in ~/.agents/skills/, is not copied: it goes to left-behind with "already read from
One receipt file per source sits at the top of Fiber home,
import-claude-code.json and import-codex.json, each holding its source,
time and counts (docs/state.md, "What each part holds"). A completed
receipt short-circuits the command for that source: with a completed
receipt the command succeeds without reading the source at all. The receipt
is written last, and only on full success. Over a remote hub connection
the import runs on that machine: /import in the terminal imports the
hub machine's ~/.claude or ~/.codex, never the terminal's own home.
A provider with a models() function returns a list in exactly the shape of
models. Fiber caches it at cache/models/<name>.json.
A person changes provider data only through an extension. A local server such as Ollama is an extension directory holding one provider file, installed from its path. A wrong context window is fixed in a local copy of the extension or upstream. Configuration has no second source of provider data, so there are no merge rules between the two.