Workspace Configuration

Relevant source files

• server/endpoints/embed/index.js
• server/models/embedChats.js
• server/models/workspace.js
• server/models/workspaceChats.js
• server/prisma/schema.prisma
• server/utils/chats/embed.js
• server/utils/chats/index.js
• server/utils/chats/stream.js
• server/utils/middleware/embedMiddleware.js

Purpose and Scope

This page documents the configuration settings available at the workspace level in AnythingLLM. It covers how workspace settings are stored in the Workspace model, the available configuration fields, validation rules, and how these settings inherit from system defaults and are consumed during chat operations.

For information about managing documents within workspaces, see Document Management in Workspaces. For workspace threads and conversation organization, see Thread System. For system-level configuration management, see Configuration Management.

---

Overview

Workspaces in AnythingLLM are tenant containers that can override system-level settings with workspace-specific configuration. Each workspace maintains its own settings for:

• LLM Configuration: Provider, model, and inference parameters (temperature, history length)
• System Prompt: Custom instructions for the AI assistant
• Vector Search Configuration: Similarity threshold, number of results (topN), search mode
• Agent Configuration: Agent provider and model selection
• Chat Behavior: Chat mode (chat vs query), query refusal messages

Workspace settings provide per-tenant customization while maintaining sensible defaults inherited from system configuration.

Sources: server/models/workspace.js1-612 server/prisma/schema.prisma127-156

---

Workspace Model Structure

The Workspace model is defined in server/models/workspace.js and manages all workspace configuration operations. It provides methods for creating, updating, and querying workspaces, along with validation logic for configuration fields.

Core Model Properties

Sources: server/models/workspace.js35-612 server/prisma/schema.prisma127-156

---

Configuration Fields Reference

Writable Fields

The Workspace model defines a writable array that specifies which fields can be updated through the API. Fields not in this list (such as slug, vectorTag, pfpFilename) require direct database access or specialized methods to modify.

Writable Configuration Fields:

• name - Workspace display name
• openAiTemp - Temperature for LLM inference
• openAiHistory - Number of chat history messages to include
• lastUpdatedAt - Timestamp of last modification
• openAiPrompt - System prompt for the workspace
• similarityThreshold - Minimum similarity score for vector search
• chatProvider - LLM provider override (e.g., "openai", "anthropic")
• chatModel - Model name override (e.g., "gpt-4", "claude-3-sonnet")
• topN - Number of document chunks to retrieve
• chatMode - Chat behavior mode ("chat" or "query")
• agentProvider - Agent system provider override
• agentModel - Agent model override
• queryRefusalResponse - Custom message when no context found in query mode
• vectorSearchMode - Search mode ("default" or "rerank")

Sources: server/models/workspace.js40-58

Field Validation Rules

Each configuration field has an associated validation function that normalizes values and applies constraints. The validateFields() method applies these validations before any update.

Field	Type	Validation Logic	Default
name	String	Max 255 characters, fallback to "My Workspace"	"My Workspace"
openAiTemp	Float	Must be >= 0, null if invalid	null
openAiHistory	Integer	Must be >= 0	20
similarityThreshold	Float	Clamped to 0.0-1.0 range	0.25
topN	Integer	Must be >= 1	4
chatMode	String	Must be "chat" or "query"	"chat"
chatProvider	String	Null if empty or "none"	null
chatModel	String	Null if empty	null
agentProvider	String	Null if empty or "none"	null
agentModel	String	Null if empty	null
queryRefusalResponse	String	Null if empty	null
openAiPrompt	String	Null if empty	null
vectorSearchMode	String	Must be "default" or "rerank"	"default"

Sources: server/models/workspace.js60-132

Validation Implementation

Sources: server/models/workspace.js164-176

---

Settings Inheritance and Defaults

System Default Inheritance

When a workspace is created, it inherits the default system prompt from the system_settings table. If no system default is configured, it falls back to SystemSettings.saneDefaultSystemPrompt.

Workspace Creation Flow:

Sources: server/models/workspace.js197-202 server/models/workspace.js205-222

Runtime Settings Resolution

During chat operations, workspace settings are resolved with fallback to system environment variables:

1. LLM Provider/Model: Workspace chatProvider and chatModel override system process.env.LLM_PROVIDER and base model
2. Temperature: Workspace openAiTemp overrides LLMConnector.defaultTemp
3. System Prompt: Workspace openAiPrompt overrides system default prompt
4. History Length: Workspace openAiHistory determines message limit (default: 20)
5. Vector Search: Workspace similarityThreshold, topN, and vectorSearchMode control retrieval

