> 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/enterprise-deployment.md).

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

{% hint style="info" %}
Evaluating on your workstation? The [Standalone deployment](/ai-architect/installation/install-ai-architect-self-hosted/standalone-deployment.md) is faster (one command, about 5 to 10 minutes).
{% endhint %}

## Before you begin

Have the following ready. See [Prerequisites & requirements](/ai-architect/installation/install-ai-architect-self-hosted/prerequisites-and-requirements.md) 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](https://alpha.bito.ai/home/advanced) |
| Git provider token (PAT) | GitHub, GitLab, Bitbucket, or Azure DevOps                         |
| Deployment tooling       | Docker Compose **or** Kubernetes (tabs below)                      |

{% tabs %}
{% tab title="Docker Compose" %}

* **Docker** Desktop 20.10+ with Compose v2
* Ports **5001-5006** free on the host (or customize)
  {% endtab %}

{% tab title="Kubernetes" %}

* `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
  {% endtab %}
  {% endtabs %}

<details>

<summary><strong>No cluster yet? Test on a local KIND cluster</strong></summary>

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

```shellscript
# 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
```

</details>

{% stepper %}
{% step %}

### Pre-seed your configuration (optional)

To install **without prompts**, create `~/.bitoarch/install.yaml` from the full template, [install.default.yaml](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/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.
{% endstep %}

{% step %}

### Install and index

```shellscript
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**.

{% hint style="info" %}
**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
```

{% endhint %}
{% endstep %}

{% step %}

### Expose the MCP endpoint

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

{% tabs %}
{% tab title="Docker Compose" %}
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.

```shellscript
bitoarch status
bitoarch mcp-info          # MCP URL + token
```

{% endtab %}

{% tab title="Kubernetes" %}
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.

```shellscript
# 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
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Connect your team

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

```shellscript
bitoarch mcp-info
```

Each user connects their tool with the [Quick MCP integration with AI coding agents](/ai-architect/quick-mcp-integration-with-ai-coding-agents.md) installer (Claude Code, Cursor, Windsurf, VS Code, JetBrains).

{% hint style="info" %}
**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](/ai-architect/single-sign-on-sso-integration.md).
{% endhint %}
{% endstep %}

{% step %}

### Verify the installation

```shellscript
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.
{% endstep %}
{% endstepper %}

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

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

Full walkthrough: [Single Sign-On (SSO) integration](/ai-architect/single-sign-on-sso-integration.md).

## Next steps

* [Operations & troubleshooting](/ai-architect/installation/install-ai-architect-self-hosted/operations-and-troubleshooting.md)
* [CLI command reference](/ai-architect/installation/install-ai-architect-self-hosted/cli-command-reference.md)

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

{% hint style="info" %}
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.
{% endhint %}


---

# 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/enterprise-deployment.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.