Skip to content
← Back to Home

Koko (AI Assistant)

Production setup, safe mode behavior, and operational controls.

Last updated: January 7, 2026

What users see (by design)

Koko is built to be production-safe:

  • If no AI provider is configured, Koko stays available in safe fallback mode (fast, deterministic navigation help).
  • If an upstream AI provider fails, Koko automatically degrades to safe mode so the UI never gets blocked.
  • Provider/config diagnostics are intentionally hidden from end users unless you explicitly enable operator diagnostics.

Step-by-step: enable full AI responses

  1. Pick a provider (OpenAI, Anthropic, Gemini, xAI, DeepSeek, or Ollama).
  2. Enable the feature flag:
    • Set NEXT_PUBLIC_FEATURE_AI_AGENTS=true.
  3. Configure at least one provider key:
    • OpenAI: OPENAI_API_KEY (optional OPENAI_MODEL)
    • Anthropic: ANTHROPIC_API_KEY (optional ANTHROPIC_MODEL)
    • Gemini: GEMINI_API_KEY (optional GEMINI_MODEL)
    • xAI: XAI_API_KEY (optional XAI_MODEL)
    • DeepSeek: DEEPSEEK_API_KEY (optional DEEPSEEK_MODEL)
    • Ollama: OLLAMA_BASE_URL (optional OLLAMA_MODEL)
  4. Choose routing mode (optional):
    • KOKO_CHAT_MODE=fallback (default): try providers in order until one succeeds.
    • KOKO_CHAT_MODE=single: use the first configured provider (or a forced provider).
    • KOKO_CHAT_MODE=ensemble: query multiple providers and synthesize (higher cost).
    • Provider order: KOKO_PROVIDER_ORDER=openai,anthropic,google,xai,deepseek,ollama
  5. Decide on anonymous access:
    • By default, when a provider is configured Koko requires auth (cost/abuse control).
    • Set KOKO_ALLOW_ANON=true only if you intentionally want anonymous AI access.

Operator diagnostics (optional)

For troubleshooting only, you can enable operator diagnostics (do not enable by default in production):

  • KOKO_EXPOSE_DIAGNOSTICS=true
  • Optionally enable agent tools (web fetch) with KOKO_AGENT_TOOLS=true.

Where Koko lives

  • Chat endpoint: /api/agents/chat
  • In-app experience: /app/koko
  • Site widget: the floating Koko button (where enabled)

Related

Need help? Visit Support or Contact.

Koko (AI Assistant) | Howfar Docs — HOWFAR