Documentation/Prism environment reference

Prism environment reference

Every key in Prism/.env.example is documented below. Examples are starting values, not credentials to reuse. Keep your .env private and restrict its permissions.

Environment, saved settings and updates

Saved AI provider settings take precedence over server AI defaults. Deployment paths, networks and mounts are controlled by Compose. Editing .env does not change a running container; recreate the affected service. A simple docker compose restart does not reload its environment.

chmod 600 .env
docker compose up -d --build

Conversation, embeddings and vision

`LLM_BACKEND`

Example / default: ollama
Purpose: Initial default conversation backend: ollama, openai or anthropic.
How to use it: Use openai for vLLM, SGLang, llama.cpp and compatible gateways. Saved AI provider settings override this initial choice.

`OLLAMA_URL`

Example / default: http://host-gateway:11434
Purpose: Ollama API root as seen by the Prism container; do not add /v1.
How to use it: Use http://ollama:11434 for an Ollama service on the same Compose network. host-gateway targets the Docker host, whose Ollama listener must accept connections from Docker.

`OLLAMA_MODEL`

Example / default: qwen3.6:27b
Purpose: Initial Ollama conversation model tag.
How to use it: Enter the exact installed tag returned by Ollama. Pull the model first; RAM/VRAM requirements depend on its size and quantization. This value does not download a model.

`OPENAI_BASE_URL`

Example / default: http://host-gateway:8000/v1
Purpose: API root for OpenAI or an OpenAI-compatible server.
How to use it: Include /v1 for compatible servers. Use https://api.openai.com/v1 for OpenAI; a Docker service name or reachable host address for your own server. Never embed credentials in the URL.

`OPENAI_API_KEY`

Example / default: (empty)
Purpose: Bearer credential for the OpenAI-compatible endpoint.
How to use it: Required by OpenAI and protected gateways; leave empty only if your endpoint accepts unauthenticated requests. Keep it in the private .env or the encrypted AI provider form.

`OPENAI_MODEL`

Example / default: assistant
Purpose: Initial model ID when LLM_BACKEND=openai.
How to use it: Copy the exact ID from /v1/models, including any served-model alias. The example assistant is an alias you must configure on your own server, not a downloadable model name.

`ANTHROPIC_API_KEY`

Example / default: (empty)
Purpose: API credential for Anthropic models.
How to use it: Use an Anthropic Console API key. A Claude chat subscription or Claude Code login is not an API credential for Prism. A configured key can add this source alongside another default.

`ANTHROPIC_MODEL`

Example / default: (provider model ID)
Purpose: Fallback/default Anthropic model identifier.
How to use it: Use an ID available to your API account. It becomes the initial conversation model with LLM_BACKEND=anthropic; the UI can list and select available models later.

`ANTHROPIC_BASE_URL`

Example / default: (empty)
Purpose: Optional Anthropic API proxy root.
How to use it: Empty uses https://api.anthropic.com. Change only for a trusted proxy implementing the Anthropic API; do not put an OpenAI /v1 endpoint here.

`EMBED_MODEL`

Example / default: qwen3-embedding:8b
Purpose: Initial embedding model used for document retrieval.
How to use it: This is separate from the conversation model. Pull it on Ollama or serve it through /v1/embeddings. Changing an existing index model requires a rebuild from AI provider.

`EMBED_BACKEND`

Example / default: (empty)
Purpose: Initial embedding backend: ollama or openai.
How to use it: Empty follows the chat backend, except Anthropic falls back to Ollama because it has no embedding API. Select this explicitly when chat and embeddings are hosted separately; the UI supports a dedicated source too.

`CHAT_VISION`

Example / default: true
Purpose: Initial assumption about image support in the conversation model.
How to use it: Set false for a text-only model. AI provider → Model settings can override vision per source and model, or use metadata when the provider reports it. Do not assume a text connection test validates vision.

`VISION_MODEL`

