> For the complete documentation index, see [llms.txt](https://docs.bito.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bito.ai/ai-architect/installation/install-ai-architect-self-hosted/operations-and-troubleshooting.md).

# Operations & troubleshooting

Common tasks for managing a running deployment (Standalone or Enterprise). For every command, see the CLI command reference.

## Quick reference

<table data-search="false"><thead><tr><th>Task</th><th>Command</th></tr></thead><tbody><tr><td>Check service health</td><td><code>bitoarch status</code> · <code>bitoarch health</code></td></tr><tr><td>Check indexing progress</td><td><code>bitoarch index-status</code></td></tr><tr><td>Add or remove a repository</td><td><code>bitoarch add-repo &#x3C;ns></code> · <code>bitoarch remove-repo &#x3C;ns></code></td></tr><tr><td>Rotate a credential</td><td><code>update-api-key</code> · <code>update-git-creds</code> · <code>rotate-mcp-token</code></td></tr><tr><td>View MCP connection details</td><td><code>bitoarch mcp-info</code></td></tr><tr><td>Upgrade the platform</td><td><code>bitoarch upgrade</code></td></tr><tr><td>Diagnose an issue</td><td><code>bitoarch diagnose</code></td></tr><tr><td>Create a support bundle</td><td><code>bitoarch diagnose --bundle</code></td></tr></tbody></table>

## Manage repositories

```shellscript
bitoarch add-repo myorg/repo        # add one repository
bitoarch remove-repo myorg/repo     # remove one repository
bitoarch config edit repos          # edit the repository list
bitoarch add-repos                  # apply the edited list
bitoarch index-repos --only-new-repos   # index newly added repositories only
bitoarch index-status               # in_progress | completed | failed
```

Indexing runs one job per workspace at a time. Schedule recurring re-indexing with `bitoarch create-index-scheduler`.

## Rotate credentials

```shellscript
bitoarch update-api-key      # rotate the Bito API key
bitoarch update-git-creds    # rotate the Git provider token
bitoarch update-llm-config   # change or rotate LLM provider configuration
bitoarch rotate-mcp-token    # rotate the MCP access token
```

After rotating the MCP token, update the token in each connected AI coding agent.

## Connect the AI Code Review Agent

Give Bito's AI Code Review Agent your AI Architect context for codebase-aware, cross-repository reviews:

1. Log in to [Bito Cloud](https://alpha.bito.ai/home/welcome).
2. Open the **AI Architect Settings** dashboard.
3. Enter your **MCP URL** in the Server URL field (`bitoarch mcp-info`).
4. Enter your **MCP access token** in the Auth token field.

{% hint style="info" %}
Requires the Bito Enterprise Plan. Full walkthrough: [Integrating with Bito's AI Code Review Agent](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-bitos-ai-code-review-agent.md).
{% endhint %}

## Upgrade

```shellscript
bitoarch upgrade                   # upgrade to the latest version
bitoarch upgrade --version=1.8.0   # upgrade to a specific version
```

{% hint style="info" %}
`upgrade` performs a blue/green swap, so **your indexed data, configuration, and `.env-bitoarch` are preserved automatically** with no manual backup needed. The previous install stays on disk until you remove it, and rollback is not supported once an upgrade succeeds. Upgrades must stay within the same deployment type (Docker Compose or Kubernetes).
{% endhint %}

## Stop, start, uninstall

```shellscript
bitoarch stop        # stop services, keep data
bitoarch start       # start stopped services
bitoarch restart     # restart services
bitoarch reset       # remove services, volumes, and configuration (keeps the install directory)
bitoarch uninstall   # full removal
```

{% hint style="info" %}
`reset` and `uninstall` **delete your indexed data**, and switching between Docker Compose and Kubernetes requires a `reset` followed by a full re-index. Docker images are kept: run `docker image prune` to reclaim disk space. On Kubernetes, `uninstall` removes the Helm release and namespace.
{% endhint %}

***

## Troubleshooting

#### Start with diagnose

```shellscript
bitoarch diagnose                      # pass/warn/fail sweep across all sections
bitoarch diagnose --section services   # limit to one section
bitoarch diagnose --bundle             # create a redacted support bundle (.tar.gz)
```

Sections: `prereqs`, `install`, `filesystem`, `config`, `services`, `connectivity`, `cert`.

#### Manual checks

```shellscript
bitoarch health                  # per-service health
bitoarch show-config             # current indexing configuration
bitoarch index-status            # indexing progress and state
bitoarch logs                    # tail logs from all services
bitoarch logs cis-manager        # tail logs from one service
```

#### Common issues

<table data-search="false"><thead><tr><th>Symptom</th><th>Likely cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>command not found: bitoarch</code></td><td>Shell PATH not reloaded</td><td><code>source ~/.zshrc</code></td></tr><tr><td>"Docker has only X GB RAM"</td><td>Docker under-allocated</td><td>Docker Desktop → Resources → Memory → 6 GB+ → Restart</td></tr><tr><td>"Port 5001 is in use"</td><td>Port conflict</td><td>Pre-seed custom ports in <code>install.yaml</code> before installing, or run <code>bitoarch config edit env</code> and <code>bitoarch restart --force</code> after</td></tr><tr><td>Services stopped after reboot</td><td>Not auto-started</td><td><code>bitoarch start</code></td></tr><tr><td>Indexing stuck</td><td>Stalled job</td><td><code>index-status</code> → <code>logs cis-manager</code> → <code>stop-indexing &#x26;&#x26; index-repos</code></td></tr><tr><td>MCP client cannot connect</td><td>Wrong URL/token or certificate</td><td><code>mcp-info</code>, then <code>mcp-test</code>. Standalone: <code>mcp-cert status</code></td></tr><tr><td>Pod <code>CrashLoopBackOff</code> (K8s)</td><td>Startup failure</td><td>Identify the restart reason and the crashed container's error output (see Kubernetes diagnostics below)</td></tr></tbody></table>

#### Kubernetes diagnostics

```shellscript
kubectl get pods -n bito-ai-architect                 # pod status at a glance
kubectl describe pod <pod> -n bito-ai-architect       # events and restart reason (for example OOM, image pull)
kubectl logs <pod> -n bito-ai-architect --previous    # error output from the crashed container
```

#### Escalate to Bito support

```shellscript
bitoarch diagnose --bundle                 # redacted .tar.gz (saved to ~/.bitoarch/diagnostics/)
bitoarch diagnose --bundle --output <dir>   # write it elsewhere
```

The bundle contains system information, logs, configuration, database health, indexing state, and local usage events. **Secrets and tokens are masked**, and triage fields such as email and IP are retained. Attach it to your ticket at [**support@bito.ai**](mailto:support@bito.ai).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.bito.ai/ai-architect/installation/install-ai-architect-self-hosted/operations-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.