Sources: server/utils/chats/stream.js53-56 server/utils/chats/stream.js156-159 server/utils/chats/stream.js231-240 server/utils/chats/stream.js249-252

---

Configuration Fields in Detail

LLM Configuration

chatProvider and chatModel

These fields allow workspace-level override of the LLM provider and model. When set, they take precedence over system-level process.env.LLM_PROVIDER and model configuration.

• Provider: String identifier like "openai", "anthropic", "ollama", "gemini", etc.
• Model: Model name specific to the provider (e.g., "gpt-4", "claude-3-5-sonnet-20241022", "llama3")
• Validation: Provider and model are set to null if empty or "none"
• Special Case: When chatProvider is set to "default", both chatProvider and chatModel are cleared to null

Sources: server/models/workspace.js99-106 server/models/workspace.js240-243

openAiTemp

Controls the temperature parameter for LLM inference, affecting response randomness.

• Type: Float
• Range: >= 0.0 (no upper limit enforced at validation)
• Default: null (uses LLM provider's default temperature)
• Usage: Lower values (0.0-0.3) for deterministic responses, higher values (0.7-1.0) for creative responses

Sources: server/models/workspace.js68-72

openAiHistory

Number of previous chat messages to include in the context window for each new request.

• Type: Integer
• Range: >= 0
• Default: 20
• Usage: Retrieved via recentChatHistory() during chat operations

Sources: server/models/workspace.js73-79 server/utils/chats/stream.js59

openAiPrompt

The system prompt that defines the AI assistant's behavior, personality, and capabilities.

• Type: String (can be very long)
• Default: Inherits from system_settings.default_system_prompt or SystemSettings.saneDefaultSystemPrompt
• Validation: Set to null if empty
• Usage: Expanded with system prompt variables before being sent to the LLM

Sources: server/models/workspace.js119-122 server/utils/chats/index.js91-100

Vector Search Configuration

similarityThreshold

Minimum cosine similarity score for vector search results to be included in context.

• Type: Float
• Range: 0.0 to 1.0 (clamped)
• Default: 0.25
• Usage: Higher values require stronger semantic matches

Sources: server/models/workspace.js80-87 server/utils/chats/stream.js156

topN

Maximum number of document chunks to retrieve from vector database.

• Type: Integer
• Range: >= 1
• Default: 4
• Usage: Controls context window size and response accuracy vs. speed tradeoff

Sources: server/models/workspace.js88-94 server/utils/chats/stream.js157

vectorSearchMode

Determines the vector search strategy.

• Type: String enum
• Values: "default" or "rerank"
• Default: "default"
• "default": Standard similarity search with topN results
• "rerank": Uses reranking for better relevance (LanceDB only)

Sources: server/models/workspace.js123-131 server/utils/chats/stream.js159

Chat Behavior Configuration

chatMode

Defines how the workspace handles queries when no relevant context is found.

• Type: String enum
• Values: "chat" or "query"
• Default: "chat"

Mode Comparison:

Mode	Behavior with No Context	Use Case
chat	Uses general LLM knowledge	General conversation, Q&A with fallback
query	Refuses to answer, returns queryRefusalResponse	Strict document-only responses, compliance scenarios

Sources: server/models/workspace.js95-98 server/utils/chats/stream.js16 server/utils/chats/stream.js65-92 server/utils/chats/stream.js200-227

queryRefusalResponse

Custom message returned when in "query" mode and no relevant context is found.

• Type: String
• Default: "There is no relevant information in this workspace to answer your query."
• Usage: Allows workspace-specific messaging for context-missing scenarios

Sources: server/models/workspace.js115-118 server/utils/chats/stream.js66-68

Agent Configuration

agentProvider and agentModel

Workspace-level overrides for agent system configuration. Agents use the AIbitat framework for multi-step tool calling.

• Type: String
• Default: null (inherits system agent configuration)
• Validation: Set to null if empty or "none"
• Usage: Allows different agent capabilities per workspace

Sources: server/models/workspace.js107-114

---

Configuration Consumption During Chat

Chat Request Flow with Workspace Settings

The following diagram illustrates how workspace configuration is consumed during a streaming chat request:

Sources: server/utils/chats/stream.js18-311

Settings Access Points

Sources: server/utils/chats/stream.js18-311

---

Context Window Management

The Workspace model includes a method _getContextWindow() that calculates the maximum context window size based on the workspace's LLM provider and model configuration.

Context Window Resolution Logic

1. Determine Provider: Use workspace.chatProvider or fall back to process.env.LLM_PROVIDER
2. Get Provider Class: Retrieve the LLM provider class via getLLMProviderClass()
3. Determine Model: Use workspace.chatModel or fall back to base model for the provider
4. Query Limit: Call LLMProvider.promptWindowLimit(model) to get token limit
5. Return: Returns token limit or null if provider/model not found

This value is included in the workspace object when retrieved via Workspace.get() or Workspace.getWithUser().

Sources: server/models/workspace.js327-339 server/models/workspace.js341-362

---

Special Workspace Update Behaviors

Chat Provider Reset

When the chatProvider field is updated to "default", both chatProvider and chatModel are cleared to null. This prevents configuration inconsistencies where a model is set without a provider.

Sources: server/models/workspace.js240-243

Prompt History Tracking

The Workspace model tracks changes to the openAiPrompt field for telemetry and audit purposes. When a prompt is modified:

1. Previous prompt is saved to prompt_history table (if non-default and changed)
2. Telemetry event "workspace_prompt_changed" is sent
3. Event log entry is created with workspace name and prompt diff

This feature supports future prompt library or prompt assistant functionality.

Sources: server/models/workspace.js484-533

---

Embed Configurations and Workspace Settings

Embed widgets (embeddable chat interfaces) inherit workspace configuration with optional overrides. The embed_configs table references a workspace and can allow users to override certain settings.

Embed Configuration Overrides

When an embed chat is initiated, the following workspace settings can be overridden if the embed configuration permits:

• Prompt Override: allow_prompt_override flag allows custom system prompts
• Model Override: allow_model_override flag allows different chatModel
• Temperature Override: allow_temperature_override flag allows different temperature

The embed system uses the same workspace configuration fields but with per-session customization:

Sources: server/utils/chats/embed.js11-207 server/prisma/schema.prisma238-257

---

Database Schema

Workspaces Table Structure

workspaces
├── id (Int, Primary Key)
├── name (String)
├── slug (String, Unique)
├── vectorTag (String?, Nullable)
├── createdAt (DateTime)
├── lastUpdatedAt (DateTime)
│
├── LLM Configuration
│   ├── chatProvider (String?, Nullable)
│   ├── chatModel (String?, Nullable)
│   ├── openAiTemp (Float?, Nullable)
│   ├── openAiHistory (Int, Default: 20)
│   └── openAiPrompt (String?, Nullable)
│
├── Vector Configuration
│   ├── similarityThreshold (Float?, Default: 0.25)
│   ├── topN (Int?, Default: 4)
│   └── vectorSearchMode (String?, Default: "default")
│
├── Chat Behavior
│   ├── chatMode (String?, Default: "chat")
│   └── queryRefusalResponse (String?, Nullable)
│
├── Agent Configuration
│   ├── agentProvider (String?, Nullable)
│   └── agentModel (String?, Nullable)
│
├── Display
│   └── pfpFilename (String?, Nullable)
│
└── Relations
    ├── workspace_users[]
    ├── documents[]
    ├── workspace_suggested_messages[]
    ├── embed_configs[]
    ├── threads[]
    ├── workspace_agent_invocations[]
    ├── prompt_history[]
    └── workspace_parsed_files[]

Sources: server/prisma/schema.prisma127-156

---

Summary

Workspace configuration in AnythingLLM provides fine-grained control over AI behavior, vector search, and chat modes at the tenant level. Key characteristics:

• Validation-First: All updates pass through validation functions ensuring data integrity
• Inheritance Model: Workspaces inherit system defaults but can override any setting
• Flexible Overrides: Per-workspace LLM providers, models, and parameters
• Chat Mode Control: "chat" vs "query" modes for different use cases
• Vector Search Tuning: Similarity thresholds and result counts per workspace
• Audit Trail: Prompt changes tracked in prompt_history table

The configuration system balances flexibility with safety through comprehensive validation while maintaining backward compatibility through nullable fields and sensible defaults.

Sources: server/models/workspace.js1-612 server/prisma/schema.prisma127-156 server/utils/chats/stream.js18-311