Operations & troubleshooting

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

Quick reference

Task	Command
Check service health	bitoarch status · bitoarch health
Check indexing progress	bitoarch index-status
Add or remove a repository	bitoarch add-repo <ns> · bitoarch remove-repo <ns>
Rotate a credential	update-api-key · update-git-creds · rotate-mcp-token
View MCP connection details	bitoarch mcp-info
Upgrade the platform	bitoarch upgrade
Diagnose an issue	bitoarch diagnose
Create a support bundle	bitoarch diagnose --bundle

Manage repositories

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

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.

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.

Requires the Bito Enterprise Plan. Full walkthrough: Integrating with Bito's AI Code Review Agent.

Upgrade

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

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

Stop, start, uninstall

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

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.

---

Troubleshooting

Start with diagnose

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

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

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

Kubernetes diagnostics

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

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 [e-mail].