Example / default: (empty)
Purpose: Optional captioning model for image-to-text fallback.
How to use it: Use a model that actually supports images and is available on the configured captioning backend. Useful when the conversation model is text-only; leaving it empty does not install a vision model.

Services and access

`POSTGRES_URL`

Example / default: postgres://rag:rag@postgres:5432/rag?sslmode=disable
Purpose: PostgreSQL connection string for persistence and pgvector.
How to use it: The shipped value matches the bundled database. An external database needs pgvector, a reachable address and matching credentials. For remote databases configure the TLS mode required by that server. Changing the URL does not migrate data.

`SEARXNG_URL`

Example / default: http://searxng:8080
Purpose: Search service used by web research tools.
How to use it: Keep the Compose service URL or use your own reachable SearXNG endpoint. Empty disables this search integration. This is not the address of your AI provider.

`PRISM_TOKEN`

Example / default: (generate a unique secret)
Purpose: Service token and single-user dashboard access token.
How to use it: Generate with openssl rand -hex 32. Empty removes single-user token authentication. In shared mode, human users have accounts; keep the service token private because integrations can use its elevated identity.

`MULTI_USER`

Example / default: (empty)
Purpose: Enables shared mode with accounts, groups and Admin when set to 1 or true.
How to use it: Choose before first startup. Existing configuration and secrets are migrated to the first administrator. Removing the flag is not a supported rollback: back up before converting an existing installation.

`TZ`

Example / default: UTC
Purpose: Server timezone fallback for the agent and new schedules.
How to use it: Use an IANA timezone such as Europe/Paris or America/Martinique, not GMT+2. Users can override it in Settings → Profile. Existing explicit cron timezones retain their own setting.

`VOX_URL`

Example / default: (empty)
Purpose: Internal HTTP root of an optional PrismVox console/API.
How to use it: For a shared Docker network use http://ui:7860 or an explicit network alias. Empty hides telephony. Connectivity must also be configured from PrismVox to Prism; see the connection guide.

`VOX_USER`

Example / default: (empty)
Purpose: Basic-auth username for the PrismVox administrative API.
How to use it: Match PrismVox UI_USER when its console is password protected. This is neither a SIP username nor the caller’s Prism account.

`VOX_PASSWORD`

Example / default: (empty)
Purpose: Basic-auth password paired with VOX_USER.
How to use it: Match PrismVox UI_PASSWORD and keep it secret. After a console-password rotation, update this integration and recreate prism-server.

Workspace, Docker and storage

`WORKSPACE`

Example / default: (empty)
Purpose: Workspace image variant selected during a source build.
How to use it: Empty selects the base image; gpu selects the much larger CUDA/PyTorch variant. Rebuild the workspace and add an NVIDIA device reservation override when using GPU access. It does not select the chat provider.

`AGENT_CONTAINER`

Example / default: prism-workspace
Purpose: Name of the execution container controlled by Prism.
How to use it: Keep the bundled name unless you also change the workspace container name in Compose. This is the execution environment, not a dashboard workspace tab.

`WORKSPACE_DIR`

Example / default: /workspace
Purpose: Execution files root inside the Prism server.
How to use it: Keep the same shared-volume path in prism-server and workspace. This is a container path, not a folder to enter from your laptop.

`PLUGIN_DIR`

Example / default: /workspace/.plugins
Purpose: Storage location for dashboard widget files.
How to use it: Keep it within the persistent workspace volume. Moving it alone does not move existing widgets or their stored metadata.

`SERVICE_PORT_START`

Example / default: 20000
Purpose: First host port allocated to Docker services created by the agent.
How to use it: Choose a free range together with SERVICE_PORT_END. The shipped Compose does not forward these two variables: add them to prism-server.environment in an override before changing them.

`SERVICE_PORT_END`

Example / default: 20999
Purpose: Last host port available for agent-created services.
How to use it: Must be at least SERVICE_PORT_START and within valid TCP port numbers. Account for existing services and firewall policy; a published service is not made private by its port number.

`LIVE_CONTEXT_CHAR_BUDGET`

