> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ & Troubleshooting

> Frequently asked questions and solutions to common issues with Mibyan

<Info>
  Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see [Install and update](/products/desktop-guide/install-and-update).
</Info>

Python dependency commands on this page use a
[PM-prepared source checkout](/desktop/reference/package-management#developer-workflow).
After a dependency change, reactivate the checkout and restart Mibyan.

Quick answers and fixes for the most common questions and issues.

***

## Frequently Asked Questions

### What LLM providers work with Mibyan?

Mibyan works with any OpenAI-compatible API. Supported providers include:

* **[OpenRouter](https://openrouter.ai/)** — access hundreds of models through one API key (recommended for flexibility)
* **Nous Portal** — Nous Research's subscription gateway — 300+ models plus web/image/TTS/browser through one OAuth login (recommended for newcomers)
* **OpenAI** — GPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o, etc.
* **Anthropic** — Claude models (direct API, OAuth via `mibyan auth add anthropic`, OpenRouter, or any compatible proxy)
* **Google** — Gemini models (direct API via `gemini` provider, OpenRouter, or compatible proxy)
* **z.ai / ZhipuAI** — GLM models
* **Kimi / Moonshot AI** — Kimi models
* **MiniMax** — global and China endpoints
* **Local models** — via [Ollama](https://ollama.com/), [vLLM](https://docs.vllm.ai/), [llama.cpp](https://github.com/ggerganov/llama.cpp), [SGLang](https://github.com/sgl-project/sglang), or any OpenAI-compatible server

Set your provider with `mibyan model` or by editing `~/.mibyan/.env`. See the [Environment Variables](/desktop/reference/environment-variables) reference for all provider keys.

### Does it work on Windows/Android/my platform??

See **[Platform Support](/desktop/getting-started/platform-support)** for the full platform availability matrix.

### I run Mibyan in WSL2. What's the best way to control my normal Windows Chrome?

Prefer an MCP bridge over `/browser connect`.

Recommended pattern:

* run Mibyan inside WSL2
* keep using your normal signed-in Chrome on Windows
* add `chrome-devtools-mcp` as an MCP server through `cmd.exe` or `powershell.exe`
* let Mibyan use the resulting MCP browser tools

This is more reliable than trying to force Mibyan core browser transport to attach directly across the WSL2/Windows boundary.

See:

* [Use MCP with Mibyan](/desktop/guides/use-mcp-with-mibyan#wsl2-bridge-mibyan-in-wsl-to-windows-chrome)
* [Browser Automation](/desktop/user-guide/features/browser#wsl2--windows-chrome-prefer-mcp-over-browser-connect)

### Is my data sent anywhere?

API calls go **only to the LLM provider you configure** (e.g., OpenRouter, your local Ollama instance). Mibyan does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.mibyan/`.

### Can I use it offline / with local models?

Yes. Run `mibyan model`, select **Custom endpoint**, and enter your server's URL:

```bash theme={null}
mibyan model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000   ← Mibyan minimum; set this to match your server's actual context window
```

Or configure it directly in `config.yaml`:

```yaml theme={null}
model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1
```

Mibyan persists the endpoint, provider, and base URL in `config.yaml` so it survives restarts. If your local server has exactly one model loaded, `/model custom` auto-detects it. You can also set `provider: custom` in config.yaml — it's a first-class provider, not an alias for anything else.

This works with Ollama, vLLM, llama.cpp server, SGLang, LocalAI, and others. See the [Configuration guide](/desktop/user-guide/configuration) for details.

<Tip>
  **Ollama users**

  If you set a custom `num_ctx` in Ollama (e.g., `ollama run --num_ctx 64000`), make sure to set the matching context length in Mibyan — Ollama's `/api/show` reports the model's *maximum* context, not the effective `num_ctx` you configured.
</Tip>

<Tip>
  **Timeouts with local models**

  Mibyan auto-detects local endpoints and relaxes streaming timeouts (read timeout raised from 120s to 1800s, stale stream detection disabled). If you still hit timeouts on very large contexts, set `mibyan_STREAM_READ_TIMEOUT=1800` in your `.env`. See the [Local LLM guide](/desktop/guides/local-llm-on-mac#timeouts) for details.
</Tip>

### How much does it cost?

Mibyan itself is **free and open-source** (MIT license). You pay only for the LLM API usage from your chosen provider. Local models are completely free to run.

### Can multiple people use one instance?

Yes. The [messaging gateway](/desktop/user-guide/messaging/overview) lets multiple users interact with the same Mibyan instance via Telegram, Discord, Slack, WhatsApp, or Home Assistant. Access is controlled through allowlists (specific user IDs) and DM pairing (first user to message claims access).

### What's the difference between memory and skills?

* **Memory** stores **facts** — things the agent knows about you, your projects, and preferences. Memories are retrieved automatically based on relevance.
* **Skills** store **procedures** — step-by-step instructions for how to do things. Skills are recalled when the agent encounters a similar task.

Both persist across sessions. See [Memory](/desktop/user-guide/features/memory) and [Skills](/desktop/user-guide/features/skills) for details.

### Can I use it in my own Python project?

Yes. Import the `AIAgent` class and use Mibyan programmatically:

```python theme={null}
from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")
```

See the [Python Library guide](/desktop/user-guide/features/code-execution) for full API usage.

***

## Troubleshooting

### Installation Issues

#### `mibyan: command not found` after installation

**Cause:** Your shell hasn't reloaded the updated PATH.

**Solution:**

```bash theme={null}
# Reload your shell profile
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# Or start a new terminal session
```

If it still doesn't work, verify the install location:

```bash theme={null}
which mibyan
ls ~/.local/bin/mibyan
```

<Tip>
  The installer adds `~/.local/bin` to your PATH. If you use a non-standard shell config, add `export PATH="$HOME/.local/bin:$PATH"` manually.
</Tip>

#### Unsupported Python version

Current first-party installations require **Python 3.14**, not an arbitrary
newer version. The `>=3.11,<3.15` range in `pyproject.toml` allows older
installations to run the updater before switching to 3.14; it does not mean
the current runtime supports 3.11–3.13. The installer and packaged
distributions provide their pinned interpreter.

For a manual source environment, use the
[development setup](/desktop/developer-guide/contributing#development-setup).
Do not replace the interpreter inside an installed app or container.
For a managed-install error, run `mibyan doctor` and use that installation's
[update method](/desktop/getting-started/updating).

#### Terminal commands say `node: command not found` (or `nvm`, `pyenv`, `asdf`, …)

**Cause:** Mibyan builds a per-session environment snapshot by running `bash -l` once at startup. A bash login shell reads `/etc/profile`, `~/.bash_profile`, and `~/.profile`, but **does not source `~/.bashrc`** — so tools that install themselves there (`nvm`, `asdf`, `pyenv`, `cargo`, custom `PATH` exports) stay invisible to the snapshot. This most commonly happens when Mibyan runs under systemd or in a minimal shell where nothing has pre-loaded the interactive shell profile.

**Solution:** Mibyan auto-sources `~/.bashrc` by default. If that's not enough — e.g. you're a zsh user whose PATH lives in `~/.zshrc`, or you init `nvm` from a standalone file — list the extra files to source in `~/.mibyan/config.yaml`:

```yaml theme={null}
terminal:
  shell_init_files:
    - ~/.zshrc                     # zsh users: pulls zsh-managed PATH into the bash snapshot
    - ~/.nvm/nvm.sh                # direct nvm init (works regardless of shell)
    - /etc/profile.d/cargo.sh      # system-wide rc files
  # When this list is set, the default ~/.bashrc auto-source is NOT added —
  # include it explicitly if you want both:
  #   - ~/.bashrc
  #   - ~/.zshrc
```

Missing files are skipped silently. Sourcing happens in bash, so files that rely on zsh-only syntax may error — if that's a concern, source just the PATH-setting portion (e.g. nvm's `nvm.sh` directly) rather than the whole rc file.

Independently of the init files, every terminal command's `PATH` is completed with the standard system directories (`/usr/local/bin`, `/opt/homebrew/bin`, …), the Mibyan-managed runtime dirs, and `~/.local/bin` when it exists (the `pip --user` / `pipx` / `uv tool` install target) — appended after your own entries, so precedence is unchanged. This covers backends started with a thin non-interactive PATH (systemd, GUI launchers, the Desktop SSH remote backend) without any configuration.

To disable the auto-source behaviour (strict login-shell semantics only):

```yaml theme={null}
terminal:
  auto_source_bashrc: false
```

#### `uv: command not found`

**Cause:** The `uv` package manager isn't installed or not in PATH.

**Solution:**

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
```

#### Permission denied errors during install

**Cause:** Insufficient permissions to write to the install directory.

**Solution:**

<Note>
  Mibyan Desktop is installed from the Mibyan Desktop download, or launched from an existing Mibyan CLI with `mibyan desktop`. See [Install and update](/products/desktop-guide/install-and-update).
</Note>

***

### Provider & Model Issues

#### The agent says "Mibyan policy" or "Mibyan guardrails" refused my request

A model cannot reliably identify why it refused a request. If the refusal appears only in the assistant's prose, its claim that a hidden Mibyan runtime policy caused it may be a hallucinated explanation or a restriction applied by the selected model or provider.

Mibyan enforcement is explicit: a blocked tool action returns a tool error naming the denied command or path, and an approval-required action shows an approval prompt. Mibyan does not silently turn those execution controls into a general content-refusal layer. Provider-level controls can still apply when configured, such as Amazon Bedrock Guardrails.

To isolate the source:

1. Run `/status` to confirm the active model and provider.
2. Check whether the refusal includes an actual Mibyan tool error or approval prompt. If it is prose only, do not treat the model's attribution as runtime evidence.
3. Retry in a fresh session with another configured model or provider. A refusal that changes with the model is model/provider behavior, not a Mibyan execution control.
4. If an explicit tool error appears, use its exact text when reporting the problem.

See [Security](/desktop/user-guide/security) for Mibyan' documented execution controls and [Providers](/desktop/integrations/providers) for provider configuration.

#### "…refused this request because of a policy on your account"

**Meaning:** the provider rejected the request for an account-level reason that retrying cannot change — an aggregator's data/privacy settings excluded every endpoint for the model, or the model's upstream provider has blocked the account (for example `this user has been blocked for a previous policy violation`, which OpenRouter can relay inside an otherwise successful HTTP 200 stream). Mibyan sends the request once, does not retry it or rotate credentials, and moves to your fallback chain if one is configured.

**Solution:** check the account's status and data/privacy settings with the provider named in the reply, or switch to another model or provider with `/model`. `mibyan fallback add` routes future blocks to a backup automatically.

#### "Could not open a stream to `<host>` after N attempts (request X KB)"

**Meaning:** every connect attempt to that endpoint failed before a single stream event arrived, so nothing was billed; the normal retry/fallback chain still runs afterwards. The line names the host actually contacted, how many attempts were made, and the serialized request size — the three things that separate an outage from a request-size limit.

**Solution:** if the request is large (hundreds of KB — long coding sessions reach this once the context grows) and short new chats work, the endpoint or a proxy in front of it is likely rejecting bodies that size: raise its body limit, or run `/compress` to shrink the context. If the request is small, the endpoint is unreachable — check the `base_url`, then retry with `/retry`. `logs/agent.log` records the exception chain for each attempt.

#### Messaging replies: "interrupted mid-request" vs "not running or is unreachable" vs "could not reach"

Chat surfaces (Telegram, Discord, Slack, …) never show the raw transport exception; the gateway maps it to one of three short replies, and the difference tells you where to look:

| Reply | What happened | What to do |
| - | - | - |
| "The connection to the AI model service was **interrupted mid-request** — usually transient." | An established connection was cut (`Connection reset by peer`, EOF, `RemoteProtocolError`). The endpoint answered the connect, so it is running. | `/retry`. If it recurs on large requests, see the "stream" entry above. |
| "The AI model service isn't reachable right now — the configured model endpoint is **not running or is unreachable**." | Nothing accepted the connection (`Connection refused`, no route to host, DNS failure). | Start the model server / check `base_url`, then `/retry`; `mibyan doctor` on the host. |
| "Mibyan **could not reach** the AI model service (no further detail from the SDK)." | The SDK reported a generic `APIConnectionError` and kept no cause; neither of the above is certain. | `/retry`; `mibyan doctor` if it persists. The raw exception is in `mibyan logs`. |

#### `/model` only shows one provider / can't switch providers

**Cause:** `/model` (inside a chat session) can only switch between providers you've **already configured**. If you've only set up OpenRouter, that's all `/model` will show.

**Solution:** Exit your session and use `mibyan model` from your terminal to add new providers:

```bash theme={null}
# Exit the Mibyan chat session first (Ctrl+C or /quit)

# Run the full provider setup wizard
mibyan model

# This lets you: add providers, run OAuth, enter API keys, configure endpoints
```

After adding a new provider via `mibyan model`, start a new chat session — `/model` will now show all your configured providers.

<Tip>
  **Quick reference**

  | Want to... | Use |
  | - | - |
  | Add a new provider | `mibyan model` (from terminal) |
  | Enter/change API keys | `mibyan model` (from terminal) |
  | Switch model mid-session | `/model <name>` (inside session) |
  | Switch to different configured provider | `/model provider:model` (inside session) |
</Tip>

#### API key not working

**Cause:** Key is missing, expired, incorrectly set, or for the wrong provider.

**Solution:**

```bash theme={null}
# Check your configuration
mibyan config show

# Re-configure your provider
mibyan model

# Or set directly
mibyan config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
```

<Warning>
  Make sure the key matches the provider. An OpenAI key won't work with OpenRouter and vice versa. Check `~/.mibyan/.env` for conflicting entries.
</Warning>

#### Model not available / model not found

**Cause:** The model identifier is incorrect or not available on your provider.

**Solution:**

```bash theme={null}
# List available models for your provider
mibyan model

# Set a valid model
mibyan config set model.default anthropic/claude-opus-4.7

# Or specify per-session
mibyan chat --model openrouter/meta-llama/llama-3.1-70b-instruct
```

#### Rate limiting (429 errors)

**Cause:** You've exceeded your provider's rate limits.

**Solution:** Wait a moment and retry. For sustained usage, consider:

* Upgrading your provider plan
* Switching to a different model or provider
* Using `mibyan chat --provider <alternative>` to route to a different backend

#### Context length exceeded

**Cause:** The conversation has grown too long for the model's context window, or Mibyan detected the wrong context length for your model.

**Solution:**

```bash theme={null}
# Compress the current session
/compress

# Or start a fresh session
mibyan chat

# Use a model with a larger context window
mibyan chat --model openrouter/google/gemini-3-flash-preview
```

If this happens on the first long conversation, Mibyan may have the wrong context length for your model. Check what it detected:

Look at the CLI startup line — it shows the detected context length (e.g., `📊 Context limit: 128000 tokens`). You can also check with `/usage` during a session.

**Local servers (llama.cpp, Ollama) that go silent instead of erroring:** when a provider rejects a request as too large, Mibyan compacts the conversation and rebuilds the request. Mibyan re-measures the *complete* rebuilt request (system prompt + tool schemas + messages) before retrying, and runs further bounded compaction passes if it is still over the threshold. If the request still cannot fit, the turn ends with `Context length exceeded: compression could not reduce the rebuilt request below the safe threshold` rather than sending an oversized request that llama.cpp would silently truncate (`stop processing: n_tokens = 65535, truncated = 1` in the server log). If you hit that message, the fix is almost always the configured `context_length` above: make it match the server's actual `-c` / `--ctx-size`.

**"The model server rejected this request as too large, but this conversation is only about N tokens…":** a local server (localhost, LAN, Tailscale) said "context exceeded" without quoting any measurement, while Mibyan's own estimate of the request is far below the window it knows for the model — so it does **not** compress or blame the conversation, and the turn stays retryable. On single-slot local servers (LM Studio, Ollama) this is almost always another request holding the server's context at that moment — typically a background memory review from an earlier session (`thread=bg-review` in `logs/agent.log`). Wait a moment and `/retry`. If it recurs with no other Mibyan process running, the server is loading the model with a smaller window than Mibyan assumes: raise the server's context setting or lower `model.context_length` to match it. Hosted providers never get this message: they have no shared slot to wait out, so the same rejection there means the route's real window is smaller than Mibyan assumes, and Mibyan compresses and retries instead.

To fix context detection, set it explicitly:

```yaml theme={null}
# In ~/.mibyan/config.yaml
model:
  default: your-model-name
  context_length: 131072  # your model's actual context window
```

Or for custom endpoints, add it per-model on the provider entry:

```yaml theme={null}
providers:
  my-server:
    api: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 64000
```

(Older configs use the legacy `custom_providers:` list — still supported and auto-migrated to `providers:`.)

See [Context Length Detection](/desktop/integrations/providers#context-length-detection) for how auto-detection works and all override options.

***

### Terminal Issues

#### Command blocked as dangerous

**Cause:** Mibyan detected a potentially destructive command (e.g., `rm -rf`, `DROP TABLE`). This is a safety feature.

**Solution:** When prompted, review the command and type `y` to approve it. You can also:

* Ask the agent to use a safer alternative
* See the full list of dangerous patterns in the [Security docs](/desktop/user-guide/security)

<Tip>
  This is working as intended — Mibyan never silently runs destructive commands. The approval prompt shows you exactly what will execute.
</Tip>

#### `sudo` not working via messaging gateway

**Cause:** The messaging gateway runs without an interactive terminal, so `sudo` cannot prompt for a password.

**Solution:**

* Avoid `sudo` in messaging — ask the agent to find alternatives
* If you must use `sudo`, configure passwordless sudo for specific commands in `/etc/sudoers`
* Or switch to the terminal interface for administrative tasks: `mibyan chat`

#### Docker backend not connecting

**Cause:** Docker daemon isn't running or the user lacks permissions.

**Solution:**

```bash theme={null}
# Check Docker is running
docker info

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker run hello-world
```

***

### Messaging Issues

#### Bot not responding to messages

**Cause:** The bot isn't running, isn't authorized, or your user isn't in the allowlist.

**Solution:**

```bash theme={null}
# Check if the gateway is running
mibyan gateway status

# Start the gateway
mibyan gateway start

# Check logs for errors
cat ~/.mibyan/logs/gateway.log | tail -50
```

#### Messages not delivering

**Cause:** Network issues, bot token expired, or platform webhook misconfiguration.

**Solution:**

* Verify your bot token is valid with `mibyan gateway setup`
* Check gateway logs: `cat ~/.mibyan/logs/gateway.log | tail -50`
* For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible

#### Allowlist confusion — who can talk to the bot?

**Cause:** Authorization mode determines who gets access.

**Solution:**

| Mode | How it works |
| - | - |
| **Allowlist** | Only user IDs listed in config can interact |
| **DM pairing** | First user to message in DM claims exclusive access |
| **Open** | Anyone can interact (not recommended for production) |

Configure in `~/.mibyan/config.yaml` under your gateway's settings. See the [Messaging docs](/desktop/user-guide/messaging/overview).

#### Gateway won't start

**Cause:** Missing dependencies, port conflicts, or misconfigured tokens.

**Solution:**

```bash theme={null}
# Install core messaging gateway dependencies
cd ~/.mibyan/mibyan-agent && python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"  # Telegram, Discord, Slack, and shared gateway deps

# Check for port conflicts
lsof -i :8080

# Verify configuration
mibyan config show
```

#### WSL: Gateway keeps disconnecting or `mibyan gateway start` fails

**Cause:** WSL's systemd support is unreliable. Many WSL2 installations don't have systemd enabled, and even when enabled, services may not survive WSL restarts or Windows idle shutdowns.

**Solution:** Use foreground mode instead of the systemd service:

```bash theme={null}
# Option 1: Direct foreground (simplest)
mibyan gateway run

# Option 2: Persistent via tmux (survives terminal close)
tmux new -s mibyan 'mibyan gateway run'
# Reattach later: tmux attach -t mibyan

# Option 3: Background via nohup
nohup mibyan gateway run > ~/.mibyan/logs/gateway.log 2>&1 &
```

If you want to try systemd anyway, make sure it's enabled:

1. Open `/etc/wsl.conf` (create it if it doesn't exist)
2. Add:
   ```ini theme={null}
   [boot]
   systemd=true
   ```
3. From PowerShell: `wsl --shutdown`
4. Reopen your WSL terminal
5. Verify: `systemctl is-system-running` should say "running" or "degraded"

<Tip>
  **Auto-start on Windows boot**

  For reliable auto-start, use Windows Task Scheduler to launch WSL + the gateway on login:

  1. Create a task that runs `wsl -d Ubuntu -- bash -lc 'mibyan gateway run'`
  2. Set it to trigger on user logon
</Tip>

#### macOS: Node.js / ffmpeg / other tools not found by gateway

**Cause:** launchd services inherit a minimal PATH (`/usr/bin:/bin:/usr/sbin:/sbin`) that doesn't include Homebrew, nvm, cargo, or other user-installed tool directories. This commonly breaks the WhatsApp bridge (`node not found`) or voice transcription (`ffmpeg not found`).

**Solution:** The gateway captures your shell PATH when you run `mibyan gateway install`. If you installed tools after setting up the gateway, re-run the install to capture the updated PATH:

```bash theme={null}
mibyan gateway install    # Re-snapshots your current PATH
mibyan gateway start      # Detects the updated plist and reloads
```

You can verify the plist has the correct PATH:

```bash theme={null}
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.mibyan.gateway.plist
```

***

### Performance Issues

#### Slow responses

**Cause:** Large model, distant API server, or heavy system prompt with many tools.

**Solution:**

* Try a faster/smaller model: `mibyan chat --model openrouter/meta-llama/llama-3.1-8b-instruct`
* Reduce active toolsets: `mibyan chat -t "terminal"`
* Check your network latency to the provider
* For local models, ensure you have enough GPU VRAM

#### High token usage

**Cause:** Long conversations, verbose system prompts, or many tool calls accumulating context.

**Solution:**

```bash theme={null}
# See exactly what the fixed prompt costs — breakdown by block
# (system prompt, skills index, memory, tool schemas). Runs offline.
mibyan prompt-size

# Compress the conversation to reduce tokens
/compress

# Check session token usage
/usage
```

If the baseline looks high before you've typed anything, that's the fixed prompt budget — the system prompt plus tool schemas sent on every call. Run [`mibyan prompt-size`](/desktop/reference/cli-commands#mibyan-prompt-size) to measure it, then trim: disable toolsets you don't use (`mibyan tools`) and uninstall or disable skills you don't need (`mibyan skills`).

<Tip>
  Use `/compress` regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context.
</Tip>

#### Session getting too long

**Cause:** Extended conversations accumulate messages and tool outputs, approaching context limits.

**Solution:**

```bash theme={null}
# Compress current session (preserves key context)
/compress

# Start a new session with a reference to the old one
mibyan chat

# Resume a specific session later if needed
mibyan chat --continue
```

***

### MCP Issues

#### MCP server not connecting

**Cause:** Server binary not found, wrong command path, or missing runtime.

**Solution:**

```bash theme={null}
# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.mibyan/mibyan-agent && python -c "import pm; pm.sync_venv(['mcp'], explicit=True)"

# For npm-based servers, ensure Node.js is available
node --version
npx --version

# Test the server manually
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
```

Verify your `~/.mibyan/config.yaml` MCP configuration:

```yaml theme={null}
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
```

#### Tools not showing up from MCP server

**Cause:** Server started but tool discovery failed, tools were filtered out by config, or the server does not support the MCP capability you expected.

**Solution:**

* Check gateway/agent logs for MCP connection errors
* Ensure the server responds to the `tools/list` RPC method
* Review any `tools.include`, `tools.exclude`, `tools.resources`, `tools.prompts`, or `enabled` settings under that server
* Remember that resource/prompt utility tools are only registered when the session actually supports those capabilities
* Use `/reload-mcp` after changing config

```bash theme={null}
# Verify MCP servers are configured
mibyan config show | grep -A 12 mcp_servers

# Restart Mibyan or reload MCP after config changes
mibyan chat
```

See also:

* [MCP (Model Context Protocol)](/desktop/user-guide/features/mcp)
* [Use MCP with Mibyan](/desktop/guides/use-mcp-with-mibyan)
* [MCP Config Reference](/desktop/reference/mcp-config-reference)

#### MCP timeout errors

**Cause:** The MCP server is taking too long to respond, or it crashed during execution.

**Solution:**

* Increase the timeout in your MCP server config if supported
* Check if the MCP server process is still running
* For remote HTTP MCP servers, check network connectivity

<Warning>
  If an MCP server crashes mid-request, Mibyan will report a timeout. Check the server's own logs (not just Mibyan logs) to diagnose the root cause.
</Warning>

***

### Skills Issues

#### The Skills Hub page won't load in the desktop app (403 / blocked)

**Cause:** The docs site (`mibyanai.com`) is served through Vercel, whose WAF denies some residential IP ranges it considers flagged. If your network is on such a range, every request to the domain returns a 403 block page.

**Solution:** The Skills Hub picker probes the primary domain and automatically falls back to the equivalent GitHub Pages deployment (`nousresearch.github.io/mibyan-agent`), which serves the same catalog. If the page still fails on both origins, check whether a proxy, DNS filter, or firewall is blocking both hosts — and report the affected range to the maintainers so it can be reviewed on the deployment side.

***

## Profiles

### How do profiles differ from just setting mibyan\_HOME?

Profiles are a managed layer on top of `mibyan_HOME`. You *could* manually set `mibyan_HOME=/some/path` before every command, but profiles handle all the plumbing for you: creating the directory structure, generating shell aliases (`mibyan-work`), tracking the active profile in `~/.mibyan/active_profile`, and syncing skill updates across all profiles automatically. They also integrate with tab completion so you don't have to remember paths.

### Can two profiles share the same bot token?

No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail to connect. Create a separate bot per profile — for Telegram, talk to [@BotFather](https://t.me/BotFather) to make additional bots.

### Do profiles share memory or sessions?

No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use `mibyan profile create newname --clone-all` to copy everything from the current profile, or add `--clone-from <profile>` to copy from a specific source profile.

This isolation is also the reason to never run two agents against the *same* profile or Mibyan home: both write memory automatically and each loads the other's writes at session start, so their stored state degrades with every session. One agent per profile; for genuinely shared memory across agents, use an [external memory provider](/desktop/user-guide/features/memory-providers).

### What happens when I run `mibyan update`?

`mibyan update` pulls the latest code and reinstalls dependencies **once** (not per-profile). It then syncs updated skills to all profiles automatically. You only need to run `mibyan update` once — it covers every profile on the machine.

### How many profiles can I run?

There is no hard limit. Each profile is a directory under `~/.mibyan/profiles/` that carries at least one identity file (`config.yaml`, `.env`, `SOUL.md`, `profile.yaml`, `auth.json` or `state.db`); a bare directory without one (a leftover from a log rotation or cron tick) is not a profile — it is not listed or served, `-p <name>` reports it as missing, and `mibyan profile create <name>` refuses to overwrite it until you move or remove it. The practical limit depends on your disk space and how many concurrent gateways your system can handle (each gateway is a lightweight Python process). Running dozens of profiles is fine; each idle profile uses no resources.

***

## Workflows & Patterns

### Using different models for different tasks (multi-model workflows)

**Scenario:** You use GPT-5.4 as your daily driver, but Gemini or Grok writes better social media content. Manually switching models every time is tedious.

**Solution: Delegation config.** Mibyan can route subagents to a different model automatically. Set this in `~/.mibyan/config.yaml`:

```yaml theme={null}
delegation:
  model: "google/gemini-3-flash-preview"   # subagents use this model
  provider: "openrouter"                    # provider for subagents
```

Now when you tell Mibyan "write me a Twitter thread about X" and it spawns a `delegate_task` subagent, that subagent runs on Gemini instead of your main model. Your primary conversation stays on GPT-5.4.

You can also be explicit in your prompt: *"Delegate a task to write social media posts about our product launch. Use your subagent for the actual writing."* The agent will use `delegate_task`, which automatically picks up the delegation config.

For one-off model switches without delegation, use `/model` in the CLI:

```bash theme={null}
/model google/gemini-3-flash-preview    # switch for this session
# ... write your content ...
/model openai/gpt-5.4                   # switch back
```

<Warning>
  Each `/model` switch resets the prompt cache — the cache key includes the model, so the first message after every switch re-reads the whole conversation at full input price. On long sessions, prefer delegation (subagents get their own fresh context) or a new session over repeated back-and-forth switching.
</Warning>

See [Subagent Delegation](/desktop/user-guide/features/delegation) for more on how delegation works.

### Running multiple agents on one WhatsApp number (per-chat binding)

**Scenario:** In OpenClaw, you had multiple independent agents bound to specific WhatsApp chats — one for a family shopping list group, another for your private chat. Can Mibyan do this?

**Current limitation:** Mibyan profiles each require their own WhatsApp number/session. You cannot bind multiple profiles to different chats on the same WhatsApp number — the WhatsApp bridge (Baileys) uses one authenticated session per number.

**Workarounds:**

1. **Use a single profile with personality switching.** Create different `AGENTS.md` context files or use the `/personality` command to change behavior per chat. The agent sees which chat it's in and can adapt.

2. **Use cron jobs for specialized tasks.** For a shopping list tracker, set up a cron job that monitors a specific chat and manages the list — no separate agent needed.

3. **Use separate numbers.** If you need truly independent agents, pair each profile with its own WhatsApp number. Virtual numbers from services like Google Voice work for this.

4. **Use Telegram or Discord instead.** These platforms support per-chat binding more naturally — each Telegram group or Discord channel gets its own session, and you can run multiple bot tokens (one per profile) on the same account.

See [Profiles](/desktop/user-guide/profiles) and [WhatsApp setup](/desktop/user-guide/messaging/whatsapp) for more details.

### Controlling what shows up in Telegram (hiding logs and reasoning)

**Scenario:** You see gateway exec logs, Mibyan reasoning, and tool call details in Telegram instead of just the final output.

**Solution:** The `display.tool_progress` setting in `config.yaml` controls how much tool activity is shown:

```yaml theme={null}
display:
  tool_progress: "off"   # options: off, new, all, verbose
```

* **`off`** — Only the final response. No tool calls, no reasoning, no logs.
* **`new`** — Shows new tool calls as they happen (brief one-liners).
* **`all`** — Shows all tool activity including results.
* **`verbose`** — Full detail including tool arguments and outputs.

For messaging platforms, `off` or `new` is usually what you want. After editing `config.yaml`, restart the gateway for changes to take effect.

You can also toggle this per-session with the `/verbose` command (if enabled):

```yaml theme={null}
display:
  tool_progress_command: true   # enables /verbose in the gateway
```

### Managing skills on Telegram (slash command limit)

**Scenario:** Telegram has a 100 slash command limit, and your skills are pushing past it. You want to disable skills you don't need on Telegram, but `mibyan skills config` settings don't seem to take effect.

**Solution:** Use `mibyan skills config` to disable skills per-platform. This writes to `config.yaml`:

```yaml theme={null}
skills:
  disabled: []                    # globally disabled skills
  platform_disabled:
    telegram: [skill-a, skill-b]  # disabled only on telegram
```

After changing this, **restart the gateway** (`mibyan gateway restart` or kill and relaunch). The Telegram bot command menu rebuilds on startup.

<Tip>
  Skills with very long descriptions are truncated to 40 characters in the Telegram menu to stay within payload size limits. If skills aren't appearing, it may be a total payload size issue rather than the 100 command count limit — disabling unused skills helps with both.
</Tip>

### Shared thread sessions (multiple users, one conversation)

**Scenario:** You have a Telegram or Discord thread where multiple people mention the bot. You want all mentions in that thread to be part of one shared conversation, not separate per-user sessions.

**Current behavior:** Mibyan creates sessions keyed by user ID on most platforms, so each person gets their own conversation context. This is by design for privacy and context isolation.

**Workarounds:**

1. **Use Slack.** Slack sessions are keyed by thread, not by user. Multiple users in the same thread share one conversation — exactly the behavior you're describing. This is the most natural fit.

2. **Use a group chat with a single user.** If one person is the designated "operator" who relays questions, the session stays unified. Others can read along.

3. **Use a Discord channel.** Discord sessions are keyed by channel, so all users in the same channel share context. Use a dedicated channel for the shared conversation.

### Exporting Mibyan to another machine

**Scenario:** You've built up skills, cron jobs, and memories on one machine and want to move everything to a new dedicated Linux box.

**Solution:**

1. Install Mibyan on the new machine:

<Note>
  Mibyan Desktop is installed from the Mibyan Desktop download, or launched from an existing Mibyan CLI with `mibyan desktop`. See [Install and update](/products/desktop-guide/install-and-update).
</Note>

2. On the **source machine**, create a full backup:
   ```bash theme={null}
   mibyan backup
   ```
   This saves a zip archive at `~/mibyan-backup-<timestamp>.zip`.
   The full backup covers configuration, credentials, memories, skills, sessions,
   and profiles under the Mibyan data root. It is not an application or runtime image.

3. Copy the zip to the new machine and import it:
   ```bash theme={null}
   # On the source machine
   scp ~/mibyan-backup-<timestamp>.zip newmachine:~/

   # On the new machine
   mibyan import ~/mibyan-backup-<timestamp>.zip
   ```

4. On the new machine, run `mibyan setup` to verify API keys and provider config are working.

### Moving a single profile to another machine

**Scenario:** You want to move or share one specific profile — not your full installation.

```bash theme={null}
# On the source machine
mibyan profile export work ./work-backup.tar.gz

# Copy the file to the target machine, then:
mibyan profile import ./work-backup.tar.gz work
```

The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.

### `mibyan backup` vs `mibyan profile export`

| Feature | `mibyan backup` | `mibyan profile export` |
| :- | :- | :- |
| **Use Case** | **Full machine migration** | **Porting/sharing a specific profile** |
| **Scope** | Mibyan data root, with the exclusions listed below | Single profile directory |
| **Includes** | All profiles, global config, API keys, sessions | Single profile: SOUL.md, memories, sessions, skills |
| **Credentials** | **Included** (`.env` and `auth.json`) | **Excluded** (stripped for safe sharing) |
| **Format** | `.zip` | `.tar.gz` |

The full backup excludes:

* The source checkout, dependency environments, and downloaded tools, models, and runtimes.
* Build caches, checkpoints, previous backups, and quick snapshots.
* Browser profiles, including copies of real-browser credentials.
* Bytecode, SQLite sidecars, `gateway.pid`, `cron.pid`, and `.backup.lock`.

`mibyan backup --quick` saves selected state files instead of a full archive.
It is not a replacement for the full backup before a machine migration.

Full backups report files that fail to copy. An archive can therefore exist
with missing data. Review the skipped-file report before you remove the source installation.
Restored package declarations let PM download dependencies again. Bytecode and
SQLite sidecars regenerate locally. The exclusions do not remove `.env` or
`auth.json` from the full backup.

**Manual fallback (rsync):** If you prefer to copy files directly, exclude the code repo:

```bash theme={null}
rsync -av --exclude='mibyan-agent' ~/.mibyan/ newmachine:~/.mibyan/
```

<Tip>
  `mibyan backup` produces a consistent snapshot even while Mibyan is actively running. The restored archive excludes machine-local runtime files like `gateway.pid` and `cron.pid`.
</Tip>

### Permission denied when reloading shell after install

**Scenario:** After running the Mibyan installer, `source ~/.zshrc` gives a permission denied error.

**Cause:** This usually happens when `~/.zshrc` (or `~/.bashrc`) has incorrect file permissions, or when the installer couldn't write to it cleanly. It's not a Mibyan-specific issue — it's a shell config permissions problem.

**Solution:**

```bash theme={null}
# Check permissions
ls -la ~/.zshrc

# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc

# Then reload
source ~/.zshrc

# Or just open a new terminal window — it picks up PATH changes automatically
```

If the installer added the PATH line but permissions are wrong, you can add it manually:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
```

### Error 400 on first agent run

**Scenario:** Setup completes fine, but the first chat attempt fails with HTTP 400.

**Cause:** Usually a model name mismatch — the configured model doesn't exist on your provider, or the API key doesn't have access to it.

**Solution:**

```bash theme={null}
# Check what model and provider are configured
mibyan config show | head -20

# Re-run model selection
mibyan model

# Or test with a known-good model
mibyan chat -q "hello" --model anthropic/claude-opus-4.7
```

If using OpenRouter, make sure your API key has credits. A 400 from OpenRouter often means the model requires a paid plan or the model ID has a typo.

***

## Still Stuck?

If your issue isn't covered here:

1. **Search existing issues:** [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
2. **Ask the community:** [Nous Research Discord](https://discord.gg/nousresearch)
3. **File a bug report:** Include your OS, Python version (`python3 --version`), Mibyan version (`mibyan --version`), and the full error message


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.