# Standalone mode (for individuals) [Bito's AI Architect](/ai-architect/overview.md) 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](/ai-architect/installation/install-ai-architect-self-hosted.md).) * **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 {% 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. 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. **An Anthropic API key is required**. AI Architect uses best-in-class AI models to index your codebase. You can optionally also provide an OpenAI API key. 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). {% endstep %} {% endstepper %} ### b. System requirements The AI Architect standalone mode requires the following specs: {% stepper %} {% step %} ### 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. ```dotenv 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 ``` {% 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) {% endstep %} {% endstepper %} ## Installation guide {% stepper %} {% step %} ### 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: ```bash curl -fsSL https://aiarchitect.bito.ai/standalone/install.sh | bash ``` {% hint style="info" %} **Note:** To install self-hosted AI Architect for your team, refer to [Enterprise mode setup guide](/ai-architect/installation/install-ai-architect-self-hosted.md). {% endhint %} 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 the required items. {% endhint %} {% 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 ``` {% hint style="info" %} Replace `` 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 %} {% step %} ### 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. ```shellscript 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 ``` {% hint style="info" %} 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`. {% endhint %} **Manual config fallback** (if your IDE isn't auto-detected, or for the Claude Desktop main chat which doesn't read `~/.claude.json`): ```json {  "mcpServers": {    "BitoAIArchitect": {      "url": "https://localhost:5001/mcp",      "headers": { "Authorization": "Bearer " }   } } } ``` {% hint style="info" %} **Note:** Replace `` with the **Bito MCP Access Token** you received after completing the AI Architect setup. {% 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 ``` ## 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. ## 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 %} ## 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 standalone mode: ```shellscript curl -fsSL https://aiarchitect.bito.ai/standalone/uninstall.sh | bash ``` {% endhint %} ## Troubleshooting guide ```shellscript # "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](/ai-architect/installation/install-ai-architect-self-hosted/available-commands.md). #### 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 ]` | 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 ```shellscript 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 config edit bitoarch config edit repos bitoarch config path bitoarch reset # wipe state; keep install dir bitoarch uninstall # full removal ``` --- # 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/standalone-mode-for-individuals.md?ask= ``` 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.