Standalone mode (for individuals)

Set up AI Architect on your local machine (e.g. Laptop) for quick evaluation

Bito's AI Architect can be self-hosted in two ways depending on your use case.

• Enterprise mode — (for teams to share the same indexed codebase, or you require Kubernetes, SSO, or dedicated server infrastructure. See the Enterprise mode setup guide.)

• Standalone mode — (for individuals to quickly try out AI Architect on your own machine)

This guide covers Standalone mode — a lightweight, single-machine install for individual developers who want to get up and running quickly, without provisioning shared infrastructure or coordinating with a DevOps team. It runs entirely in Docker on your local machine and automatically registers itself with your coding agents.

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 local machine, connected to your Git repositories, and ready to integrate with AI coding tools like Claude Code, Cursor, Windsurf, GitHub Copilot, etc. through the Model Context Protocol (MCP).

Prerequisites

a. Required accounts and tokens

1

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, and create an access key from Settings -> Advanced Settings

• View Guide

2

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.

3

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

2. GitLab Personal Access Token: To use GitLab repositories with AI Architect, a token with API access is required.

   • View Guide

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

   2. Bitbucket Self-Hosted (HTTP Access Token): You must provide both your token and username.

      • View Guide

4

LLM API keys

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

We suggest you provide API keys for both Anthropic and Grok LLMs, as that provides the best coverage and the best cost of indexing.

Bito will use best-in-class AI models from Anthropic and Grok together to index your codebase. It will cost you approximately USD $0.20 - $0.40 per MB of indexable code (we do not index binaries, TARs, zips, images, etc). If you provide only an Anthropic API key without Grok, your indexing costs will be significantly higher, approximately USD $1.00 - $1.50 per MB of indexable code.

b. System requirements

The AI Architect standalone mode requires the following specs:

1

Hardware specifications

	Minimum	Recommended
Operating System	macOS 12+, Ubuntu 20.04+	Same
Docker	Desktop 20.10+ with Compose v2	Docker Desktop 4.x+
Docker RAM	6 GB	8 GB+
Docker CPUs	3	4+
Disk	10 GB	50 GB+
Ports	5001–5005 free on localhost	Same

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.

You can customize resource limits by editing the .env-bitoarch file and run the command bitoarch restart --force to update the allocation. The following environment variables can be manually configured to control resource allocation.

CIS_PROVIDER_MEMORY_LIMIT=1g
CIS_MANAGER_MEMORY_LIMIT=2g
CIS_CONFIG_MEMORY_LIMIT=512m
MYSQL_MEMORY_LIMIT=2g
CIS_TRACKER_MEMORY_LIMIT=512m


CIS_PROVIDER_CPU_LIMIT=1.0
CIS_MANAGER_CPU_LIMIT=2.0
CIS_CONFIG_CPU_LIMIT=0.5
MYSQL_CPU_LIMIT=1.0
CIS_TRACKER_CPU_LIMIT=0.5

2

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

Installation guide

1

Install AI Architect

Before proceeding with the installation, ensure Docker Desktop / Docker Service 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

Execute the installation command:

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

Note: To install self-hosted AI Architect for your team, refer to Enterprise mode setup guide.

The installation script will:

• Download the latest Bito AI Architect package

• Extract it to your system

• Initialize the setup process

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.

2

Configuration

Download the install.default.yaml file, 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.

Note: Refer to the Prerequisites section for details on how to obtain the required items.

3

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.

For versions older than 1.4.0, configuration file can be found in installation directory.

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

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:

bitoarch add-repos

4

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:

bitoarch index-repos

Note: Indexing process will take approximately 3-10 minutes per repository. Smaller repos take less time.

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

5

Check indexing status

Run this command to check the status of your indexing:

bitoarch index-status

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.

6

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:

bitoarch mcp-info

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

bitoarch rotate-mcp-token <new-token>

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.

7

Connect MCP client

Standalone mode runs MCP over HTTPS at https://localhost:5001/mcp with a local mkcert-signed leaf cert. The cert is per-host (issued at install time, never reused across machines); mkcert is auto-downloaded if not on PATH.

The install bootstrap auto-registers the local MCP into every detected coding agent (Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains AI Assistant) and prints a one-time IDE-restart prompt for each. After restart, your IDE connects without further config.

bitoarch mcp-info         # URL + token + auth mode
bitoarch mcp-install      # re-run agent registration (e.g., after installing a new IDE)
bitoarch mcp-cert status  # cert verdict, days remaining, scheduler state

The cert auto-renews daily via an OS-native scheduler (launchd on macOS, systemd-user timer or crontab on Linux). Override the renew time via bitoarch mcp-cert schedule HH:MM. To opt out, set BITOARCH_CERT_AUTO_RENEW=false in .env-bitoarch and re-run bitoarch install.

