Enterprise deployment

Run AI Architect as a shared service for your team, on a server or cluster. Docker Compose suits a single shared host. Kubernetes suits production, high availability, and horizontal scaling.

Evaluating on your workstation? The Standalone deployment is faster (one command, about 5 to 10 minutes).

Before you begin

Have the following ready. See Prerequisites & requirements for creation links, hardware sizing, and, importantly, the network and firewall allowlist your deployment must reach.

Requirement

Notes

Bito API key

alpha.bito.ai/home/advanced

Git provider token (PAT)

GitHub, GitLab, Bitbucket, or Azure DevOps

Deployment tooling

Docker Compose or Kubernetes (tabs below)

Docker Desktop 20.10+ with Compose v2
Ports 5001-5006 free on the host (or customize)

kubectl and helm 3.x installed locally
A reachable cluster (kubectl cluster-info succeeds)
An Ingress Controller (nginx, traefik, or similar), or port-forward for testing

No cluster yet? Test on a local KIND cluster

To evaluate the Kubernetes path locally, create a KIND cluster (requires 4 CPUs and 8 GB RAM):

# Install tools (macOS)
brew install kind kubectl helm

# Create a cluster with ingress port mappings
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

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

# Tear down when done
kind delete cluster --name bito-ai-architect

Pre-seed your configuration (optional)

To install without prompts, create ~/.bitoarch/install.yaml from the full template, install.default.yaml, which covers every option: deployment method, Bito key, Git, LLM provider keys, Insights, ports, and SSO. Skip this step to install interactively, and the installer asks for each value instead.

Install and index

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

If you pre-seeded your configuration, the installer runs without prompts. Otherwise, it asks for the deployment method (Docker Compose or Kubernetes), your Bito API key, and your Git provider and token.

The installer validates prerequisites, generates secure secrets (database passwords, JWT, MCP token), deploys the services, and installs the bitoarch CLI globally. It then fetches your repository list from your Git provider and asks how to proceed:

Auto (recommended): saves the fetched repository list, starts indexing automatically (about 3-10 minutes per repository), and prompts you to set up SSO before finishing.
Manual: follow the steps shown in the terminal to complete configuration. In summary:
1. bitoarch config edit repos (review or trim the list, as each indexed repository consumes LLM tokens)
2. bitoarch add-repos (apply the list)
3. bitoarch index-repos (start indexing)
4. bitoarch sso setup (configure SSO, optional)

On success, the installer prints your MCP URL and access token.

Custom ports? Services default to 5001-5006. To change them, run bitoarch config edit env, set the values below, then run bitoarch restart --force:

CIS_PROVIDER_EXTERNAL_PORT=5001   # MCP server
CIS_MANAGER_EXTERNAL_PORT=5002
CIS_CONFIG_EXTERNAL_PORT=5003
MYSQL_EXTERNAL_PORT=5004
CIS_TRACKER_EXTERNAL_PORT=5005
TEMPORAL_EXTERNAL_PORT=5006

Expose the MCP endpoint

Your team connects through the MCP server. Expose only that service, and keep the rest internal.

Services expose ports 5001-5006 on the host. The MCP server is on 5001. For team access, place a TLS reverse proxy in front of port 5001. Keep ports 5002-5006 internal.

bitoarch status
bitoarch mcp-info          # MCP URL + token

Services run in the bito-ai-architect namespace as ClusterIP (internal only). Expose the MCP server through an Ingress Controller on ports 80/443 for production. Use port-forward only for testing.

# Via ingress (recommended): health of each service
curl http://your-domain.com/api/provider/health
curl http://your-domain.com/api/manager/health
curl http://your-domain.com/api/config/health
curl http://your-domain.com/api/tracker/health

# Via port-forward (testing only)
kubectl port-forward svc/ai-architect-provider 8080:8080 -n bito-ai-architect

# In-cluster (pod-to-pod)
kubectl run curl --image=curlimages/curl -it --rm --restart=Never -n bito-ai-architect -- \
  curl http://ai-architect-provider:8080/health

# Inspect pods
kubectl get pods -n bito-ai-architect

Connect your team

Retrieve the MCP URL and token, then share the connection details with your team:

bitoarch mcp-info

Each user connects their tool with the Quick MCP integration with AI coding agents installer (Claude Code, Cursor, Windsurf, VS Code, JetBrains).

Using SSO? When SSO is enabled, users authenticate through your identity provider instead of the shared access token. See Manage authentication below and the SSO integration guide.

Verify the installation

bitoarch status        # all services healthy
bitoarch index-status  # reaches "completed"
bitoarch mcp-test      # end-to-end MCP check passes

Setup is complete. Ask your AI coding agent a cross-repository question to confirm it is using AI Architect context.

Manage authentication (optional)

SSO setup is offered during installation (Step 2). By default, MCP uses a static bearer token. To enable or change user-level authentication later:

bitoarch sso setup     # Enterprise IdP (SAML/OIDC) or Bito Auth
bitoarch sso status

Full walkthrough: Single Sign-On (SSO) integration.

Next steps

Optional: connect the AI Code Review Agent for codebase-aware reviews, or enable Insights.

Secrets live in .env-bitoarch (bitoarch config path env): your API key, Git token, MCP token, database passwords, and JWT secret. This file is preserved automatically across upgrades and removed on uninstall.

Last updated 1 month ago