Skip to main content

Troubleshooting & FAQ

Common problems​

No provider configured / "Add a provider to get started"​

The Harness needs at least one AI provider before it can do anything. Go to Settings → Integrations → Providers → Add provider and follow the Quickstart steps. Each provider has its own setup page under Providers.

"Provider not reachable" after saving a key​

Hit Test in the provider editor — it pings the provider with a minimal request and surfaces the actual error message. Common causes:

  • Typo'd key. Re-paste from the provider console. Anthropic keys start with sk-ant-…; OpenAI keys start with sk-….
  • Wrong region or endpoint. Bedrock is region-specific — make sure the region in Kenaz matches where you requested model access. Azure OpenAI requires your resource hostname, not a generic endpoint.
  • No billing / quota. Most providers require a funded account before inference works. Check your provider console for billing status.
  • Network. Some corporate networks block direct API calls. Try a different network or configure your organization's proxy in Settings → App → General → HTTP Proxy.

A model I expect isn't showing in the picker​

  • Anthropic / OpenAI — Kenaz reads the model list from the API on save. If a model launched recently, save the provider again to refresh the list.
  • Bedrock — you need model access granted in the AWS Bedrock console first, in the correct region. Kenaz only shows what your account has access to.
  • Azure OpenAI — Kenaz can't discover Azure deployments automatically. Add the model IDs your deployments serve in the provider editor.
  • Ollama — the model must have been ollama pulled. Run ollama list in a terminal to see what's available.

macOS won't open the app​

Current builds (May 2026 and later) are notarized — Gatekeeper opens them without ceremony. If you're on an older build:

xattr -d com.apple.quarantine /Applications/Kenaz.app

Run this once from Terminal, then double-click normally.

A permission prompt keeps appearing for the same path​

You can pre-grant the category or path so you stop seeing it. Go to Settings → Security → Permissions, find the relevant category (Filesystem read, Filesystem write, Shell, Network), and set it to Always allowed → within these paths scoped to your project root. See Permissions for the full options and the suggested starter setup.

note

Shell and Network are pre-granted at your own risk — the suggested setup keeps Shell at "Ask each time."

An MCP server won't connect​

Walk through the checklist:

  1. Is the runtime on PATH? Most servers use npx (Node.js 20+) or uvx (uv). Run the command manually in a terminal to confirm it works.
  2. Did the server time out? Kenaz waits 10 seconds for the initialize handshake. First-run npm caching or a Docker pull can exceed this. Try again after the download finishes.
  3. Are the env vars right? If the server needs an API key (GitHub, Slack, Notion, …), check that you typed the env var correctly in the MCP recipe's environment block.
  4. Check the server logs. Open Tools → (server name) → Logs — this shows the full subprocess stderr, which usually has the exact error.
  5. "Tool list empty"? Some servers skip registering tools when a required env var is missing. Set the var and reconnect.

See Installing MCP servers for the full troubleshooting reference.

The conversation got truncated / context limit hit​

Long conversations compact automatically. If you're hitting the limit before compaction kicks in, or want to control when it fires, adjust Settings → Authoring → Compaction. You can also trigger compaction manually from the Memory view → Compact now. See Memory & compaction.

Where do log files live?​

The Harness keeps everything — including logs — under one directory, the same on every platform:

~/.kenaz/harness/<env>/logs/

<env> is prod unless you've set KENAZ_HARNESS_ENV (dev, stage, or local), so for most people the logs are in ~/.kenaz/harness/prod/logs/. Attach the latest log when filing a bug report.

FAQ​

Do I need Kenaz Fleet to use the Harness?​

No. The Harness is fully functional on its own — no sign-in required, no account needed beyond your AI provider. Fleet is an optional team control plane. If you're curious what it adds, see Connecting to Fleet.

Is my data sent anywhere?​

The Harness is local-first. Your prompts and responses go only to the AI provider you configured — directly, over TLS. Kenaz has no relay server. Your API keys live in your OS keychain and are never uploaded.

If you sign in to Fleet, what Fleet can and cannot see is documented on Connecting to Fleet. Telemetry is off by default and requires a separate opt-in step.

Can I use the Harness without the Workbench?​

Yes. The Harness runs as a standalone desktop app — download it from docs.kameas.ai/download and run it natively. The Kenaz Workbench wraps it in a sandboxed Linux environment and bundles a code editor and notebook alongside it, but the Harness itself doesn't require it.

Which AI providers are supported?​

Anthropic, OpenAI, OpenRouter, AWS Bedrock, Azure OpenAI, Google Gemini, Ollama, and any OpenAI-compatible endpoint (vLLM, LiteLLM, enterprise gateways). See the Providers overview for setup guides.

Where are my API keys stored?​

In your operating system's native credential store — Keychain Access on macOS, Credential Manager on Windows, Secret Service on Linux. Kenaz writes the plaintext once on save, then zeroes it from memory. The on-disk config files contain only a reference to the keychain entry, not the key itself. See Secret store for details and instructions for inspecting or clearing entries.

Where does Kenaz store my conversations and files?​

Everything lives locally under:

~/.kenaz/harness/<env>/

where <env> is prod for standard installs. Sessions, artifacts, memory chunks, and the audit log are all in this directory. Nothing is synced to a remote server unless you explicitly configure Fleet sync.

Can I use more than one AI provider at the same time?​

Yes. Add as many providers as you want — Kenaz stores each one independently. Switch between them per-session using the model picker in the chat header. You can also route specific tasks (compaction, embeddings) to different providers via Settings → Integrations → LLM Routing.

How do I move Kenaz to a new machine?​

Copy your config files from ~/.kenaz/harness/<env>/ (they contain no secrets, just structure and keychain locators). On the new machine, drop them into the same path and open Kenaz — each provider and MCP server will show as "missing credential." Re-paste your API keys. The OS keychain is not automatically synced or backed up; that's intentional. See Secret store → Backups & migration.

Something isn't documented here — where do I ask?​

File an issue on github.com/kameas-ai/kenaz-harness. For security questions, email security@kameas.ai.