Configuration & Environment Variables

#Precedence

Peekaboo resolves settings in this order (highest → lowest):

1. Command-line arguments
2. Environment variables (never copied into files)
3. Credentials file (~/.peekaboo/credentials: API keys or OAuth tokens)
4. Configuration file (~/.peekaboo/config.json)
5. Built-in defaults

#Available Options

#GameBridge manifest budget

Set PEEKABOO_GAMEBRIDGE_MAX_MANIFEST_BYTES=1048576 to limit Firestaff manifests to 1 MiB. The limit is inclusive and applies before loading or decoding the file, including growth after opening. An oversized or invalid manifest is ignored and normal Accessibility detection can proceed. Firestaff must publish immutable frames by atomic rename; detected size or timestamp changes are refused. Unset or empty keeps the existing unlimited-size default.

The environment belongs to the process performing detection. Use --no-remote for a standalone CLI invocation, or set the variable when starting the Bridge host. A CLI environment override is not forwarded to an already-running host.

#API Key Storage

1. Environment variables – supported for existing automation, but keep values out of command arguments.
2. Credentials file – peekaboo config credential set OPENAI_API_KEY prompts without echo and stores the value in ~/.peekaboo/credentials (chmod 600). Scripts should pipe one line with --credential-stdin --no-input or use an owner-only --credential-file.
3. Config file – avoid storing keys here unless absolutely necessary. OAuth tokens are never written to config.json.

The macOS app and CLI use this same file as the ongoing authority for saved API keys, including when PEEKABOO_CONFIG_DIR changes the configuration root. Settings reloads it when the provider pane opens; use Reload keys after a CLI rotation while the pane stays open. There is no credential-path Keychain storage or importer and no password or biometric prompt for app credential persistence.

The directory is owner-only (0700) and the file is owner-readable/writable (0600), including temporary files before publication. This deliberately accepts file-level protection to avoid authentication prompts: the keys are plaintext, and other processes running as your user can read them. Do not share this file. Sequential app/CLI edits preserve unrelated keys and OAuth entries; concurrent edits by separate processes, including Tachikoma, are not serialized.

Old app preferences are never imported automatically, even if the file is missing, empty, or deleted. Import saved app keys explicitly recovers legacy-only keys; existing file values win, including CLI changes made since the pane opened. Successful saves, clears, and imports retire only the corresponding legacy entries. Failed imports leave those entries available for another explicit attempt. Showing a credential field or receiving an unchanged binding value never saves the draft or retires legacy keys. App edits and legacy imports trim surrounding whitespace and newlines; interior newlines and NUL remain invalid. Whitespace-only app input clears a populated field but leaves an already empty field unchanged; blank legacy entries remain stored without offering recovery.

A failed save keeps the draft marked Not saved and leaves the previous effective credential unchanged. A failed clear does not claim deletion or environment fallback. Retry is explicit after failure, and reload preserves failed drafts. A durability warning means publication already happened; reload to check instead of blindly repeating the write. Environment overrides, config fallbacks, OAuth sessions, and the international MiniMax fallback for MiniMax China remain runtime-only and are not implicitly saved.

#Provider Variables

• PEEKABOO_AI_PROVIDERS: provider/model CSV. Example: openai/gpt-5.6,anthropic/claude-opus-5,grok/grok-4.3,ollama/llava:latest.
• OPENAI_API_KEY, ANTHROPIC_API_KEY, GROK_API_KEY | X_AI_API_KEY | XAI_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, MINIMAX_CN_API_KEY, MOONSHOT_API_KEY | KIMI_API_KEY: required for their respective providers when using API keys.
• Ollama native endpoint precedence: PEEKABOO_OLLAMA_BASE_URL > OLLAMA_BASE_URL >

aiProviders.ollamaBaseUrl > http://localhost:11434. Set the server base without /api/chat or /v1; see the Ollama provider guide.

#Defaults & Paths

• PEEKABOO_DEFAULT_SAVE_PATH: screenshot destination (created automatically).
• PEEKABOO_CLI_PATH: point Peekaboo at a debug build (.build/debug/peekaboo) without copying binaries around.

#Agent generation settings

The macOS Settings UI and peekaboo agent share agent.temperature and agent.maxTokens through ~/.peekaboo/config.json:

{
  "agent": {
    "defaultModel": "anthropic/claude-fable-5",
    "temperature": 0.7,
    "maxTokens": 128000
  }
}

maxTokens is an upper request, not a promise: Peekaboo clamps it to the selected model's advertised output limit. Fable 5 supports up to 128K output and a 1M context window. Anthropic-compatible custom providers inherit known Fable limits from the model ID, while custom model entries can advertise their own maxTokens.

Temperature is clamped to 0...1 for Anthropic-compatible models and 0...2 elsewhere. Peekaboo omits it entirely for models that reject sampling controls, including GPT-5-compatible endpoints and current Anthropic adaptive-thinking models.

#UI Input Strategy