Example / default: (unset; unknown-model fallback 150000)
Purpose: Optional deployment ceiling for the agent’s live context budget.
How to use it: Leave unset to use each model’s detected or manually configured context window. Use Model settings for a 500000-token model; this variable is a character/byte-equivalent ceiling, not a token count.

`DOCKER_MODE`

Example / default: host
Purpose: Docker backend used for services created by the agent.
How to use it: host uses the host daemon and requires trusted users. workspace targets a daemon already provisioned inside the execution environment; it does not install Docker-in-Docker or create an isolation sandbox.

`WORKSPACE_DOCKER_SOCKET`

Example / default: unix:///run/user/1000/docker.sock
Purpose: Docker daemon address used in workspace mode.
How to use it: Match the actual internal daemon socket. Ignored in host mode. Changing this value cannot provide a daemon that is not installed and running.

`WORKSPACE_DOCKER_USER`

Example / default: 1000
Purpose: User identity for Docker commands inside the execution environment.
How to use it: Match the owner permitted to access the internal daemon. The default targets a rootless daemon owned by UID 1000; only change it together with that environment’s provisioning.

`NOTES_VAULT_PATH`

Example / default: (empty)
Purpose: Optional absolute host folder to mount at /vault.
How to use it: Set an existing Markdown vault directory, recreate prism-server, then select Markdown vault and /vault in Settings → Notes. Empty uses a managed volume. Back up files before enabling write access.

Additional Compose and compatibility options

NO_PROXY extends the internal proxy bypass list. PRISM_ANTHROPIC_TOOL_SEARCH and PRISM_CLAUDE_LAZY_TOOLS are experimental Anthropic tool-discovery flags, off by default; leave them unset for the standard tool catalog. They are forwarded by Compose but are not needed for the installation recipes.

The optional protonmail profile enables the bundled Bridge service. Its generated IMAP/SMTP password belongs in Email settings; the standard .env does not configure a Proton account.

Advanced runtime and internal wiring

These options are read by application processes but are not all forwarded by the standard Compose file. Adding a name to .env alone is insufficient when no service environment entry references it. Use a Compose override for the named service, recreate it, and keep the usual UI settings for ordinary changes.

`OPENAI_REASONING_EFFORT`

Default reasoning effort sent to compatible OpenAI APIs. Empty or none omits the field. The personal Agent setting can override this default; use a value your model accepts.

Service: prism-server · Default: medium

`OLLAMA_NUM_CTX`

Fallback context size in tokens requested from Ollama. Per-model context settings are the normal control; a larger value needs enough model-server memory and actual model support.

Service: prism-server · Default: 32768

`HISTORY_REPLAY_MAX_MESSAGES`

Positive cap on conversation rows loaded for replay, distinct from the model token window. Unset, Prism scales the bound from the context budget, with a floor of 200 and ceiling of 20000 rows. Setting an explicit small value can discard useful history despite a large model context.

Service: prism-server · Default: Automatic

`CHANNEL_CONTEXT_CHAR_BUDGET`

History character budget for group channels/rooms; 0 restores the deployment-wide budget. This is not a token limit and does not change the provider model’s capabilities.

Service: prism-server · Default: 30000

`PORT`

Internal HTTP listener. A change also needs matching Compose routing, health checks and proxy targets; the browser port is configured separately by published ports.

Service: prism-server · Default: 8080

`SECRET_KEY_PATH`

Private encryption-key file outside WORKSPACE_DIR, in persistent server storage. The default is derived from the workspace path. Back up and restore this key with the database; choosing a new empty path does not decrypt old credentials.

Service: prism-server · Default: Automatic

Example: forward one runtime option

services:
  prism-server:
    environment:
      OPENAI_REASONING_EFFORT: "none"

Save as compose.runtime.yml and include it with your existing Compose files. This example omits reasoning_effort for a backend that rejects that field; it is not a recommendation for every model.

docker compose -f docker-compose.yml -f compose.runtime.yml up -d --no-deps prism-server

Continue: Prism deployment examples →