Configuration and troubleshooting

Files and environment

Fetchira uses $FETCHIRA_HOME, otherwise $XDG_CONFIG_HOME/fetchira, otherwise ~/.config/fetchira. The directory holds fetchira.toml, usage.db, captured sessions, image outputs and update state. A relative db_path is resolved inside that directory.

Environment variables already set in the process take precedence over .env. Fetchira loads its home .env first, then fills unset variables from a .env found from the current working directory. Use absolute paths when setting FETCHIRA_HOME or XDG_CONFIG_HOME.

A minimal configuration using an environment-backed key:

[[account]]
provider = "serper"
label = "serper-1"
api_key = "env:SERPER_API_KEY"

Keep SERPER_API_KEY in the process environment or the Fetchira home .env. See fetchira.toml.example and .env.example for the supported fields; enable only the accounts you use. Local config can contain plaintext API keys. Hosted mode encrypts stored provider credentials with its persistent master key. Treat the data directory and backups as private: debug logs can contain queries and results.

Accounts and routing

fetchira providers
fetchira add serper --key 'KEY' --label serper-work
fetchira add gemini_web
fetchira list
fetchira usage serper

list (alias accounts) shows account readiness. usage shows the compact model/quota snapshot; usage PROVIDER adds supported operations and options. Web sessions expire: fetchira login LABEL captures a fresh session for an existing account. For a session file, use fetchira session LABEL --file session.json. Remove an account with fetchira remove LABEL only when its saved configuration and session are no longer needed.

The router tries configured providers in priority order and chooses an account by remaining allowance. Unsupported providers are skipped. Change the order with:

fetchira priority
fetchira priority search serper,tavily,exa
fetchira priority deep_research gemini_web,parallel
fetchira priority search reset

Capabilities with configurable priority are search, read, deep_research, and image. Unlisted providers follow the listed ones in built-in order, which ranks providers by public search, research and scraping benchmarks; topic=academic adds OpenAlex and topic=news adds GDELT. Restart running MCP/server processes after changing configuration through the CLI. Dashboard changes reload its router.

A --provider argument restricts the request to that backend; it does not fall back to a different provider. A returned session also pins the account, so a follow-up cannot silently continue another conversation. Provider plans, balances and limits are authoritative. Where a provider reports its real remaining balance, Fetchira caches it and routes on it, counting its own calls down between reads; built-in quotas are only estimates for providers that report nothing. An explicit quota (or, for deep research, dr_quota) caps a live balance, so it can hold back a paid one; set reset/dr_reset to match your plan. A forced provider still obeys these limits.

Dollar balances are real balances; the displayed ≈ call counts are estimates that vary by operation and plan. Steel requests use its proxy: the Launch plan requires a paid $10 deposit to enable it, even with free credits (Steel pricing).

Temporary rate limits cause failover and a retry delay, not monthly quota exhaustion. Confirmed insufficient-credit responses trigger a separate quota check after a one-minute cooldown. A fresh positive balance restores routing after a top-up; providers without a readable balance get a single probe per cooldown. Configured local ceilings still apply. If no account can serve the request, Fetchira returns an error with the available provider information.

Proxies and logging

fetchira proxy LABEL http://user:password@proxy.example:8080
fetchira proxy LABEL pool
fetchira proxy LABEL direct

pool needs [proxy_pool] in the config; see the example file. Accounts keep a stable pool assignment. Provider availability can depend on the account’s region and proxy.

Logs go to stderr; set RUST_LOG=fetchira=debug for diagnostics. The dashboard Debug tab uses a bounded request/response log (24-hour retention by default). Disable capture with:

[debug_log]
enabled = false

Troubleshooting

Updates and removal

Run fetchira update (alias fetchira upgrade) or click Update in the dashboard. The updater uses Homebrew for a Homebrew installation and release archives for a standalone binary. It reports progress or an actionable error in place. Hosted updates have a separate backup and rollback procedure.

Accounts, sessions, usage and settings stay in the existing data directory. The new process migrates the database and refreshes existing agent skills automatically, including when it starts through MCP or restarts the dashboard. Replaced skill files are backed up, stale Homebrew launchers are repaired, and your CLI/MCP choices and other server settings stay unchanged. No separate migration command is needed. Already-running agents load the new executable when restarted; active work is not terminated. Use Setup & agents to deliberately change integrations.

To stop using Fetchira, remove its MCP entry from the clients you configured, remove the installed Fetchira skill folder, and uninstall the binary using its installation method. Keep the data directory until you have saved any sessions, images or backups you need.