fiber

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:

  1. built-in defaults
  2. global: config.json at the top of Fiber home
  3. repository: .fiber/config.json in the workspace
  4. per project: projects/<key>/config.json in Fiber home
  5. per run: -c key=value on 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:

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.

KeyDefaultRepoMeaning
modelnoneyesThe default model for a new session, as provider/model (docs/model-routing.md, "Choosing the model").
thinkingthe model's own defaultyesThe thinking level for a new session (docs/model-routing.md, "Thinking").
model_lists.refresh_after"24h"noHow 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_devtruenoWhether 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_modelsnoneyesA list of model references the model picker shows; none means every installed model (docs/tui.md, "Swapped views").
roles."<name>"noneyesA 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.portnonenoThe 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[]noThe web page origins, such as "https://fiber.example.ts.net", whose websockets the hub accepts (docs/invocation.md, "Remote clients").
hub.idle_exit_ms1800000 (30 minutes)noHow 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.defaultnonenoOn a client, the name of the hub in hubs it uses without --hub; unset, it uses the local hub.
hubs."<name>".addressnonenoOn 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_ms1800000 (30 minutes)noHow long a session stays running with no turn, no jobs and no cache warming, whoever is connected (docs/invocation.md, "Lifecycle").
session.keep_exited10noHow many exited sessions each project keeps on home before the hub archives the older ones; 0 keeps them all (docs/invocation.md, "Archiving").
reviewer.modelnonenoThe reviewer's model: when set it wins, else the provider's saved pick, else the package default (docs/permissions.md, "The reviewer").
reviewer.contextnonenoThe 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.consecutive3noConsecutive blocks before a person is asked.
reviewer.block_limits.session20noBlocks in a session before a person is asked.
compaction.enabledtrueyesWhether automatic compaction runs (docs/compaction.md).
compaction.tokens400000yesThe token trigger.
compaction.window_fraction0.7yesThe trigger as a fraction of the model's context window.
compaction.nudgetrueyesWhether the nudge is given.
cache.lifetime"1h"yesThe prompt-cache lifetime, "5m" or "1h" (docs/prompt-cache.md).
cache.warm_idlefalseyesWhether an idle session keeps its prompt cache warm (docs/prompt-cache.md, "Warming while idle").
cache.warm_cap2yesHow many cache lifetimes after the last turn warming stops, an integer; less than 12 (docs/prompt-cache.md, "Warming while idle").
cache.diagnosticsfalseyesWhether 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.mdnoA key, or a list of keys, for a terminal action; [] unbinds it (docs/tui.md, "Bindings").
retry.attempts3yesRetries of a failed model call (docs/model-routing.md, "When a model call fails").
retry.initial_delay_ms2000yesThe first backoff, doubling each retry.
retry.max_delay_ms60000yesThe cap on one backoff, and on a wait a server asks for.
tools."<name>".max_result_bytesthe tool's own, or 16384yesThe tool's result cap (docs/tools.md, "Bounded results").
tools."<name>".deferredthe tool's ownyesWhether the tool is deferred (docs/tools.md, "What is deferred by default").
skills.disabled[]noNames 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.backendthe one installednoThe search backend web_search uses when more than one is installed (docs/tools.md, "Web fetch and web search").
shell.read_only."<command>".flagsnonenoAdds 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.enabledfalsenoWhether 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[]noExtra paths a confined call may write, such as ["~/.pi/agent"], as a list of strings. Person-only, like every sandbox.* key.
sandbox.deny_read[]noExtra 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"noHow 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.usdnonenoThe 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_at80yesThe percent used of a quota window at which the model gets a notice (docs/tools.md, "Provider quota").
mcp.servers."<name>"noneyes, with approvalAn MCP server ("MCP servers").
repository_extensionsnoneyes, with approvalThe 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>".enabledtruenoWhether 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_ms5000yesA process extension's startup deadline.
extensions."<name>".commands."<command>"noneyesA new name for one of the extension's commands, when two extensions clash.
extensions."<name>".tools.enabled, extensions."<name>".tools.disablednoneyesLists 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_msthe callback's ownnoOverrides the timeout of every hook and watcher the extension registers, including the entries the hooks extension registers from configuration.
hooks.order."<hook point>"nonenoExtension names in the order their hooks run at that point (docs/extensions.md, "When several hooks share a point").
providers."<name>".credentialdefault; fiber login writes the first label it storesnoThe credential label a new session uses (docs/model-routing.md, "Which credential a session uses").
providers."<name>".credentials."<label>"nonenoWhere that label's key comes from, when it is not stored in Fiber home ("Secrets").
providers.databricks.request_tagsnonenoAn 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_modelthe package's reviewer_modelnoThe 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"]noThe 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.showntruenoWhether the terminal's rail shows; ⌥R and /rail write it (docs/tui.md, "The rail").
tui.rail.width15noThe 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.width21noThe panel's share of the screen's width, in percent, kept from 30 to 60 columns; dragging its edge writes it.
tui.themenonenoThe 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.editornonenoThe 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_motionfalsenoWhether every animation takes its still form. Detection is not built yet (see #1506) (docs/tui.md, "Reduced motion").

Not built yet: see #1506.

KeyDefaultNeeds approvalWhat it sets
tui.attention.notificationtruenoWhether 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.belltruenoWhether it rings the bell where OSC 9 is not supported.
tui.attention.titletruenoWhether the terminal title shows the session's state.
tui.hovertruenoWhether hover highlights the click target under the pointer; false drops mouse mode 1003 (docs/tui.md, "Mouse and hover").
tui.inline_imagestruenoWhether images show inline where the terminal speaks kitty's graphics protocol (docs/tui.md, "Images").
tui.logo_glyph"⌇"noThe glyph before the name in the logo, "⌇" or "≈", for a font without ⌇ (docs/tui.md, "The logo").
tui.slots."<slot>"nonenoThe 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:

FieldMeaning
command, args, envthe 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
urla remote server
requiredwhether failing to start ends the session, default false
startup_timeout_msthe startup deadline, default 5000
timeout_msthe call timeout
declare_in_fullwhether its tools are declared in full rather than deferred, default false
tools.enabled, tools.disabledlists of tool names
tools."<tool>".hintsoverrides 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:

LayerFile
globalconfig/<extension>.json in Fiber home
repository.fiber/config/<extension>.json
per projectprojects/<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.

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:

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"):

A problem in a file is reported by file and key:

When Fiber writes

Fiber writes configuration in these places:

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 }
    }
  ]
}

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:

SourceFiber destination
Claude Code skills/*/SKILL.mdA 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/*.mdA 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.mdCLAUDE.md at the top of Fiber home
Claude Code settings.json mcpServersUser-scope MCP servers in the global layer, with the field map docs/mcp.md ("Configuration") lists
Codex skills/*/SKILL.mdA personal skill, as above
Codex prompts/*.mdA 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.mdAGENTS.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 ", whatever other reason would also leave it behind. Here "already read" means that discovery would load it.

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.