Configure Plane AI Commercial Edition

Plane AI brings AI-powered features to your workspace, including natural language chat, duplicate detection, and semantic search across work items, pages, and projects. This guide walks you through configuring Plane AI on your self-hosted instance.

For an overview of what Plane AI can do, see the Plane AI.

Before you begin

You'll need:

• An OpenSearch 2.x instance (self-hosted or AWS OpenSearch) configured for advanced search.
• At least one LLM provider API key or a custom OpenAI-compatible endpoint.
• At least one embedding model configured in OpenSearch.

Supported models

Large language models (LLMs)

OpenAI

Supported models:

• GPT-5
• GPT-4.1
• GPT-5.2

Anthropic

Supported models:

• Claude Sonnet 4.0
• Claude Sonnet 4.5
• Claude Sonnet 4.6

You can provide API keys for both OpenAI and Anthropic, making all models available to users. If you provide only one key, users will only have access to that provider's models.

Custom models (self-hosted or third-party)

Plane AI works with any model exposed through an OpenAI-compatible API, including models served by Ollama, Groq, Cerebras, and similar runtimes. You can configure one custom model alongside your public provider keys.

WARNING

For reliable performance across all Plane AI features, use a custom model with at least 100 billion parameters. Larger models produce better results.

Embedding models

Embedding models power semantic search. Plane AI supports:

Provider	Supported models
Cohere	cohere/embed-v4.0
OpenAI	openai/text-embedding-ada-002, openai/text-embedding-3-small
AWS Bedrock (Titan)	bedrock/amazon.titan-embed-text-v1

Enable Plane AI services

Open the /opt/plane/plane.env file in your preferred editor and set the replica count for Plane AI services to 1:

PI_API_REPLICAS=1
PI_BEAT_REPLICAS=1
PI_WORKER_REPLICAS=1
PI_MIGRATOR_REPLICAS=1

Configure an LLM provider

Configure at least one LLM provider. Add the relevant variables to /opt/plane/plane.env.

OpenAI

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

Anthropic

CLAUDE_API_KEY=xxxxxxxxxxxxxxxx

Custom model

Use this for self-hosted models or third-party OpenAI-compatible endpoints.

CUSTOM_LLM_ENABLED=true
CUSTOM_LLM_MODEL_KEY=your-model-key
CUSTOM_LLM_BASE_URL=http://your-endpoint/v1
CUSTOM_LLM_API_KEY=your-api-key
CUSTOM_LLM_NAME=Your Model Name
CUSTOM_LLM_DESCRIPTION="Optional description"
CUSTOM_LLM_MAX_TOKENS=128000

INFO

The custom endpoint must expose an OpenAI-compatible API matching OpenAI's request and response format.

Speech-to-text (optional)

GROQ_API_KEY=your-groq-api-key

This enables voice input in Plane AI. It's not required for LLM or semantic search features.

Configure OpenSearch and an embedding model

Plane AI uses OpenSearch for semantic indexing and retrieval. If you haven't set up OpenSearch yet, complete the OpenSearch for advanced search guide first, then return here.

Configure OpenSearch connection

OPENSEARCH_URL=https://your-opensearch-instance:9200/
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=your-secure-password
OPENSEARCH_INDEX_PREFIX=plane

Configure an embedding model

Configure exactly one embedding model using one of these options.

Option A: Use an existing OpenSearch model ID

If you've already deployed an embedding model in OpenSearch, provide its model ID. This works with both self-hosted and AWS OpenSearch.

EMBEDDING_MODEL_ID=your-model-id

For AWS OpenSearch, you must deploy the embedding model manually before setting this variable. See Deploy an embedding model on AWS OpenSearch.

Option B: Automatic deployment (self-hosted OpenSearch only)

For self-hosted OpenSearch, Plane can automatically create and deploy the embedding model. Provide the model name and the corresponding provider credentials.

Cohere:

EMBEDDING_MODEL=cohere/embed-v4.0
COHERE_API_KEY=your-cohere-api-key

OpenAI:

EMBEDDING_MODEL=openai/text-embedding-3-small
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

AWS Bedrock (Titan):

EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v1
BR_AWS_ACCESS_KEY_ID=your-access-key
BR_AWS_SECRET_ACCESS_KEY=your-secret-key
BR_AWS_REGION=your-region

Required IAM permission for Bedrock Titan

The IAM user for BR_AWS_ACCESS_KEY_ID and BR_AWS_SECRET_ACCESS_KEY needs bedrock:InvokeModel permission on the Titan foundation model. Without it, embedding requests fail with a 403 error.

Attach this policy to the IAM user:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeModel",
      "Resource": "arn:aws:bedrock:<your-region>::foundation-model/amazon.titan-embed-text-v1"
    }
  ]
}

Replace <your-region> with your BR_AWS_REGION value.

INFO

Automatic embedding model deployment only works with self-hosted OpenSearch. For AWS OpenSearch, deploy the model manually and use EMBEDDING_MODEL_ID.

Restart Plane

After updating the environment file, restart Plane.

Docker:

prime-cli restart

Or if you're managing containers directly:

docker compose down
docker compose up -d

Kubernetes:

helm upgrade --install plane-app plane/plane-enterprise \
    --namespace plane \
    -f values.yaml \
    --wait

Vectorize existing data

Generate embeddings for your existing content by running this command in the API container.

Docker:

docker exec -it plane-api-1 sh
python manage.py manage_search_index --background --vectorize document index --force

Kubernetes:

API_POD=$(kubectl get pods -n plane --no-headers | grep api | head -1 | awk '{print $1}')
kubectl exec -n plane $API_POD -- python manage.py manage_search_index --background --vectorize document index --force

The --background flag processes vectorization through Celery workers. This is recommended for instances with large amounts of existing content.

After setup

Once configured:

• Plane AI is available across your workspace.
• New content (work items, pages, comments) is automatically vectorized in the background.
• Semantic search stays synchronized without manual intervention.

Environment variables reference

See the environment variables reference for a complete list of AI-related configuration options.