Mibyan Quickstart

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.

Python dependency commands on this page use a PM-prepared source checkout. After a dependency change, reactivate the checkout and restart Mibyan. This guide gets you from zero to a working Mibyan setup that survives real use. Install, choose a provider, verify a working chat, and know exactly what to do when something breaks.

Who this is for

Brand new and want the shortest path to a working setup
Switching providers and don’t want to lose time to config mistakes
Setting up Mibyan for a team, bot, or always-on workflow
Tired of “it installed, but it still does nothing”

The fastest path

Pick the row that matches your goal:

Goal	Do this first	Then do this
I just want Mibyan working on my machine	`mibyan setup`	Run a real chat and verify it responds
I already know my provider	`mibyan model`	Save the config, then start chatting
I want a bot or always-on setup	`mibyan gateway setup` after CLI works	Connect Telegram, Discord, Slack, or another platform
I want a local or self-hosted model	`mibyan model` → custom endpoint	Verify the endpoint, model name, and context length
I want multi-provider fallback	`mibyan model` first	Add routing and fallback only after the base chat works

Rule of thumb: if Mibyan cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.

1. Install Mibyan

With the Mibyan Desktop installer on macOS or Windows (recommended)

To easily install the command-line and desktop applications, download the Mibyan Desktop installer from our website and run it.

Without Mibyan Desktop:

For a command-line only install without Mibyan Desktop, run: For aarch64 Android devices, use the separate Termux APT guide.

Linux / macOS / WSL2

Mibyan Desktop is installed from the Mibyan Desktop download, or launched from an existing Mibyan CLI with mibyan desktop. See Install and update.

Windows (native)

Run in powershell:

Mibyan Desktop is installed from the Mibyan Desktop download, or launched from an existing Mibyan CLI with mibyan desktop. See Install and update.

After it finishes, reload your shell:

source ~/.bashrc   # or source ~/.zshrc

For detailed installation options, prerequisites, and troubleshooting, see the Installation guide.

2. Choose a Provider

The single most important setup step. Use mibyan model to walk through the choice interactively:

mibyan model

Easiest path: Nous PortalOne subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

mibyan setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.

Setup modesOn a fresh install, mibyan setup offers three modes:

Quick Setup (Nous Portal) — OAuth login, no API keys to manage; sets up a model plus the Tool Gateway tools, billed to your Nous Portal subscription. The recommended fast path.
Full Setup — walk through every provider, tool, and option yourself (bring your own keys).
Blank Slate — everything starts off except the bare minimum needed to run an agent: provider & model, the File Operations toolset, and the Terminal toolset. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers — and compression, checkpoints, smart routing, and memory capture are all disabled. After the minimal baseline is applied, you choose one of two paths: start with everything disabled (finish now with the minimal agent), or walk through all configurations (opt in to tools, skills, plugins, MCP, and messaging). Pick this when you want a minimal, fully-controlled agent and intend to enable only exactly what you need.

Blank Slate writes an explicit platform_toolsets.cli list plus agent.disabled_toolsets, so nothing you didn’t choose ever loads — not even after mibyan update. Re-enable anything later with mibyan tools, seed skills with mibyan skills opt-in --sync, or tune settings with mibyan setup agent.

Good defaults:

