> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Post-Installation

> Post-installation configuration and setup steps for CrewAI Platform

<Note>
  These initialization steps must be completed after `helm install` before the platform is usable by any users.
</Note>

## Overview

After successfully installing CrewAI Platform, perform these initial setup tasks to configure the system and prepare it for use.

## Required: First Boot Initialization

<Warning>
  The following steps are **REQUIRED** before any user can log in:

  1. **Initialize Internal Organization** (`studio:install_internal_organization`)
  2. **Set Up Default Permissions** (`factory:setup_permissions_defaults`)
  3. **Grant Admin Panel Access** (`factory:grant_admin`) — **skip this step if using Microsoft Entra ID** (admin access is handled via Azure App Roles instead — see the warning below)
  4. **Add Owner** (`factory:add_owner`)

  The following steps are **OPTIONAL** and can be performed after the platform is accessible:

  * Enable Studio V2
  * Multi-Organization Namespace Isolation
</Warning>

### Initialize Internal Organization

```bash theme={null}
kubectl exec -it deploy/crewai-web -- bin/rails studio:install_internal_organization
```

<Note>
  If you're using Multi-Organization Namespace Isolation, the `studio:install_internal_organization` command will expect the namespaces described in the [feature guide](/features/multi-org-namespaces) to exist before running.
</Note>

### Set Up Default Permissions

**Understanding Organization IDs**

Organization IDs are sequential integers assigned by the database. After running `studio:install_internal_organization`, the internal CrewAI organization receives ID 1. The first customer-facing organization created in the UI receives ID 2. To list all organizations and their IDs:

```bash theme={null}
kubectl exec -it deploy/crewai-web -- bin/rails runner "puts Organization.all.map { |o| \"#{o.id}: #{o.name}\" }.join(\"\\n\")"
```

<Note>
  **Local auth (AUTH\_PROVIDER: local) users:** Before running `factory:add_owner` or `factory:grant_admin`, your admin user must exist in the database. With SSO providers, the user record is created automatically on first login. With local auth, the user must self-register:

  1. Navigate to `https://<APPLICATION_HOST>/users/sign_up`
  2. Register with the email address you will use for `factory:add_owner` and `factory:grant_admin`
  3. Then run the kubectl exec commands below

  If you run `factory:add_owner[2,admin@company.com]` before the user record exists, the command will silently succeed but assign the role to a non-existent user, and the next login will not have admin access.
</Note>

```bash theme={null}
# Step 1: Set up default permission roles
kubectl exec -it deploy/crewai-web -- bin/rails factory:setup_permissions_defaults

# Step 2: Add the first admin as owner of org 2 (replace with your admin email)
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[2,admin@company.com]'
```

<Note>
  **Role distinction:** `factory:add_owner` grants organization ownership within a specific org (org-scoped). `factory:grant_admin` grants access to the platform Admin Panel (global). Admins typically need both.
</Note>

<Note>
  There is no `adminUsers` Helm key. Admin roles must be set via the `kubectl exec` commands below — they cannot be pre-configured in values.yaml.
</Note>

**Multi-user, multi-org example** — two users in two organizations (each command is a separate `kubectl exec` call):

```bash theme={null}
# Grant ownership in org 1 (internal org) — repeat for org 2, 3, etc.
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[1,admin1@example.com]'
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[1,admin2@example.com]'

# Grant ownership in org 2 (first customer org)
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[2,admin1@example.com]'
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[2,admin2@example.com]'

# Grant Admin Panel access (global — not per-org)
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:grant_admin[admin1@example.com]'
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:grant_admin[admin2@example.com]'
```

### Grant Admin Panel Access