Manual config fallback (if your IDE isn't auto-detected, or for the Claude Desktop main chat which doesn't read ~/.claude.json):

{
  "mcpServers": {
    "BitoAIArchitect": {
      "url": "https://localhost:5001/mcp",
      "headers": { "Authorization": "Bearer <Your-Bito-MCP-Access-Token>" }
    }
  }
}

Note: Replace <Your-Bito-MCP-Access-Token> with the Bito MCP Access Token you received after completing the AI Architect setup.

Update repository list and re-index

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

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

To apply the changes, run this command:

bitoarch update-repos

Start the re-indexing process using this command:

bitoarch index-repos --only-new-repos

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

2. Open the AI Architect Settings 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 [email protected] to request a trial. We'll help you configure the integration and get your team up and running quickly.

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.7.1 or higher, run the following command to upgrade AI Architect to latest version:

bitoarch upgrade                    # latest

Or you can also upgrade to a specific version:

bitoarch upgrade --version=1.8.0    # specific version

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:

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

# 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

Your data is safe: All repositories, indexes, API keys, and settings are automatically preserved during upgrade.

Uninstall

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

Docker images are kept — docker image prune to reclaim.

Alternatively, you can also use the following curl command to uninstall AI Architect standalone mode:

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

Troubleshooting guide

# "Docker has only X GB RAM allocated (6 GB recommended)"
# → Docker Desktop → Settings → Resources → Memory → 6 GB+ → Apply & Restart

# "Port 5001 is in use" — edit ~/.bitoarch/install.yaml BEFORE install:
# ports: { cis_provider: 6001, cis_manager: 6002, cis_config: 6003, mysql: 6004, cis_tracker: 6005 }

# "bitoarch: command not found" right after install
source ~/.zshrc        # or ~/.bashrc

# AI Architect not responding after a system restart
# If AI Architect stops responding after your machine has been restarted or shut down, the underlying Docker containers may have stopped. To restore:
# 1. Start Docker :  Make sure Docker Desktop (or your Docker service) is running before doing anything else.
# 2. Start the AI Architect services.
bitoarch start

# Indexing stuck
bitoarch index-status
bitoarch logs cis-manager
bitoarch stop-indexing && bitoarch index-repos

# Corporate proxy — before install
export HTTP_PROXY=http://proxy:8080 HTTPS_PROXY=http://proxy:8080
export NO_PROXY=localhost,127.0.0.1,ai-architect-config,ai-architect-manager,ai-architect-provider
curl -fsSL https://aiarchitect.bito.ai/standalone/install.sh | bash

# Defensive uninstall (CLI broken)
curl -fsSL https://aiarchitect.bito.ai/standalone/uninstall.sh | bash

Available commands

For complete reference of AI Architect CLI commands, refer to Available commands.

Standalone-only commands

These exist only when MCP_AUTO_INSTALL=true in .env-bitoarch (set automatically by the Standalone install bootstrap). On Enterprise installs they are hidden from bitoarch --help and refuse to run.

Command	Description
bitoarch mcp-install [--email <addr>]	Re-register the local MCP with detected coding agents (Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains AI Assistant). Run after installing a new IDE.
bitoarch mcp-cert status	Cert verdict (✓/⚠/✗), days remaining, paths, scheduler state.
bitoarch mcp-cert renew	Force re-issue cert and restart cis-provider.
bitoarch mcp-cert renew --check	Renew only if expiring within 60 days (this is the cron entry point — not normally run by hand).
bitoarch mcp-cert paths	Print cert path.
bitoarch mcp-cert schedule	Show current renew time + scheduler state.
bitoarch mcp-cert schedule HH:MM	Set the daily auto-renew time (24h). Persists to .env-bitoarch as BITOARCH_CERT_RENEW_TIME.

The cert auto-renews daily via an OS-native scheduler (launchd on macOS, systemd-user timer on Linux/WSL, crontab fallback). To opt out, add BITOARCH_CERT_AUTO_RENEW=false to .env-bitoarch and re-run bitoarch install.

Common commands

bitoarch status            # service health
bitoarch logs              # tail logs (append a service name to filter)
bitoarch mcp-info          # URL + token + auth mode
bitoarch mcp-test          # end-to-end MCP check
bitoarch mcp-install       # re-register MCP with installed coding agents (Standalone-only)
bitoarch mcp-cert --help   # cert lifecycle: status / renew / schedule (Standalone-only)

bitoarch stop
bitoarch start
bitoarch restart
bitoarch restart --force   # reload env + recreate containers
bitoarch update            # refresh images per versions/service-versions.json
bitoarch upgrade           # blue/green tarball swap

bitoarch config edit
bitoarch config edit repos
bitoarch config path

bitoarch reset             # wipe state; keep install dir
bitoarch uninstall         # full removal