Skip to main content
These initialization steps must be completed after helm install before the platform is usable by any users.

​
Overview

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

​
Required: First Boot Initialization

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

​
Initialize Internal Organization

kubectl exec -it deploy/crewai-web -- bin/rails studio:install_internal_organization
If you’re using Multi-Organization Namespace Isolation, the studio:install_internal_organization command will expect the namespaces described in the feature guide to exist before running.

​
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: 
kubectl exec -it deploy/crewai-web -- bin/rails runner "puts Organization.all.map { |o| \"#{o.id}: #{o.name}\" }.join(\"\\n\")"
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.
# 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]'
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.
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.
Multi-user, multi-org example — two users in two organizations (each command is a separate kubectl exec call): 
# 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,daniel.example@example.com]'
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:add_owner[1,daniel.example2@example.com]'

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

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

​
Grant Admin Panel Access

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). 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.
Grant users access to the admin panel by assigning the factory-admin role. For all other authentication providers, use the following Rails commands: 
# 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 
kubectl exec -it deploy/crewai-web -- bin/rails studio:tools:sync_crewai_tools
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.
For information on adding integrations to an existing deployment, see Configure Built-In Integrations.

​
Optional: Additional Configuration

​
Enable Studio V2 (Optional)

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.
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.
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.
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: 
# 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 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. The Studio Agent supports any model available through LiteLLM.
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.

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

​
Accessing the Application

Choose the appropriate access method for your deployment:

​
Via Port Forwarding (Development)

# 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: 
# Example with NGINX ingress
open https://crewai.company.com

​
Via LoadBalancer (Alternative)

If using LoadBalancer service type: 
# 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: 
    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.
  5. Test basic functionality by creating a test crew or project
  6. Check background workers are processing jobs: 
    kubectl logs -l app=crewai-worker --tail=50