# Install AI Architect (self-hosted)

This guide walks you through installing [**Bito's AI Architect**](/ai-architect/overview.md) as a self-hosted service in your own infrastructure. Self-hosting gives you complete control over where your code knowledge graph resides and how AI Architect accesses your repositories.

**Why choose self-hosted deployment?** Organizations with strict data governance requirements, air-gapped environments, or specific compliance needs benefit from running AI Architect within their own infrastructure. Your codebase analysis and knowledge graph stay entirely within your control, while still providing the same powerful context-aware capabilities to your AI coding tools.

**What you'll accomplish:** By the end of this guide, you'll have AI Architect running on your infrastructure, connected to your Git repositories, and ready to integrate with AI coding tools like Claude Code, Cursor, Windsurf, and GitHub Copilot through the Model Context Protocol (MCP).

### Deployment options

AI Architect can be deployed in three different configurations depending on your team size, infrastructure, and security requirements:

#### a. Personal use (with your LLM keys)

Set up AI Architect on your local machine for individual development work. You'll provide your own LLM API keys for indexing, giving you complete control over the AI models used and associated costs.

**Best for:** Individual developers who want codebase understanding on their personal machine.

#### b. Team / shared access (with your LLM keys)

Deploy AI Architect on a shared server within your infrastructure, allowing multiple team members to connect their AI coding tools to the same MCP server. Each team member can configure AI Architect with their preferred AI coding agent while sharing the same indexed codebase knowledge graph.

**Best for:** Development teams that want to share codebase intelligence across the team while managing their own LLM costs.

#### c. Enterprise deployment (requires Bito Enterprise Plan)

Deploy AI Architect on your infrastructure (local machine or shared server) with indexing managed by Bito. Instead of providing your own LLM keys, Bito handles the repository indexing process, simplifying setup and cost management.

**Best for:** Organizations that prefer managed indexing without handling individual LLM API keys and costs.

{% hint style="info" %}
**Note:** All deployment options are self-hosted on your infrastructure — your code and knowledge graph remain under your control.
{% endhint %}

## Prerequisites

### a. Required accounts and tokens

{% stepper %}
{% step %}

### Bito API Key (aka Bito Access Key)

You'll need a **Bito account** and a **Bito Access Key** to authenticate AI Architect. You can sign up for a Bito account at [**https://alpha.bito.ai**](https://alpha.bito.ai/), and create an access key from [**Settings -> Advanced Settings**](https://alpha.bito.ai/home/advanced)

* [**View Guide**](/help/account-and-settings/access-key.md)
  {% endstep %}

{% step %}

### Git provider

We support the following Git providers:

* GitHub
* GitLab
* Bitbucket

So, you'll need an account on one of these Git providers to index your repositories with AI Architect.
{% endstep %}

{% step %}

### Git Access Token

A personal access token from your chosen Git provider is required. You'll use this token to allow AI Architect to read and index your repositories.

1. **GitHub Personal Access Token (Classic):** To use GitHub repositories with AI Architect, ensure you have a CLASSIC personal access token with repo access. We do not support fine-grained tokens currently.
   * [**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
2. **GitLab Personal Access Token:** To use GitLab repositories with AI Architect, a token with API access is required.
   * [**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)
3. **Bitbucket Access Token:** To use Bitbucket repositories with AI Architect, you need **API Token** or **HTTP Access Token** depending on your Bitbucket setup.
   1. **Bitbucket Cloud (`API Token`):** You must provide both your **token** and **email address**.
      * [**View Guide**](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
   2. **Bitbucket Self-Hosted (`HTTP Access Token`):** You must provide both your **token** and **username**.
      * [**View Guide**](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
        {% endstep %}

{% step %}

### LLM API keys

Bito's AI Architect uses Large Language Models (LLMs) to build a knowledge graph of your codebase.

LLM API keys are required for self-managed AI Architect deployments. An **Anthropic (Claude)** API key is mandatory; you can optionally also provide an **OpenAI (GPT)** API key. AI Architect also supports [**Portkey**](https://portkey.ai) integration for custom proxy configurations.

With an Anthropic API key, indexing costs are typically **$1.00–$1.50 per MB** of indexable code (source files only; binaries, archives, and images are skipped).

Teams of up to five members can use AI Architect for free with their preferred coding agents by using their own LLM API keys. Larger teams require [**Bito Enterprise Plan**](https://bito.ai/pricing/), which includes bundled LLM tokens. Further, if you want to power Bito Code Review Agent with AI Architect, you will need Bito Enterprise Plan regardless of the size of the team.

{% hint style="info" %}
To use Bito-hosted LLM instead (no LLM keys required from you), contact [**support@bito.ai**](mailto:support@bito.ai) about the [Bito Enterprise Plan](https://bito.ai/pricing/).
{% endhint %}
{% endstep %}
{% endstepper %}

### b. System requirements

AI Architect can be installed on your local machine for individual use, or on a shared server that your entire team can connect to. When installed on a server, multiple developers can configure their AI coding tools (such as Claude Code, Cursor, Windsurf, etc.) to use the same MCP server, sharing access to the indexed codebase.

The AI Architect supports the following operating systems:

* **macOS**
* **Unix-based systems** (Ubuntu, Debian, RHEL, or similar distributions)
* **Windows (via WSL2)**

#### Shared servers (for team deployments)

* **On-premise physical servers** - Bare metal Linux servers in your data center
* **On-premise virtual machines** - VMware, Hyper-V, Proxmox, KVM, or other virtualization platforms
* **Cloud virtual machines** - AWS EC2, Google Cloud Compute Engine, Azure VMs, DigitalOcean Droplets, or similar cloud instances

{% stepper %}
{% step %}

### Hardware specifications

| Tier           | Repositories | vCPU      | Memory  | Storage   |
| -------------- | ------------ | --------- | ------- | --------- |
| **Minimum**    | up to 25     | 12 cores  | 24 GB   | 500 GB    |
| **Ideal**      | 25 – 100     | 16 cores  | 48 GB   | 1.5 TB    |
| **Enterprise** | 100+         | 32+ cores | 128+ GB | 2 – 4 TB+ |

{% hint style="info" %}
**Notes:**

* **Large repositories:** Increase memory and storage by 50% above the tier baseline when any single repository exceeds 5 GB.
* **Indexing workload:** Indexing generates transient CPU and memory peaks above steady-state usage. The resources listed above include the headroom required to absorb these peaks; do not size below the tier minimums.
* **Persistent storage:** Automatically configured during installation using Docker volumes or Kubernetes PersistentVolumeClaims.
* **Production security:** Restrict access via firewall rules and front the deployment with a reverse proxy (e.g., Nginx) with HTTPS enabled.
  {% endhint %}

AI Architect automatically detects available system resources during setup and configures optimal resource allocation for its Docker containers. For most deployments, the automatic configuration provides good performance. However, you can manually adjust these settings to fine-tune performance or accommodate specific workload requirements.

To view the active values:

```shellscript
grep -E '_(MEMORY|CPU)_LIMIT=' .env-bitoarch
```

To change a limit, edit the corresponding line in `.env-bitoarch` and apply:

```shellscript
bitoarch restart --force
```

Keep total allocated memory under \~75% of host memory to leave room for indexing bursts and the OS page cache.
{% endstep %}

{% step %}

### **WSL2 is required for Windows users**

If you're running Windows, Windows Subsystem for Linux 2 (WSL2) must be installed before proceeding.

**To install WSL2:**

1. Open PowerShell or Command Prompt as Administrator
2. Run the following command:

```shellscript
wsl --install
```

3. Set up your Ubuntu username and password when prompted.
   {% endstep %}

{% step %}

### Supported deployment modes

AI Architect supports two deployment modes. Choose the option that fits your infrastructure:

| Mode                  | Use case                                                                  | Requirements                                                                                                                                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Docker (Compose)**  | Single-host deployments, evaluation, smaller teams                        | Docker Engine and Docker Compose. [Install Docker Desktop](https://docs.docker.com/compose/install) — includes both.                                                                                                                                                                            |
| **Kubernetes (Helm)** | Production deployments requiring high availability and horizontal scaling | A pre-configured Kubernetes cluster on your infrastructure. For testing in a single laptop or local machine, create a local cluster using KIND (Kubernetes in Docker) — see the [Kubernetes Deployment Guide](https://github.com/gitbito/ai-architect/blob/main/docs/KUBERNETES_DEPLOYMENT.md). |
| {% endstep %}         |                                                                           |                                                                                                                                                                                                                                                                                                 |

{% step %}

### Docker Desktop / Docker Service (required)

**Docker Compose** is required to run AI Architect.

The easiest and recommended way to get Docker Compose is to install **Docker Desktop**.

Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Docker Compose prerequisites.

[**Install Docker Desktop**](https://docs.docker.com/compose/install)

**Configuration for Windows (WSL2):**

If you're using Windows with WSL2, you need to enable Docker integration with your WSL distribution:

1. Open **Docker Desktop**
2. Go to **Settings** > **Resources** > **WSL Integration**
3. Enable integration for your WSL distribution (e.g., Ubuntu)
4. Click **Apply**
   {% endstep %}

{% step %}

### Kubernetes cluster (required for Kubernetes based deployment method)

### For production environments:

During the setup process given below, if you choose [**Kubernetes**](https://kubernetes.io/docs/home/) as your deployment method, you must have an existing Kubernetes cluster set up and running.

Ensure your Kubernetes cluster have the following required tools:

* **kubectl** (Kubernetes command-line tool)
* **helm** (Kubernetes package manager)

### For testing and development:

For testing purposes, you can create a local Kubernetes cluster using KIND (Kubernetes in Docker). KIND allows you to run Kubernetes clusters in Docker containers.

**Install KIND:**

* **macOS:**

```shellscript
brew install kind kubectl helm
```

* **Linux:**

```shellscript
# KIND
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```

{% hint style="info" %}
**Note:** Before creating a KIND cluster, verify Docker has sufficient resources:

```shellscript
docker info --format 'CPUs={{.NCPU}} Mem={{.MemTotal}}'
```

\
**Required:** Minimum 4 CPUs and 8GB RAM

If resources are insufficient, increase Docker Desktop resources (Preferences → Resources) and restart Docker.
{% endhint %}

#### Setting up a test cluster with KIND

Create a KIND cluster with proper port mappings for service access:

```shellscript
kind create cluster --name bito-ai-architect --config - <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
  - containerPort: 443
    hostPort: 443
EOF
```

{% hint style="info" %}
**Note:** Services use ClusterIP for secure, internal-only access. External access is configured via Ingress Controller on ports 80/443.
{% endhint %}

#### Verify cluster

```shellscript
kubectl cluster-info --context kind-bito-ai-architect
kubectl get nodes
```

{% endstep %}
{% endstepper %}

## Installation guide

{% stepper %}
{% step %}

### Install AI Architect

Before proceeding with the installation, ensure **Docker Desktop / Docker Service** or **Kubernetes cluster** is running on your system. If it's not already running, launch it and wait for it to fully start before continuing.

Open your terminal:

* **Linux/macOS**: Use your standard terminal application
* **Windows (WSL2)**: Launch the **Ubuntu** application from the **Start menu**

Execute the installation command:

```bash
curl -fsSL https://aiarchitect.bito.ai/install.sh | bash
```

The installation script will:

* Download the latest Bito AI Architect package
* Extract it to your system
* Initialize the setup process

{% hint style="info" %}
**Installing dependencies:**

The AI Architect setup process will automatically check for required tools on your system. If any dependencies are missing (such as `jq`, which is needed for JSON processing), you'll be prompted to install them. Simply type `y` and press `Enter` to proceed with the installation.
{% endhint %}
{% endstep %}

{% step %}

### Configuration

[**Download the `install.default.yaml` file**](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/install.default.yaml), then rename it to `install.yaml` and place it at `~/.bitoarch/install.yaml` on your machine.

Open the file and update the configuration with your details by following the inline instructions.

Providing your Bito API key and Git credentials is required for the setup to work.

{% hint style="info" %}
**Note:** Refer to the [**Prerequisites section**](#prerequisites) for details on how to obtain these.
{% endhint %}

Alternatively, follow the on-screen prompts to configure your deployment. You'll provide the following information:

#### Select AI Architect deployment method:

Choose how you want to deploy Bito's AI Architect. We support two deployment methods:

1. **Docker Compose:** Deploys AI Architect using Docker Compose.
2. **Kubernetes:** Deploys AI Architect to an existing Kubernetes cluster. Choose this option if you have an existing Kubernetes cluster running and want to leverage Kubernetes for orchestration, scaling, and management.
   * **Note:** The setup script will automatically deploy AI Architect services to your Kubernetes cluster in the `bito-ai-architect` namespace.

{% hint style="info" %}
**If you have a Kubernetes cluster:**

1. Ensure it's running
2. Verify the current Kubernetes context: `kubectl config current-context`
3. Check connectivity: `kubectl cluster-info`

\
**If you don't have a Kubernetes cluster:**

1. Select Docker Compose (option 1)
   {% endhint %}

#### You'll need to provide the following details when prompted:

{% hint style="info" %}
**Note:** Refer to the [**Prerequisites section**](#prerequisites) for details on how to obtain these.
{% endhint %}

* **Bito API Key** (required) - Enter your Bito Access key and press Enter.
* **Git provider** (required):

  You'll be prompted to choose your Git provider:

  1. GitLab
  2. GitHub
  3. Bitbucket

  Enter the number corresponding to your Git provider and press Enter.
* **Is your Git provider self-hosted or cloud-based?**

  * Type `y` for enterprise/self-hosted instances (like `https://github.company.com`) and enter your custom domain URL
  * Type `n` for standard cloud providers (github.com, gitlab.com, bitbucket.org)

  Press Enter to continue.
* **Git Access Token** (required) - Enter personal access token for your Git provider and press Enter.
* **Configure LLM API keys** (required) - Choose which AI model provider(s) to configure:

  1. Anthropic
  2. OpenAI

  Enter the number corresponding to your AI model provider, then provide your API key when prompted.

  After adding a provider, you'll be asked: *"Do you want to configure another provider?"*

  * Type `y` to add additional providers (recommended for better coverage and fallback options).
  * Type `n` when you're done adding LLM providers.

  Press Enter to continue.
* **Generate a secure MCP access token?** - You'll be asked if you want Bito to create a secure token to prevent unauthorized access to your MCP server:

  * Type `y` to generate a secure access token (recommended)
  * Type `n` to skip token generation

  Press Enter to continue.
* **Configure SSO?** - Optionally enable Single Sign-On (SSO) authentication. Choose between **Bito authentication** (OAuth via your Bito workspace) or **Enterprise IdP** (SAML/OIDC via your corporate identity provider). See [SSO Authentication](https://github.com/gitbito/ai-architect#6-sso-authentication) for more details.
  {% endstep %}

{% step %}

### Add repositories

Once your Git account is connected successfully, Bito automatically detects your repositories and populates the `/usr/local/etc/bitoarch/.bitoarch-config.yaml` file with an initial list. Review this file to confirm which repositories you want to index — feel free to remove any that should be excluded or add others as needed. Once the list looks correct, save the file, and continue with the steps below.

{% hint style="info" %}
For versions older than 1.4.0, configuration file can be found in installation directory.
{% endhint %}

Below is an example of how the `.bitoarch-config.yaml` file is structured:

```yaml
repository:
  configured_repos:
    - namespace: your-org/repo-name-1
    - namespace: your-org/repo-name-2
    - namespace: your-org/repo-name-3
```

After updating the `.bitoarch-config.yaml` file, you have two options to proceed with adding your repositories for indexing:

1. **Auto Configure (recommended)**
   * Automatically saves the repositories and starts indexing
   * If needed, edit the repo list before selecting this option
2. **Manual Setup**
   * You have to manually update the configuration file and then start the indexing. Below we have provided complete details of the manual process.

Once you select an option, your **Bito MCP URL** and **Bito MCP Access Token** will be displayed. Make sure to store them in a safe place, you'll need them later when configuring MCP server in your AI coding agent (e.g., Claude Code, Cursor, Windsurf, GitHub Copilot (VS Code), etc.).

To manually apply the configuration, run this command:

```shellscript
bitoarch add-repos
```

{% endstep %}

{% step %}

### Start indexing

Once your repositories are configured, AI Architect needs to analyze and index them to build the knowledge graph. This process scans your codebase structure, dependencies, and relationships to enable context-aware AI assistance.

Start the indexing process by running:

```shellscript
bitoarch index-repos
```

{% hint style="info" %}
**Note:** Indexing process will take approximately 3-10 minutes per repository. Smaller repos take less time.
{% endhint %}

Once the indexing is complete, you can configure AI Architect MCP server in any coding or chat agent that supports MCP.
{% endstep %}

{% step %}

### Check indexing status

Run this command to check the status of your indexing:

```shellscript
bitoarch index-status
```

{% hint style="info" %}
**Example output:**

```
Configured Repositories:
  Total: 3

Repository Index Status:
State: ⏳ running
  Progress: 0 / 1 completed
  In Progress: 1

Workspace Index Progress:
State: ⏳ running
  Progress: 1 / 2 completed
  In Progress: 1

Overall Status: in-progress
```

**What each section represents:**

* **Configured Repositories:** Shows how many repositories are added in your config file for indexing.
* **Repository Index Status:** Shows the indexing progress for each individual repository.
* **Workspace Index Progress:** Shows the status of indexes that combine and process information across multiple repositories.
* **Overall Status:** Provides a single summary indicating whether indexing is still running, completed successfully, or failed.
  {% endhint %}
  {% endstep %}

{% step %}

### Check MCP server details

To manually check the MCP server details (e.g. **Bito MCP URL** and **Bito MCP Access Token**), use the following command:

```shellscript
bitoarch mcp-info
```

If you need to update your **Bito MCP Access Token**, use the following command:

```shellscript
bitoarch rotate-mcp-token <new-token>
```

{% hint style="info" %}
Replace `<new-token>` with your new secure token value.

**Important:** After rotating the token, you'll need to update it in all AI coding agents (Claude Code, Cursor, Windsurf, etc.) where you've configured this MCP server.
{% endhint %}
{% endstep %}
{% endstepper %}

## Update repository list and re-index

Edit `/usr/local/etc/bitoarch/.bitoarch-config.yaml` file to add/remove repositories.

```shellscript
vim /usr/local/etc/bitoarch/.bitoarch-config.yaml
```

To apply the changes, run this command:

```shellscript
bitoarch update-repos
```

Start the re-indexing process using this command:

```shellscript
bitoarch index-repos --only-new-repos
```

## SSO Authentication

AI Architect supports Single Sign-On (SSO) authentication for secure, multi-user access to the MCP server. SSO runs entirely on-prem — no authentication traffic leaves your environment except for identity provider federation (if Enterprise IdP is configured) and Bito API calls for SSO configurations.

#### Authentication modes

AI Architect supports three authentication modes:

| Mode                    | Provider            | How it works                                                                                                 |
| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Bearer Token**        | None (SSO disabled) | Static MCP access token passed in the request header. This is the default mode.                              |
| **Bito Authentication** | Bito                | OAuth flow validated via your Bito workspace. Ideal for teams already using Bito.                            |
| **Enterprise IdP**      | Enterprise IdP      | OAuth flow federated to your corporate SAML/OIDC identity provider (e.g., Okta, Azure AD, Google Workspace). |

{% hint style="info" %}
**Note:** If Enterprise IdP is selected but not yet configured, the system automatically falls back to Bito authentication until the IdP setup is complete.
{% endhint %}

#### Setting up SSO during installation

SSO is configured during the setup process. When prompted with **"Configure SSO?"**, you can choose one of the following options:

1. **Enterprise IdP (SAML/OIDC)**
   * The setup process generates a configuration URL for your identity provider
   * Open the URL in your browser and configure your IdP (e.g., Okta, Azure AD, Google Workspace) with the provided details. [Learn more](/ai-architect/single-sign-on-sso-integration.md#configure-your-identity-provider)
   * Return to the setup and verify the connection
2. **Bito Authentication**
   * Enables OAuth authentication using your Bito workspace credentials
   * No additional IdP configuration is required

{% hint style="info" %}
**Note:** You can also configure or reconfigure SSO at any time after installation using the `bitoarch sso setup` command.
{% endhint %}

#### Configuring SSO after installation

If you skipped SSO during initial setup or want to change your SSO configuration, you can use the following CLI commands:

**Set up or reconfigure SSO:**

```shellscript
bitoarch sso setup
```

This command will guide you through the SSO configuration process, including choosing between Enterprise IdP and Bito authentication.

**Check SSO status:**

```shellscript
bitoarch sso status
```

Displays the current SSO configuration and IdP connection status.

#### Managing SSO

**Enable SSO**

Re-enable SSO after it has been temporarily disabled:

```shellscript
bitoarch sso enable
```

**Disable SSO**

You can disable SSO either temporarily or permanently:

```shellscript
bitoarch sso disable
```

You will be prompted to choose:

* **Temporary disable** — Turns off SSO authentication but preserves your IdP configuration. You can re-enable it later with `bitoarch sso enable`.
* **Permanent disable** — Removes the IdP configuration entirely and resets SSO settings. You will need to run `bitoarch sso setup` again to reconfigure.

**Rotate SSO management key**

Rotate the SSO tenant management key for security purposes:

```shellscript
bitoarch sso rotate-key
```

{% hint style="info" %}
**Important:** After rotating the key, SSO services will restart automatically. Active sessions may need to re-authenticate.
{% endhint %}

#### SSO session configuration

SSO sessions are configurable with the following defaults:

| Setting                 | Default               | Description                                    |
| ----------------------- | --------------------- | ---------------------------------------------- |
| Session duration        | 360 minutes (6 hours) | How long a session remains valid               |
| Refresh token TTL       | 300 minutes (5 hours) | How long a refresh token remains valid         |
| Max concurrent sessions | 2                     | Maximum number of concurrent sessions per user |

{% hint style="info" %}
**Note:** Session settings can be customized through environment variables in the `.env-bitoarch` configuration file.
{% endhint %}

## Accessing services (Kubernetes-based deployment)

Port-forwards are exposed on all network interfaces (0.0.0.0) and are accessible from any machine on the network.

#### Local access (from the Kubernetes host machine)

```shellscript
curl http://localhost:5001/health          # Provider
curl http://localhost:5002/health          # Manager
curl http://localhost:5003/health          # Config
```

#### Network access (from other machines on your network)

Get the host machine's IP address:

```shellscript
kubectl get nodes -o wide
# Or: hostname -I (Linux) / ifconfig (macOS)
```

From another machine on the network:

```shellscript
curl http://<host-ip>:5001/health          # Provider
curl http://<host-ip>:5002/health          # Manager
curl http://<host-ip>:5003/health          # Config
curl http://<host-ip>:5005/health          # Tracker
```

#### Security considerations

> **Important security notes:**
>
> * Port-forwards use HTTP (not HTTPS) - traffic is unencrypted
> * Services are accessible from any machine that can reach the host
>
> **For production internet-facing deployments:**
>
> * Use firewall rules to restrict access to trusted IPs
> * Consider using Kubernetes Ingress with TLS/SSL
> * Implement VPN for remote access
> * Use network policies to limit pod-to-pod traffic

#### Alternative: Kubernetes Ingress (production)

For production deployments, configure a Kubernetes Ingress Controller with TLS/SSL instead of using port-forwards. This provides secure HTTPS access with proper certificate management.

## Setting up AI Architect MCP in coding agents

Now that AI Architect is installed and your repositories are indexed, the next step is to connect it to your AI coding tools (such as Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) through the Model Context Protocol (MCP).

#### Quick setup (recommended)

**Save time with our automated installer!** We provide a one-command setup that automatically configures AI Architect for all compatible AI coding tools on your system.

The automated installer will:

* Detect all supported AI tools installed on your system
* Configure them automatically with your MCP credentials
* Get you up and running in seconds instead of manually configuring each tool

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents.md) for automated setup across all your tools.

#### Manual setup

If you prefer hands-on control over your configuration or encounter issues with automated setup, we provide detailed step-by-step guides for each supported AI coding tool:

* [**Guide for Claude Code**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-claude-code.md)
* [**Guide for Cursor**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-cursor.md)
* [**Guide for Windsurf**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-windsurf.md)
* [**Guide for GitHub Copilot (VS Code)**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-github-copilot-vs-code.md)
* [**Guide for Junie (JetBrains)**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-junie-jetbrains.md)
* [**Guide for JetBrains AI Assistant**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-jetbrains-ai-assistant.md)

Each guide walks you through the complete manual configuration process for that specific tool.

## Configuring AI Architect for Bito AI Code Review Agent

Now that you have **AI Architect** set up, you can take your code quality to the next level by integrating it with [**Bito's AI Code Review Agent**](https://bito.ai/product/ai-code-review-agent/). This powerful combination delivers significantly more accurate and context-aware code reviews by leveraging the deep codebase knowledge graph that AI Architect has built.

**Why integrate AI Architect with AI Code Review Agent?**

When the AI Code Review Agent has access to AI Architect's knowledge graph, it gains a comprehensive understanding of your entire codebase architecture — including microservices, modules, APIs, dependencies, and design patterns.

This enables the AI Code Review Agent to:

* **Provide system-aware code reviews** - Understand how changes in one service or module impact other parts of your system
* **Catch architectural inconsistencies** - Identify when new code doesn't align with your established patterns and conventions
* **Detect cross-repository issues** - Spot problems that span multiple repositories or services
* **Deliver more accurate suggestions** - Generate fixes that are grounded in your actual codebase structure and usage patterns
* **Reduce false positives** - Better understand context to avoid flagging valid code as problematic

#### Getting started with AI Architect-powered code reviews

1. Log in to [**Bito Cloud**](https://alpha.bito.ai/home/welcome)
2. Open the [**AI Architect Settings**](https://alpha.bito.ai/home/ai-architect/settings?mode=self-hosted) dashboard.
3. In the **Server URL** field, enter your **Bito MCP URL**
4. In the **Auth token** field, enter your **Bito MCP Access Token**

**Need help getting started?** Contact our team at [**support@bito.ai**](mailto:support@bito.ai) to request a trial. We'll help you configure the integration and get your team up and running quickly.

## Insights

Insights features analyze commit history, Jira tickets, and Confluence docs to surface engineering activity metrics. They run independently of code indexing and are optional.

Insights provides deep visibility into your engineering organization by analyzing three data sources.

* **Git insights** analyze commit history to identify code health risks, knowledge concentration, development patterns, and team velocity.
* **Ticket tracker insights** analyze Jira tickets to understand strategic direction, feature intent, code stability risks, and architectural design issues.
* **Docs insights** analyze Confluence documentation to correlate design decisions with implementation.

Together, these insights help engineering leaders identify risks like bus factor vulnerabilities, quality concerns, delivery bottlenecks, and strategic alignment gaps.

#### Key insights metrics

**Health score**

The health score is an overall repository health metric ranging from 0 to 100, based on five weighted factors. A score of 90-100 indicates strong health across all dimensions with minimal risks. Scores between 70-89 suggest some concerns requiring attention, such as low test investment or moderate bus factor. Scores of 50-69 represent significant risks requiring immediate action, like a bus factor of 1 or zero test coverage. Below 50 indicates critical vulnerabilities threatening project continuity.

The five factors that contribute to the health score are:

* **Bus factor (30% weight)**: This measures knowledge concentration risk. A bus factor of 1 means a single contributor owns more than 50% of commits or code, creating a single-point-of-failure risk. A bus factor of 2-3 indicates moderate concentration that is manageable but fragile, while a bus factor of 4 or higher shows healthy distribution with well-distributed knowledge. When you encounter a bus factor of 1, implement pair programming, knowledge transfer sessions, and distribute code reviews to mitigate the risk.
* **Velocity trend (20% weight)**: This tracks development momentum based on commit frequency over time. An increasing trend indicates healthy engagement and momentum. While velocity should be monitored, small sample sizes can skew results, so track trends over time rather than relying on single data points.
* **Bugfix ratio (20% weight)**: This represents the percentage of commits that are bug fixes. Lower ratios between 0-15% indicate higher quality, while higher ratios may signal quality concerns. This metric helps you understand whether your team is spending too much time fixing bugs versus building new features.
* **Author diversity (15% weight)**: This measures the number of unique contributors to the repository. Higher diversity reduces knowledge concentration risk and indicates a healthier, more resilient team. Low diversity combined with a low bus factor is a warning sign that knowledge is too concentrated.
* **Test investment (15% weight)**: This tracks the percentage of commits dedicated to testing. Industry best practice is 15-20%. Zero test investment, as seen in some sample data, indicates unquantified risk and reliance on manual verification. Prioritize test coverage, especially for high-churn files, to improve this metric.

**Hotspots**

Hotspots identify files with high churn rates that may indicate instability or areas needing refactoring. Each hotspot shows the change count, unique authors, churn score, line ownership percentages, and rename history count. Hotspots are categorized by severity: critical (top 5%), high (top 15%), medium (top 40%), and low (bottom 60%). Critical hotspots are files in the highest churn percentile and should be prioritized for refactoring or test coverage. High hotspots have elevated churn and should be monitored closely. Medium hotspots represent moderate churn, which is normal for active development areas. Low hotspots are stable files with low risk.

**Themes**

Themes are thematic groupings of related work across directories. Each theme includes the commit count, impact level, tech stack identification, representative commits, dark work analysis, and intent breakdown. Themes help you understand what types of work are happening in your repository and how they relate to each other. For example, a theme like "Notification Delivery Hardening" might represent a coordinated effort to enhance reliability and observability. The dark work component of themes identifies commits not linked to Jira tickets, which may represent untracked feature work, legitimate infrastructure changes, or work requiring investigation.

**Dark work analysis**

Dark work identifies commits not linked to Jira tickets. A high dark work percentage above 30% indicates significant work not tracked in tickets, which may suggest process gaps. A medium percentage of 10-30% shows some untracked work that should be reviewed to determine if it represents legitimate infrastructure changes. A low dark work percentage below 10% indicates good tracking discipline where most work is ticket-linked. Understanding dark work helps you improve ticket tracking discipline and ensure all important work is properly tracked and planned.

**Contributor analysis**

Contributor analysis provides per-author breakdowns including commit count and percentage, archetype classification (builder, maintainer, etc.), top files worked on, intent mix (feature vs. docs vs. refactor), and active period. This helps you understand who is doing what in your repository and identify knowledge concentration risks. For example, if one contributor has 75% of commits and is classified as the primary builder, this represents a significant bus factor risk that should be addressed through knowledge transfer and ownership distribution.

**Feature intent reports**

When you enable ticket tracker insights, you receive feature intent reports that provide strategic analysis including product direction, investment portfolio by cluster and category, top strategic initiatives with detailed context, cross-initiative dependency mapping, epic health dashboard with completion percentages, and requirements quality scoring. These reports help you understand strategic alignment, identify critical path blockers, and assess the quality of your requirements. Each initiative includes context on WHY it matters, WHAT it involves, WHERE it's being implemented, current STATUS, associated RISKS, DEPENDENCIES, key quotes from stakeholders, customer impact, success metrics, and confidence levels.

**Code stability risk reports**

Code stability risk reports provide technical risk analysis including a risk matrix by severity (CRITICAL, HIGH, MEDIUM, LOW), recurring bug patterns with confidence scores and root cause attribution, per-repository incident analysis with learnings, silent failure inventory, regression-prone areas, and per-repository risk profiles with 6-dimensional health scoring. These reports help you identify recurring bug patterns like self-hosted deployment fragility, concurrency bottlenecks, LLM provider fallback issues, code quality gaps, and security vulnerabilities. The reports also include failure cascade diagrams showing how failures propagate through the system, which is valuable for understanding systemic risks.

**Architecture & design risk audits**

Architecture and design risk audits provide structural analysis including repository risk maps with bug counts, bug density by cluster, per-repository risk profiles with health scores, dimensions, dependencies, known issues, architectural patterns, and bottlenecks. The audits also include failure cascade diagrams, design debt inventory with effort sizing, and customer impact mapping. These audits help you understand which repositories have the highest risk, identify design debt that needs to be addressed, and understand how architectural decisions impact system reliability.

#### During installation

The installer prompts for each insights feature. You can pre-seed configuration via `~/.bitoarch/install.yaml` to skip prompts by uncommenting the `insights:` section and filling in values.

#### After installation

```shellscript
bitoarch insights enable git              # Enable commit-history insights (reuses git credentials)
bitoarch insights enable ticket-tracker   # Enable Jira insights (prompts for Jira base URL + email + API token)
bitoarch insights enable docs             # Enable Confluence insights (prompts for Confluence URL + email + API token)
bitoarch insights run                     # Trigger analysis
bitoarch insights status                  # Check what's enabled
```

#### Managing Jira project scope

```shellscript
bitoarch insights discover-tracker-projects   # Interactive selection from accessible projects
bitoarch insights tracker-projects list       # Show current project keys
bitoarch insights tracker-projects add PROJ   # Add a project key
bitoarch insights tracker-projects remove PROJ
```

#### Credential rotation

```shellscript
bitoarch update-ticket-tracker    # Re-enter Jira credentials (validates before saving)
bitoarch update-docs              # Re-enter Confluence credentials
```

{% hint style="info" %}
**Atlassian API tokens**

Generate API tokens at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Provide the Confluence base URL without `/wiki` — the platform normalizes it automatically.
{% endhint %}

#### Best practices

Enable all three insight sources (Git, Jira, Confluence) for comprehensive visibility.

Review health scores weekly to catch emerging risks early. Address bus factor risks through knowledge transfer before they become critical. Use dark work analysis to improve ticket tracking discipline.

Correlate Git insights with Jira insights to understand implementation versus planning alignment.

Track trends over time—velocity trends, bug ratios, and health scores are more valuable as time-series data than as single snapshots. Use insights for planning—feature intent reports and dependency mapping inform roadmap decisions. Prioritize based on severity, focusing on CRITICAL and HIGH severity findings first.

## Upgrading AI Architect

Upgrade your AI Architect installation to the latest version while preserving your data and configuration. The upgrade process:

* Automatically detects your current version
* Downloads and extracts the new version
* Migrates your configuration and data
* Seamlessly transitions to the new version
* Preserves all indexed repositories and settings

#### Upgrade instructions

#### Option 1: Upgrade from within your installation (Recommended)

If you're running **version 1.1.0 or higher**, navigate to your current installation directory and run:

```shellscript
cd /path/to/bito-ai-architect
```

```shellscript
./scripts/upgrade.sh --version=latest
```

#### Option 2: Upgrade from external location

If you need to run the upgrade from outside your installation directory (useful for **version 1.0.0**), use the `--old-path` parameter:

```shellscript
# Download the standalone upgrade script
curl -O https://github.com/gitbito/ai-architect/blob/main/upgrade.sh
chmod +x upgrade.sh

# Run upgrade with explicit path
./upgrade.sh --old-path=/path/to/bito-ai-architect --version=latest
```

#### Upgrade parameters

The upgrade script supports the following parameters:

```shellscript
# Description
--version=VERSION

# Upgrade to specific version
--version=latest

# Upgrade from custom URL or file
--url=file:///path/to/package.tar.gz

# Specify installation path (required if running outside installation directory)
--old-path=/opt/bito-ai-architect

# Show help message
--help
```

{% hint style="info" %}
**Your data is safe:** All repositories, indexes, API keys, and settings are automatically preserved during upgrade.
{% endhint %}

{% hint style="info" %}
**Important:** You can only upgrade within the same deployment type. To switch from **Docker Compose** to **Kubernetes** or vice versa, you must use the `bitoarch reset` command, which will result in data loss.
{% endhint %}

## Uninstall

```shellscript
bitoarch reset       # wipe containers/volumes/config; keep install dir
bitoarch uninstall   # full removal (+ install dir + ~/.bitoarch/install.yaml)
```

{% hint style="info" %}
Docker images are kept — `docker image prune` to reclaim.
{% endhint %}

{% hint style="info" %}
Alternatively, you can also use the following curl command to uninstall AI Architect:

```shellscript
curl -fsSL https://aiarchitect.bito.ai/uninstall.sh | bash
```

{% endhint %}

## Troubleshooting guide

```shellscript
# Check all services
bitoarch status
bitoarch health --verbose

# View full configuration
bitoarch show-config --raw

# Test MCP connection
bitoarch mcp-test

# Check indexing status with details
bitoarch index-status --raw

# Check setup log
tail -f setup.log

# Local log files
tail -f var/logs/cis-provider/provider.log
tail -f var/logs/cis-manager/manager.log

# Services stopped after reboot
bitoarch start

# Complete logs
bitoarch logs

# Reset installation (removes all data and configuration)
bitoarch reset

# To stop all the services
bitoarch stop

# Restart service (for env based config updates)
bitoarch restart --force

# Force pull latest images based on service-versions.json and restart services
bitoarch update
```

#### Commands specific to Kubernetes-based deployment

```shellscript
# Check Kubernetes pod status
# All pods should show "Running" status.
kubectl get pods -n bito-ai-architect

# Check detailed information about a specific Kubernetes pod
kubectl describe pod <pod-name> -n bito-ai-architect

# Access Kubernetes pod shell
kubectl exec -it -n bito-ai-architect \
  $(kubectl get pod -n bito-ai-architect -l app.kubernetes.io/component=provider -o jsonpath='{.items[0].metadata.name}') \
  -- /bin/sh

# Stop KIND cluster (preserves data)
docker stop bito-ai-architect-control-plane

# Start KIND cluster again
docker start bito-ai-architect-control-plane

# Delete KIND cluster completely
kind delete cluster --name bito-ai-architect

# View Provider service logs:
kubectl logs -n bito-ai-architect -l app.kubernetes.io/component=provider --tail=100 -f

# View Manager service logs:
kubectl logs -n bito-ai-architect -l app.kubernetes.io/component=manager --tail=100 -f
```

## Available commands

For complete reference of AI Architect CLI commands, refer to [Available commands](/ai-architect/installation/install-ai-architect-self-hosted/available-commands.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bito.ai/ai-architect/installation/install-ai-architect-self-hosted.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.