Provider	What it is	How to set up
Nous Portal	Subscription-based, zero-config	OAuth login via `mibyan model`
OpenAI Codex	ChatGPT or Codex subscription, uses Codex models	Device code auth via `mibyan model` → ChatGPT or Codex Subscription
Anthropic	Claude models directly — Max plan + extra usage credits (OAuth), or API key for pay-per-token	`mibyan model` → OAuth login (requires Max + extra credits), or an Anthropic API key
OpenRouter	Multi-provider routing across many models	Enter your API key
Fireworks AI	Direct OpenAI-compatible model API	Set `FIREWORKS_API_KEY`
Z.AI	GLM / Zhipu-hosted models	Set `GLM_API_KEY` / `ZAI_API_KEY` (also accepts `Z_AI_API_KEY`)
Kimi / Moonshot	Moonshot-hosted coding and chat models	Set `KIMI_API_KEY` (or the Kimi-Coding-specific `KIMI_CODING_API_KEY`)
Kimi / Moonshot China	China-region Moonshot endpoint	Set `KIMI_CN_API_KEY`
Arcee AI	Trinity models	Set `ARCEEAI_API_KEY`
GMI Cloud	Multi-model direct API	Set `GMI_API_KEY`
Actual Computer	Your own hardware as a private inference cluster — hosted relay or local daemon	Set `ACTUAL_API_KEY` (relay) or `ACTUAL_BASE_URL=http://127.0.0.1:8080` (local, no key)
MiniMax (OAuth)	MiniMax frontier model via browser OAuth — no API key needed (model name in `mibyan_cli/models.py` may change between releases)	`mibyan model` → MiniMax (OAuth)
MiniMax	International MiniMax endpoint	Set `MINIMAX_API_KEY`
MiniMax China	China-region MiniMax endpoint	Set `MINIMAX_CN_API_KEY`
Alibaba Cloud	Qwen models via DashScope	Set `DASHSCOPE_API_KEY` (Qwen Coding Plan also accepts `ALIBABA_CODING_PLAN_API_KEY`)
Hugging Face	20+ open models via unified router (Qwen, DeepSeek, Kimi, etc.)	Set `HF_TOKEN`
AWS Bedrock	Claude, Nova, Llama, DeepSeek via native Converse API	IAM role or `aws configure` (guide)
Azure Foundry	Azure AI Foundry-hosted models	Set `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL`
Google AI Studio	Gemini models via direct API	Set `GOOGLE_API_KEY` / `GEMINI_API_KEY`
xAI	Grok models via direct API	Set `XAI_API_KEY`
xAI Grok OAuth	SuperGrok / Premium+ subscription, no API key needed	`mibyan model` → xAI Grok OAuth
NovitaAI	Multi-model API gateway	Set `NOVITA_API_KEY`
Ramp Router	Responses-native LLM gateway routing across OpenAI/Anthropic/xAI/…	Set `RAMP_ROUTER_API_KEY`
Nebius Token Factory	Open models on Nebius AI cloud	Set `NEBIUS_API_KEY`
StepFun	Step Plan models	Set `STEPFUN_API_KEY`
Xiaomi MiMo	Xiaomi-hosted models	Set `XIAOMI_API_KEY`
Tencent TokenHub	Tencent-hosted models	Set `TOKENHUB_API_KEY`
Tencent TokenPlan	Tencent Hy models via Anthropic-style endpoint	Set `TOKENPLAN_API_KEY`
Ollama Cloud	Managed Ollama-hosted models	Set `OLLAMA_API_KEY`
LM Studio	Local desktop app exposing an OpenAI-compatible API	Set `LM_API_KEY` (and `LM_BASE_URL` if non-default)
Qwen OAuth	Qwen Portal browser OAuth — no API key needed	`mibyan model` → Qwen OAuth
Kilo Code	KiloCode-hosted models	Set `KILOCODE_API_KEY`
OpenCode Zen	Pay-as-you-go access to curated models	Set `OPENCODE_ZEN_API_KEY`
OpenCode Go	$10/month subscription for open models	Set `OPENCODE_GO_API_KEY`
DeepSeek	Direct DeepSeek API access	Set `DEEPSEEK_API_KEY`
NVIDIA NIM	Nemotron models via build.nvidia.com or local NIM	Set `NVIDIA_API_KEY` (optional: `NVIDIA_BASE_URL`)
GitHub Copilot	GitHub Copilot subscription (GPT-5.x, Claude, Gemini, etc.)	OAuth via `mibyan model`, or `COPILOT_GITHUB_TOKEN` / `GH_TOKEN`
GitHub Copilot ACP	Copilot ACP agent backend (spawns local `copilot` CLI)	`mibyan model` (requires `copilot` CLI + `copilot login`)
Vercel AI Gateway	Vercel AI Gateway routing	Set `AI_GATEWAY_API_KEY`
Custom Endpoint	VLLM, SGLang, Ollama, or any OpenAI-compatible API	Set base URL + API key

For most first-time users: choose a provider, accept the defaults unless you know why you’re changing them. The full provider catalog with env vars and setup steps lives on the Providers page.

Minimum context: 64K tokensMibyan requires a model with at least 64,000 tokens of context. Models with smaller windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you’re running a local model, set its context size to at least 64K (e.g. --ctx-size 65536 for llama.cpp or -c 65536 for Ollama).