<Warning>
  **Microsoft Entra ID users: do NOT run `factory:grant_admin`.** Admin panel access for Entra ID users is granted by assigning the `factory-admin` App Role in the Azure portal (see [Entra ID App Roles](/features/entra-id#configuring-app-roles)). Running `factory:grant_admin` has no effect for Entra ID users because the platform reads admin status from the JWT `roles` claim, not the database table that `factory:grant_admin` modifies.

  All other commands — `studio:install_internal_organization`, `factory:setup_permissions_defaults`, and `factory:add_owner` — ARE still required for Entra ID deployments.
</Warning>

Grant users access to the admin panel by assigning the `factory-admin` role.

For all other authentication providers, use the following Rails commands:

```bash theme={null}
# Grant admin access to a user
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:grant_admin[admin@company.com]'

# Revoke admin access from a user
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:revoke_admin[admin@company.com]'

# List all users with admin access
kubectl exec -it deploy/crewai-web -- bin/rails factory:list_admins
```

## Sync Built-In Integrations

If you have configured OAuth credentials for Built-In Integrations (Google Workspace, Microsoft 365, HubSpot, Notion, or Salesforce), you need to sync the integration definitions so the platform recognizes them.

**Option 1: Via Admin Panel**

1. Log in to the CrewAI web UI as an admin
2. Navigate to **Admin Panel** > **Tools & Integrations**
3. Click the **Sync Integrations** button

**Option 2: Via kubectl**

```bash theme={null}
kubectl exec -it deploy/crewai-web -- bin/rails studio:tools:sync_crewai_tools
```

<Warning>
  You must sync integrations after every Helm upgrade that adds or changes OAuth integration credentials. Without syncing, newly configured integrations will not appear as available to users.
</Warning>

For information on adding integrations to an existing deployment, see [Configure Built-In Integrations](/features/built-in-integrations-overview).

## Optional: Additional Configuration

### Enable Studio V2 (Optional)

<Note>
  There are no Helm values for Studio V2. Adding `studioV2.enabled` or `STUDIO_V2_ENABLED` to your values.yaml has no effect — Helm silently ignores unrecognized keys.
</Note>

<Warning>
  **Studio V2 has no Helm chart values and cannot be pre-configured in values.yaml.** Setup requires the platform to be fully running and accessible. The UI steps cannot be automated — Studio V2 requires interactive setup.
</Warning>

<Note>
  **GitOps users:** The UI steps cannot be automated via ArgoCD or Flux — Studio V2 requires interactive browser-based setup. Only the `kubectl exec` commands can be applied declaratively.
</Note>

Studio V2 setup involves the following ordered steps once the platform is accessible:

**Step 1: Create the LLM Connection (UI)**

Log in to the CrewAI web UI as an admin and create an LLM Connection named **exactly** `studio-v2`.

**Step 2: Set as Default Connection (UI)**

In the UI, set the `studio-v2` connection as the default LLM connection.

**Step 3: Run the activation commands (kubectl)**

After completing both UI steps, run these three commands in order:

```bash theme={null}
# 1. Install the Studio agent
kubectl exec -it deploy/crewai-web -- bin/rails studio:agent:install

# 2. Sync and index tools
kubectl exec -it deploy/crewai-web -- \
  bin/rails studio:tools:sync_crewai_tools \
       studio:tools:sync_enterprise_tools

# 3. Install the Studio runner
kubectl exec -it deploy/crewai-web -- bin/rails studio:runner:install
```

**These are the complete and authoritative activation commands. They match the Studio V2 Setup Guide exactly.**

See the [Studio V2 Setup Guide](/features/studio-v2) for UI steps that must precede these commands.

### Configuring the Studio Agent Model

By default, the Studio Agent uses an Anthropic model to chat, build crews, and generate code. To use a different model, set the `MODEL` in the `studio-v2` LLM connection you created during [Studio V2 setup](#enable-studio-v2-optional). The Studio Agent supports any model available through LiteLLM.

<Warning>
  After updating the model in the `studio-v2` LLM connection, you need to redeploy the `studio-assistant` deployment for the change to take effect. The platform does not automatically trigger a redeployment.
</Warning>

### Enable Multi-Organization Namespace Isolation (Optional)

If you plan to use namespace isolation between organizations, enable it before deploying any crews. See [Multi-Organization Namespace Isolation](/features/multi-org-namespaces).

## Accessing the Application

Choose the appropriate access method for your deployment:

### Via Port Forwarding (Development)

```bash theme={null}
# Forward web service port
kubectl port-forward svc/crewai-web 2603:80

# Access in browser
open http://localhost:2603
```

### Via Ingress (Production)

If ingress is enabled, access via your configured hostname:

```bash theme={null}
# Example with NGINX ingress
open https://crewai.company.com
```

### Via LoadBalancer (Alternative)

If using LoadBalancer service type:

```bash theme={null}
# Get LoadBalancer external IP
kubectl get svc crewai-web

# Access via LoadBalancer IP
open http://<EXTERNAL-IP>:80
```

## Verification Steps

After completing post-installation setup:

1. **Access the Web UI** using one of the methods above
2. **Log in** with your configured authentication provider
3. **Verify admin access** by checking user permissions
4. **Run the health diagnostic** to verify all components are functional:
   ```bash theme={null}
   TOKEN=$(kubectl get secret <release-name>-secrets -n <namespace> \
     -o jsonpath='{.data.FACTORY_DEBUG_TOKEN}' | base64 -d)

   curl -H "X-Factory-Debug-Token: $TOKEN" \
     https://<your-factory-host>/health/debug
   ```
   All components should report `"status": "ok"`. The endpoint requires the auto-generated `FACTORY_DEBUG_TOKEN` (or a signed-in `factory-admin` session); unauthorized callers receive `404`. For detailed troubleshooting if any checks fail, see [Factory Health & Debug](/factory-health).
5. **Test basic functionality** by creating a test crew or project
6. **Check background workers** are processing jobs:
   ```bash theme={null}
   kubectl logs -l app=crewai-worker --tail=50
   ```