> ## 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.

# Installation

> Install Mibyan with desktop bundles, source installers, Docker, Nix, or the Termux APT package

<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>

Get Mibyan up and running in under two minutes!

<Tip>
  **Platform Support**

  For the full platform support matrix (which OSes, distribution methods, and
  platform-gated features are supported), see **[Platform Support](/desktop/getting-started/platform-support)**.
</Tip>

## Quick Install

### Desktop packages on macOS or Windows

Download the package for your platform from the
[Mibyan website](https://mibyanai.com).

* **Windows:** open the `.appinstaller` download with Windows App Installer.
  It installs the signed MSIX bundle and records its update source.
  Microsoft Store packages have separate Store ownership.
* **macOS:** open the DMG, then copy `Mibyan.app` to Applications. The ZIP
  artifact carries the signed app used by the automatic updater.

Bundled packages contain the agent, Python, supported dependencies, and prebuilt
interfaces. First launch does not build that base runtime. Provider access and
optional integrations can still require network access.

A `Mibyan-Setup` bootstrap installer is different: it downloads a source
installation and builds the desktop app. Light is a remote-only build variant,
not a bundled local runtime. See [Mibyan Desktop](/desktop/user-guide/desktop).

<Note>
  The macOS installer is **Apple Silicon only**. macOS on x86 (Intel) processors is [not a supported platform](/desktop/getting-started/platform-support#unsupported).
</Note>

### Without Mibyan Desktop:

For a command-line only install without Mibyan Desktop, run:

#### Linux / macOS / WSL2

<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>

#### Windows (native)

Run in powershell:

<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>

If you want to install & run Mibyan Desktop after a command-line only install, simply run

```bash theme={null}
mibyan desktop
```

### Android / Termux

Use the Termux APT package on aarch64 Android devices.
Configure its signed repository before running `pkg install mibyan-agent`.
The desktop/server scripts are not the Termux installation path.

### What the source installer does

The scripts clone the source, bootstrap uv, and delegate dependency preparation
to PM. PM provides pinned Python, Node.js, npm, ripgrep, and FFmpeg. The source
installation selects the `all` Python extra, not every optional extra.
PM also installs the browser and computer-use tools by default: `agent-browser`
and its pinned Chromium, and `cua-driver` (the computer-use driver, on macOS,
Windows and glibc Linux). If a download fails, the install still completes and
prints the command to retry. The default browser driver (browser-harness, the
engine of the Browser Use CLI) is a regular Python dependency, so every install,
the Desktop app included, already has it.
Other optional tools use their feature-specific installation paths.

To leave the browser tools out, pass `--skip-browser` on POSIX or `-SkipBrowser`
on Windows; for the computer-use driver, `--skip-computer-use` /
`-SkipComputerUse`. Mibyan remembers these choices: later installs and
`mibyan update` do not add them back. Run `mibyan pm install agent-browser` or
`mibyan pm install cua-driver` to install them and undo the choice.

The scripts create a launcher and prepare the data directory. Interactive runs
also invoke setup and gateway configuration. `--non-interactive` on POSIX, or
`-NonInteractive` on Windows, skips stages that need input. The optional
`--include-desktop` / `-IncludeDesktop` stage builds the desktop from source.

On a terminal the scripts show one status line per step and write the output
of git, uv and the builds to `logs/install.log` under the Mibyan data
directory; a failed step prints its last lines and the log path. CI (`CI` or
`GITHUB_ACTIONS` set), redirected output, `--verbose` / `-Verbose` or
`mibyan_INSTALL_VERBOSE=1` stream everything instead.

#### Install layout

| Method | Code | CLI entry point | Default user data |
| - | - | - | - |
| POSIX source script | `~/.mibyan/mibyan-agent/` | `~/.local/bin/mibyan` wrapper | `~/.mibyan/` |
| Windows source script | `%LOCALAPPDATA%\mibyan\mibyan-agent\` | `%LOCALAPPDATA%\mibyan\bin\` | `%LOCALAPPDATA%\mibyan\` |
| Desktop bundle | Inside the installed app package | Packaged launchers; Windows execution aliases | Platform default Mibyan data directory |
| Docker | `/opt/mibyan/` | Image entrypoint and `mibyan` shim | Mounted `/opt/data/` |
| Termux APT | `$PREFIX/lib/mibyan-agent/` | Symlinks in `$PREFIX/bin/` | `~/.mibyan/` |

`mibyan_HOME` selects user data. The POSIX script's `--dir` selects its source
checkout independently. Windows provides `-MibyanHome` and `-InstallDir`.
Running the POSIX script as root does not select an automatic FHS layout:
it uses root's home unless you provide an explicit source path.

PM's tool store and per-install Python generations have separate lifetimes.
See [Package management](/desktop/reference/package-management) for their locations.
Do not remove the data root to repair an application installation.

### After Installation

Reload your shell and start chatting:

```bash theme={null}
source ~/.bashrc   # or: source ~/.zshrc
mibyan             # Start chatting!
```

To reconfigure individual settings later, use the dedicated commands:

```bash theme={null}
mibyan model          # Choose your LLM provider and model
mibyan tools          # Configure which tools are enabled
mibyan gateway setup  # Set up messaging platforms
mibyan config set     # Set individual config values
mibyan config get     # Inspect individual config values
mibyan setup          # Or run the full setup wizard to configure everything at once
```

<Tip>
  **Fastest path: Nous Portal**

  One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:

  ```bash theme={null}
  mibyan setup --portal
  ```

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

<Tip>
  **Already running Mibyan on another machine?**

  You don't need to rebuild your setup from scratch. Restore a full backup with `mibyan import` (see [Exporting Mibyan to another machine](/desktop/reference/faq#exporting-mibyan-to-another-machine)), or bring over a single agent with `mibyan profile import` (see [Moving a single profile to another machine](/desktop/reference/faq#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`mibyan backup` vs `mibyan profile export`](/desktop/reference/faq#mibyan-backup-vs-mibyan-profile-export) explains which to use.
</Tip>

***

## Prerequisites

For the POSIX source script, provide Git, curl, tar, and SHA-256 utilities.
Windows can bootstrap its pinned Git for Windows archive when Git is absent.
The script always downloads its verified uv pin; a uv already on your PATH is never used.

Current first-party installations run on **Python 3.14**. The broader
`>=3.11,<3.15` range in `pyproject.toml` lets older Python installations
run the updater before PM switches them to 3.14; it does not promise current
runtime support on 3.11–3.13. PM selects the managed tool versions from
`pm/lock.json`; it does not adopt arbitrary system Node versions as the
installed runtime.

Source builds can require a native compiler and platform development libraries.
Building Electron from source adds Node native-module requirements. These
build prerequisites do not apply to installing a complete desktop package.
Linux Chromium also requires system libraries supplied by the distribution.

<Tip>
  **Nix users**

  Nix is **no longer an explicitly supported install path** (best-effort only). If you already use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the **[Nix & NixOS Setup](/desktop/getting-started/nix-setup)** guide.
</Tip>

***

## Manual / Developer Installation

For a source checkout, start with the
[PM developer workflow](/desktop/reference/package-management#developer-workflow).
It covers activation, daily commands, dependency refresh, and current bootstrap limits.
[Development Setup](/desktop/developer-guide/contributing#development-setup) covers the separate test environment and checks.

***

## Non-Sudo / System Service User Installs

Run the source installer as the intended service user. Its home, tool store,
configuration, and launcher must belong to that user.

1. As an administrator, install the source-build prerequisites and any Linux
   libraries needed by the selected browser backend.
2. As the service user, run the regular installer:

<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>

3. Add the actual launcher directory to the service user's shell environment:

   ```bash theme={null}
   export PATH="$HOME/.local/bin:$PATH"
   ```

4. Run `mibyan doctor` from that account. Use the installed wrapper, not a
   hardcoded `venv/bin/mibyan` path.

5. For a Linux user service that must survive logout, enable lingering as an administrator:

   ```bash theme={null}
   sudo loginctl enable-linger SERVICE_USER
   ```

The current source installer does not run Playwright's `--with-deps` step or
provide a package-manager-specific sudo fallback. PM manages tool binaries;
the administrator supplies system libraries. See
[Browser automation](/desktop/user-guide/features/browser) and
[Messaging Gateway](/desktop/user-guide/messaging/overview).

***

## Troubleshooting

| Problem | Solution |
| - | - |
| `mibyan: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
| `API key not set` | Run `mibyan model` to configure your provider, or `mibyan config set OPENROUTER_API_KEY your_key` |
| Missing config after update | Run `mibyan config check` then `mibyan config migrate` |

For more diagnostics, run `mibyan doctor` — it will tell you exactly what's missing and how to fix it.

### Symlinked home directories and external storage

Mibyan supports a symlinked `mibyan_HOME` and symlinked home subdirectories,
including `hooks`, `skills`, `sessions`, and `logs`. During home initialization,
existing directory links are preserved, and permissions on linked directories
(and descendants such as `logs/curator`) are left to their owner.

If a link target is missing, inaccessible, or not a directory, initialization
stops with a storage error naming the path and link target. Mibyan does **not**
replace the link or create its missing target: doing so could write data onto
the local disk while an external or NAS volume is unmounted. Check the reported
link, restore the mount or correct its target, and verify access permissions
before retrying. For a deliberately new dotfiles target, create it yourself only
after confirming the intended storage is available.

`mibyan doctor` reports these failures as storage problems, not invalid YAML.
Keep your existing `config.yaml`; running `mibyan setup` is not the repair for an
unavailable directory. This is a directory-availability check, not a mount monitor:
an existing directory cannot establish that the intended volume is mounted.

## Install method auto-detection

The update owner depends on the running installation, not only its data home.
Source checkouts use the managed Git update path. Desktop bundles, Docker,
Nix, and Termux packages retain their package owner's update mechanism.
`mibyan doctor` reports installation provenance. See
[Updating & Uninstalling](/desktop/getting-started/updating) before changing package-owned files.


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