You can switch providers at any time with mibyan model — no lock-in. For a full list of all supported providers and setup details, see AI Providers.

How settings are stored

Mibyan separates secrets from normal config:

Secrets and tokens → ~/.mibyan/.env
Non-secret settings → ~/.mibyan/config.yaml

The easiest way to set values correctly is through the CLI:

mibyan config set model anthropic/claude-opus-4.6
mibyan config set terminal.backend docker
mibyan config set OPENROUTER_API_KEY sk-or-...

The right value goes to the right file automatically.

3. Run Your First Chat

mibyan            # classic CLI
mibyan --tui      # modern TUI (recommended)

You’ll see a welcome banner with your model, available tools, and skills. Use a prompt that’s specific and easy to verify:

Pick your interfaceMibyan ships with two terminal interfaces: the classic prompt_toolkit CLI and a newer TUI with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config — try each with mibyan vs mibyan --tui.

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

Help me set up a clean GitHub PR workflow for this codebase.

What success looks like:

The banner shows your chosen model/provider
Mibyan replies without error
It can use a tool if needed (terminal, file read, web search)
The conversation continues normally for more than one turn

If that works, you’re past the hardest part.

4. Verify Sessions Work

Before moving on, make sure resume works:

mibyan --continue    # Resume the most recent session
mibyan -c            # Short form

That should bring you back to the session you just had. If it doesn’t, check whether you’re in the same profile and whether the session actually saved. This matters later when you’re juggling multiple setups or machines.

5. Try Key Features

Use the terminal

❯ What's my disk usage? Show the top 5 largest directories.

The agent runs terminal commands on your behalf and shows results.

Slash commands

Type / to see an autocomplete dropdown of all commands:

Command	What it does
`/help`	Show all available commands
`/tools`	List available tools
`/model`	Switch models interactively
`/personality pirate`	Try a fun personality
`/save`	Save the conversation

Multi-line input

Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line. Shift+Enter requires a terminal that sends it as a distinct sequence (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). Alt+Enter and Ctrl+J work in every terminal.

Interrupt the agent

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

6. Add the Next Layer

Only after the base chat works. Pick what you need:

Bot or shared assistant

mibyan gateway setup    # Interactive platform configuration

Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant, or Microsoft Teams.

Automation and tools

mibyan tools — tune tool access per platform
mibyan skills — browse and install reusable workflows
Cron — only after your bot or CLI setup is stable

Sandboxed terminal

For safety, run the agent in a Docker container or on a remote server:

mibyan config set terminal.backend docker    # Docker isolation
mibyan config set terminal.backend ssh       # Remote server

For Docker sandboxes, you can also enable the egress credential-injection proxy so the sandbox never sees your real API keys — only opaque proxy tokens that work exclusively from behind a local TLS-intercepting daemon. See Egress proxy. Setup is mibyan egress setup && mibyan egress start; mibyan setup terminal also points Docker users at it. Modal, SSH, Daytona, and Singularity are not wired yet.

Voice mode

Run mibyan tools and configure the Voice providers. Then enable /voice on in the CLI and press Ctrl+B to record. PM handles missing supported requirements; a dependency change can require a restart. Local Faster-Whisper is not available on every architecture. See Voice Mode.

Skills

Skills are on-demand instruction documents that teach Mibyan how to do a specific task — deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs. Each is a SKILL.md file with a name, a description, and a step-by-step procedure. The agent reads the short descriptions for free and only loads a skill’s full content when a task actually calls for it, so adding skills doesn’t bloat every request. Mibyan ships with a catalog of bundled skills already installed in ~/.mibyan/skills/. You can add more from the Skills Hub, or write your own. Browse and install from the hub:

mibyan skills browse                      # list everything available
mibyan skills search kubernetes           # find skills by keyword
mibyan skills install openai/skills/k8s   # install one (runs a security scan first)

The install argument is a source/path slug from the hub — openai/skills/k8s means the k8s skill from OpenAI’s catalog. mibyan skills browse shows the exact slugs to use. Use a skill — every installed skill becomes a slash command automatically:

/k8s deploy the staging manifest          # run the skill with a request
/k8s                                       # load it and let Mibyan ask what you need

This works in the CLI and in any connected messaging platform. You don’t have to install everything up front — the agent picks the right bundled skill on its own during normal conversation when a task matches one. See Skills System for writing your own, external skill directories, and the full hub source list.