Input strategy controls whether UI interactions use accessibility action invocation or synthetic input. The built-in policy keeps the global default, legacy SDK typing, and ordinary hotkeys at synthFirst, selects actionFirst for click, scroll, background typing, and focused background Cmd+A, and exposes setValue/performAction as action-only operations. An explicit global strategy overrides the built-in click/scroll/type/select-all preferences unless a more specific configured override wins.

The Cmd+A built-in preference is limited to focused text selection: unsupported selection falls directly back to targeted events, never to a new process-menu action. Explicit global, hotkey, and per-app selections remain authoritative; synthetic choices skip AX selection entirely. The resolved policy records this separately as backgroundSelectAllDefault, not in the typing preference or generic hotkey override. Concrete SDK policies and older resolved JSON without the new preference retain their declared strategy. Action-based selection and menus do not implement key holding; choose a synthetic strategy when a physical hold is required.

Precedence is --input-strategy CLI flag, then environment, then config file, then built-in default. The CLI flag forces local execution because the current bridge protocol does not forward per-call strategy overrides.

Valid values:

• actionFirst: try accessibility action invocation, fall back to synthetic input when unsupported.
• synthFirst: use synthetic input first.
• actionOnly: use action invocation only.
• synthOnly: use synthetic input only.

For background typing, actionOnly forbids keyboard events and both synthetic strategies skip AX value/selection edits. actionFirst falls back per unsupported unit, never after an accepted or uncertain write. Local native text edits can work with Accessibility alone; local Event Synthesizing permission is checked only before needed events. Bridge-hosted targeted typing still requires Post Event permission at admission, including native edits.

The legacy SDK type(text:target:clearExisting:typingDelay:snapshotId:) keeps its shipped synthFirst default, including named-target focus and per-character keyboard delivery. Default calls do not probe AX replacement eligibility. Explicit global, type, and per-app strategies retain their existing precedence on both SDK and background paths. Direct AX replacement under an explicitly selected action strategy requires clearExisting: true, zero typingDelay, and a fresh check proving the named target is the current keyboard receiver; cached focus or a frontmost app/window alone is insufficient. A requested positive delay or a successfully read focus mismatch makes the action route unsupported: actionFirst uses the existing synthetic focus/clear/type path, while actionOnly refuses without dispatch. An unreadable or uncertain focus check instead stops before input under either action strategy, without fallback. Permission failures, cannotComplete, missing or malformed focus values, and timeouts are errors, not evidence that the target is unfocused. Explicit synthFirst and synthOnly retain their existing synthetic behavior. These SDK eligibility checks do not change the global/per-app strategy precedence or the CLI foreground action-array path.

Zero-delay SDK replacement also requires bounded, same-process ancestry proving a native rather than web receiver. Known AXWebArea descendants take the existing keyboard route under actionFirst and refuse under actionOnly, before any AX value write; unprovable ancestry instead stops without input or fallback. This avoids treating AX value readback as proof of page input-event behavior and leaves explicit set-value semantics unchanged.

Config example:

{
  "input": {
    "defaultStrategy": "synthFirst",
    "click": "actionFirst",
    "scroll": "actionFirst",
    "type": "actionFirst",
    "hotkey": "synthFirst",
    "setValue": "actionOnly",
    "performAction": "actionOnly",
    "perApp": {
      "com.googlecode.iterm2": {
        "hotkey": "synthOnly"
      }
    }
  }
}

Environment variables:

• PEEKABOO_INPUT_STRATEGY
• PEEKABOO_CLICK_INPUT_STRATEGY
• PEEKABOO_SCROLL_INPUT_STRATEGY
• PEEKABOO_TYPE_INPUT_STRATEGY
• PEEKABOO_HOTKEY_INPUT_STRATEGY
• PEEKABOO_SET_VALUE_INPUT_STRATEGY
• PEEKABOO_PERFORM_ACTION_INPUT_STRATEGY

CLI override:

peekaboo click --on "$ELEMENT_ID" --input-strategy actionFirst

When an input-policy override selects caller-local execution, combining that policy with --bridge-socket or PEEKABOO_BRIDGE_SOCKET fails with BRIDGE_UNAVAILABLE before constructing local services or sending input; Peekaboo does not silently ignore the selected host. Remove the CLI, environment, and config input-policy overrides to use that host, or pass --no-remote to deliberately run locally. Without an explicit socket, policy-local routing remains available. Concrete snapshot references still resolve their unique producer first; --no-remote restricts that check to the caller.

#Logging & Troubleshooting

• PEEKABOO_LOG_LEVEL=debug (or trace) surfaces verbose input-path logs.
• PEEKABOO_LOG_FILE=/tmp/peekaboo.log persists logs for sharing.
• Tool filters: env PEEKABOO_ALLOW_TOOLS replaces config tools.allow; env PEEKABOO_DISABLE_TOOLS is additive with tools.deny. Deny wins if a tool appears in both. See docs/security.md for examples and risk guidance.

#Setting Variables

# Single command
PEEKABOO_AI_PROVIDERS="ollama/llava:latest" peekaboo see --analyze "Describe this UI" --path img.png

# Session exports
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export X_AI_API_KEY="xai-..."

# Shell profile
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

When in doubt, run peekaboo config show --effective to see the merged view from every layer.