MCP servers

# Add to ~/.mibyan/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Editor integration (ACP)

ACP support ships with the standard [all] extras, so the curl installer already includes it. Just run:

mibyan acp

(If you installed without [all], run cd ~/.mibyan/mibyan-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)" first.) See ACP Editor Integration.

Common Failure Modes

These are the problems that waste the most time:

Symptom	Likely cause	Fix
Mibyan opens but gives empty or broken replies	Provider auth or model selection is wrong	Run `mibyan model` again and confirm provider, model, and auth
Custom endpoint “works” but returns garbage	Wrong base URL, model name, or not actually OpenAI-compatible	Verify the endpoint in a separate client first
Gateway starts but nobody can message it	Bot token, allowlist, or platform setup is incomplete	Re-run `mibyan gateway setup` and check `mibyan gateway status`
`mibyan --continue` can’t find old session	Switched profiles or session never saved	Check `mibyan sessions list` and confirm you’re in the right profile
Model unavailable or odd fallback behavior	Provider routing or fallback settings are too aggressive	Keep routing off until the base provider is stable
`mibyan doctor` flags config problems	Config values are missing or stale	Fix the config, retest a plain chat before adding features

Recovery Toolkit

When something feels off, use this order:

mibyan doctor
mibyan model
mibyan setup
mibyan sessions list
mibyan --continue
mibyan gateway status

That sequence gets you from “broken vibes” back to a known state fast.

Quick Reference

Command	Description
`mibyan`	Start chatting
`mibyan model`	Choose your LLM provider and model
`mibyan tools`	Configure which tools are enabled per platform
`mibyan setup`	Full setup wizard (configures everything at once)
`mibyan doctor`	Diagnose issues
`mibyan update`	Update to latest version
`mibyan gateway`	Start the messaging gateway
`mibyan --continue`	Resume last session

Next Steps

CLI Guide — Master the terminal interface
Configuration — Customize your setup
Messaging Gateway — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams, and more
Tools & Toolsets — Explore available capabilities
AI Providers — Full provider list and setup details
Skills System — Reusable workflows and knowledge
Tips & Best Practices — Power user tips
Moving to another machine — mibyan backup migrates your whole setup (or a single profile); no need to rebuild from scratch

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

Who this is for

The fastest path

1. Install Mibyan

With the Mibyan Desktop installer on macOS or Windows (recommended)

Without Mibyan Desktop:

Linux / macOS / WSL2

Windows (native)

2. Choose a Provider

How settings are stored

3. Run Your First Chat

4. Verify Sessions Work

5. Try Key Features

Use the terminal

Slash commands

Multi-line input

Interrupt the agent

6. Add the Next Layer

Bot or shared assistant

Automation and tools

Sandboxed terminal

Voice mode

Skills

MCP servers

Editor integration (ACP)

Common Failure Modes

Recovery Toolkit

Quick Reference

Next Steps

​Who this is for

​The fastest path

​1. Install Mibyan

​With the Mibyan Desktop installer on macOS or Windows (recommended)

​Without Mibyan Desktop:

​Linux / macOS / WSL2

​Windows (native)

​2. Choose a Provider

​How settings are stored

​3. Run Your First Chat

​4. Verify Sessions Work

​5. Try Key Features

​Use the terminal

​Slash commands

​Multi-line input

​Interrupt the agent

​6. Add the Next Layer

​Bot or shared assistant

​Automation and tools

​Sandboxed terminal

​Voice mode

​Skills

​MCP servers

​Editor integration (ACP)

​Common Failure Modes

​Recovery Toolkit

​Quick Reference

​Next Steps

Who this is for

The fastest path

1. Install Mibyan

With the Mibyan Desktop installer on macOS or Windows (recommended)

Without Mibyan Desktop:

Linux / macOS / WSL2

Windows (native)

2. Choose a Provider

How settings are stored

3. Run Your First Chat

4. Verify Sessions Work

5. Try Key Features

Use the terminal

Slash commands

Multi-line input

Interrupt the agent

6. Add the Next Layer

Bot or shared assistant

Automation and tools

Sandboxed terminal

Voice mode

Skills

MCP servers

Editor integration (ACP)

Common Failure Modes

Recovery Toolkit

Quick Reference

Next Steps