TinyMCE AI on-premises reference

Environment variable reference

Alphabetized. Required-ness is marked relative to a minimum working deployment.

Variable Required Default Description

ALLOWED_ORIGINS

Recommended

Comma-separated list of CORS-allowed editor origins. Required for cross-origin editor deployments. See Cross-origin requests for format, wildcards, and verification.

AWS_BEARER_TOKEN_BEDROCK

Read by the AWS SDK as a Bedrock API key. It takes priority over assumedRole and credentials, so leave it unset unless it holds the intended identity. See Assumed role and host credentials.

CS_CONFIG_PATH

Path, inside the container, to a JSON configuration file. When set, the service reads its options from the file and ignores option environment variables. See Configuration file.

DATABASE_DATABASE

Yes

Database name (ai_service is the convention).

DATABASE_DRIVER

Yes

mysql or postgres.

DATABASE_HOST

Yes

Database hostname or IP.

DATABASE_PASSWORD

Yes

Database password.

DATABASE_PORT

3306 (MySQL) / 5432 (PostgreSQL)

Database port.

DATABASE_SCHEMA

PostgreSQL only

cs-on-premises

PostgreSQL schema name. Pre-create or set to public.

DATABASE_SSL_CA

Path to CA cert for database Transport Layer Security (TLS).

DATABASE_SSL_CERT

Path to client cert.

DATABASE_SSL_KEY

Path to client key.

DATABASE_USER

Yes

Database user.

ENABLE_METRIC_LOGS

false

Emit JSON request logs to stdout.

ENVIRONMENTS_MANAGEMENT_SECRET_KEY

Yes

Management Panel login secret. Not used to sign user JSON Web Tokens (JWTs).

GOOGLE_APPLICATION_CREDENTIALS

In image version 1.2.0 and later, the Google auth library reads the service account key file that this variable points to, as part of the Application Default Credentials for Vertex AI. Ignored in earlier image versions. See Impersonation and host credentials.

GOOGLE_VERTEX_LOCATION

Alternative to the location field of a Vertex AI provider. See Google Vertex AI.

GOOGLE_VERTEX_PROJECT

Alternative to the project field of a Vertex AI provider. See Google Vertex AI.

GUARDRAILS

JSON object; per-operation guardrail configuration. Guardrails are off by default. See Guardrails.

HOOKS

JSON object; hook endpoint, enabled hook events, and signing configuration. See Hooks.

LANGFUSE_BASE_URL

https://cloud.langfuse.com

Self-hosted Langfuse URL.

LANGFUSE_DEBUG

Verbose Langfuse logging.

LANGFUSE_PUBLIC_KEY

If using Langfuse

Langfuse public key.

LANGFUSE_SECRET_KEY

If using Langfuse

Langfuse secret key.

LICENSE_KEY

Yes

AI service license key (long string from Tiny). The same key is shared across all replicas of a deployment — no per-pod licensing is required.

LLM_TELEMETRY_ENABLED

false

Records spans for AI operations. See Observability.

LLM_TIMEOUT_MS

180000

Per-request large language model (LLM) timeout in ms. Raise for large self-hosted models.

LOG_LEVEL

40

Lowest log level written to the container output. See Log levels.

MCP_OAUTH_CALLBACK_URL

If using MCP OAuth

URL of the OAuth callback page hosted by the integrating web application. Used as the OAuth redirect_uri for all OAuth-enabled MCP servers (unless overridden per server). See OAuth 2.0 authentication.

MCP_SERVERS

JSON object; Model Context Protocol (MCP) server configuration, keyed by server name. Supports static-token and OAuth 2.0 authentication per server, an environment allowlist, and connection pool limits. See MCP integration.

MODELS

Yes (Azure, Bedrock, Vertex, openai-compatible); recommended for all providers

JSON array defining exposed models. Required for Azure, Bedrock, Vertex, and openai-compatible providers, which have no default model list. Recommended for OpenAI, Anthropic, and Google direct, which come with a default model list that MODELS replaces. See Defining the model list.

MODERATION

JSON object; content moderation configuration (turn the check on or off, and choose the moderation provider). A custom moderation endpoint requires image version 1.1.0 or later. See Content moderation.

OTEL_DEBUG

Verbose OpenTelemetry Protocol (OTLP) diagnostic logging.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

If using OTLP export

OTLP traces endpoint URL. The Langfuse export does not need it.

OTEL_TRACES_SAMPLER_ARG

1.0

OTLP sampling rate (0.0 to 1.0).

PROVIDERS

Yes

JSON object; LLM provider configuration. See LLM providers.

REDIS_CLUSTER_NODES

Comma-separated host:port[:password] for Redis Cluster mode.

REDIS_DB

Redis database number.

REDIS_HOST

Yes

Redis hostname.

REDIS_IP_FAMILY

Set to 6 for IPv6.

REDIS_PASSWORD

Redis password.

REDIS_PORT

6379

Redis port.

REDIS_TLS_CA

Path to CA cert for Redis TLS.

REDIS_TLS_CERT

Path to Redis client cert.

REDIS_TLS_ENABLE

false

Enable Redis TLS.

REDIS_TLS_KEY

Path to Redis client key.

REDIS_USER

Redis username (ACL).

STORAGE_ACCESS_KEY_ID

If using S3

S3 access key.

STORAGE_ACCOUNT_KEY

If using Azure Blob

Azure storage account key.

STORAGE_ACCOUNT_NAME

If using Azure Blob

Azure storage account name.

STORAGE_BUCKET

If using S3

S3 bucket name.

STORAGE_CONTAINER

If using Azure Blob

Azure container name.

STORAGE_DRIVER

Yes

database, filesystem, s3, or azure.

STORAGE_ENDPOINT

Custom endpoint (S3-compatible or Azure-compatible).

STORAGE_LOCATION

If using filesystem

Mount point for filesystem storage. Must be writable by the container user.

STORAGE_REGION

If using S3

S3 region.

STORAGE_SECRET_ACCESS_KEY

If using S3

S3 secret access key.

WEBRESOURCES_ENABLED

false

Enable web scraping endpoint forwarding. See Web scraping.

WEBRESOURCES_ENDPOINT

If web resources enabled

Scraper URL.

WEBRESOURCES_REQUEST_TIMEOUT

Scraper request timeout in ms.

WEBSEARCH_ENABLED

false

Enable web search forwarding. See Web search.

WEBSEARCH_ENDPOINT

If web search enabled

Search URL.

WEBSEARCH_HEADERS

Colon-CSV format (Header-Name: value, Another: value). Extra headers sent to the search endpoint. Do not use JSON — see Web search.

WEBSEARCH_REQUEST_TIMEOUT

Search request timeout in ms.

Configuration file

The service can read its options from a JSON file instead of from environment variables. Set CS_CONFIG_PATH to the path of the file inside the container, and mount the file at that path:

docker run --init -d -p 8000:8000 \
  --name ai-service \
  -v /path/to/ai-service-config.json:/app/config.json:ro \
  -e CS_CONFIG_PATH='/app/config.json' \
  registry.containers.tiny.cloud/ai-service-tiny:<version>

The file holds one flat JSON object. Each key is an option name, and option names are case-insensitive, so license_key in the file and LICENSE_KEY as an environment variable name the same option. In the file, write options that take JSON, such as providers, models, and mcp_servers, as JSON values rather than as JSON strings:

{
  "license_key": "<license-key>",
  "environments_management_secret_key": "<management-secret>",
  "database_driver": "mysql",
  "database_host": "<database-host>",
  "database_user": "<database-user>",
  "database_password": "<database-password>",
  "database_database": "ai_service",
  "redis_host": "<redis-host>",
  "storage_driver": "database",
  "providers": {
    "openai": { "type": "openai", "apiKeys": ["<openai-api-key>"] }
  },
  "models": [
    {
      "id": "gpt-4.1",
      "provider": "openai",
      "description": "OpenAI GPT-4.1",
      "features": ["conversations", "reviews", "actions"]
    }
  ]
}

The file and the environment variables are mutually exclusive. When CS_CONFIG_PATH is set, the service reads options only from the file and ignores option environment variables. There is no default file path. The exceptions are the telemetry variables, which start with OTEL_ or LANGFUSE_, and the variables that the provider SDKs read themselves, such as AWS_BEARER_TOKEN_BEDROCK, the AWS credential chain variables, and GOOGLE_APPLICATION_CREDENTIALS. The service and the SDKs read these from the process environment even when the rest of the configuration is in a file.

Two options behave differently in the file:

llm_telemetry_enabled is an ordinary option, so it can be set in the file, unlike the OTEL_ and LANGFUSE_ variables.
websearch_headers accepts either a JSON object, for example {"Authorization": "Bearer <token>"}, or the same colon-CSV string that the WEBSEARCH_HEADERS environment variable requires.

Complete `docker run` reference

A single command with all required environment variables for a minimal production deployment (MySQL, OpenAI, S3 storage):

docker run --init -d -p 8000:8000 \
  --name ai-service \
  -e LICENSE_KEY='<license-key>' \
  -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY='<management-secret>' \
  -e DATABASE_DRIVER='mysql' \
  -e DATABASE_HOST='<database-host>' \
  -e DATABASE_PORT='3306' \
  -e DATABASE_USER='<database-user>' \
  -e DATABASE_PASSWORD='<database-password>' \
  -e DATABASE_DATABASE='ai_service' \
  -e REDIS_HOST='<redis-host>' \
  -e REDIS_PORT='6379' \
  -e PROVIDERS='{"openai":{"type":"openai","apiKeys":["<openai-api-key>"]}}' \
  -e MODELS='[{"id":"gpt-4.1","provider":"openai","name":"GPT-4.1","description":"OpenAI GPT-4.1","features":["conversations","reviews","actions"]}]' \
  -e STORAGE_DRIVER='s3' \
  -e STORAGE_BUCKET='<s3-bucket-name>' \
  -e STORAGE_REGION='<aws-region>' \
  -e STORAGE_ACCESS_KEY_ID='<s3-access-key>' \
  -e STORAGE_SECRET_ACCESS_KEY='<s3-secret-key>' \
  -e ALLOWED_ORIGINS='https://<your-app-domain>' \
  -e ENABLE_METRIC_LOGS='true' \
  registry.containers.tiny.cloud/ai-service-tiny:<version>

For PostgreSQL, change DATABASE_DRIVER to 'postgres' and add -e DATABASE_SCHEMA='cs-on-premises' (or 'public'). For Redis authentication, add -e REDIS_PASSWORD='<redis-password>'. For Redis TLS, add -e REDIS_TLS_ENABLE='true'.

API endpoint reference

Method Path Auth Description

GET

/health

None

Liveness probe. Returns {"serviceName":"on-premises-http","uptime":<seconds>}. Not metric-logged.

GET

/docs/

None

Redirects (HTTP 301) to /v1/api/docs.

GET

/v1/api/docs

None

ReDoc-rendered API documentation.

GET

/v1/api/doc.json

None

OpenAPI 3 JSON spec.

GET

/panel/

Management secret (login form)

Management Panel UI. Sign in with ENVIRONMENTS_MANAGEMENT_SECRET_KEY through the browser login form.

GET

/v1/models/1

JWT

List available models for the current token. The compatibility version literal 1 is the only accepted value. Other values, such as v1, v2, and latest, return 400 Bad Request.

POST

/v1/conversations

JWT

Create a conversation. Body must include client-supplied id.

GET

/v1/conversations

JWT

List conversations for the current sub.

GET

/v1/conversations/{id}

JWT

Read one conversation.

POST

/v1/conversations/{id}/messages

JWT

Send a message. Returns Server-Sent Events (SSE) stream.

POST

/v1/conversations/{id}/web-resources

JWT

Fetch a web page through the configured scrape endpoint. Body: {"url":"https://…"}. Returns 201 on success, 422 on scrape failure. Requires WEBRESOURCES_ENABLED='true'. See Web scraping.

GET

/v1/conversations/{id}/web-resources

JWT

List the web resources fetched for a conversation.

DELETE

/v1/conversations/{id}/web-resources/{webResourceId}

JWT

Remove a web resource from a conversation.

POST

/v1/conversations/{id}/files

JWT

Upload a file to a conversation as multipart/form-data.

DELETE

/v1/conversations/{id}/files/{fileId}

JWT

Remove a file from a conversation.

POST

/v1/conversations/{id}/documents

JWT

Add a document to a conversation.

GET

/v1/conversations/{id}/documents/{documentId}

JWT

Read one conversation document.

DELETE

/v1/conversations/{id}

JWT

Delete a conversation.

POST

/v1/actions/system/{actionName}/calls

JWT

Run a built-in quick action, for example fix-grammar. Body shape: {"content":[{"type":"text","content":"…"}]} with exactly one text part (no modelId). Returns an SSE stream.

POST

/v1/reviews/system/{reviewName}/calls

JWT

Run a built-in review, for example correctness. Returns an SSE stream. For the content format, see the API reference.

POST

/v1/actions/custom/calls

JWT

Run a custom action with a prompt and a model. Returns an SSE stream.

POST

/v1/reviews/custom/calls

JWT

Run a custom review with a prompt and a model. Returns an SSE stream.

GET

/v1/mcp/oauth/status

JWT

Connection status for all OAuth-enabled MCP servers. See OAuth REST endpoints.

POST

/v1/mcp/oauth/{serverName}/initialize

JWT

Start the OAuth authorization flow.

POST

/v1/mcp/oauth/{serverName}/complete

JWT

Complete the OAuth flow with the authorization code.

DELETE

/v1/mcp/oauth/{serverName}

JWT

Revoke the OAuth connection for the calling user.

GET, POST, PUT, DELETE

/v1/admin/mcp-servers and /v1/admin/mcp-servers/{mcpServerName}

JWT with ai:admin

List, register, read, update, and remove the MCP servers of the environment in the token. Image version 1.2.0 and later. See MCP server admin API, and for each operation, see MCP Server Admin in the API reference.

The OAuth endpoints are available only when at least one MCP server has an oauth block configured. The interactive API documentation at /v1/api/docs may not include these endpoints; they are documented in the MCP OAuth section.

Environment management (create, read, update, delete) is handled through the Management Panel UI at /panel/.

Server-Sent Events reference

The message endpoint returns Content-Type: text/event-stream. Events use named types. The following table lists the main events. For every event and its payload, see the API reference.

Event Payload shape Meaning

message-metadata

{"messageId":"…"}

Sent once at the start of each message.

text-delta

{"textDelta":"…"}

Incremental text fragment. The editor concatenates these.

mcp-tool-result

{"toolName":"...","result":"...","success":true}

Emitted when an MCP tool call completes. result is a string.

error

{"message":"…","cause":{…}}

Provider error. HTTP status remains 200; the error is in-stream.

There is no end-of-stream event. The stream ends when the service closes the response.

Healthy stream example:

event: message-metadata
data: {"messageId":"abc123"}

event: text-delta
data: {"textDelta":"Hello "}

event: text-delta
data: {"textDelta":"there!"}

Error stream example:

event: message-metadata
data: {"messageId":"abc123"}

event: error
data: {"message":"Incorrect API key provided","cause":{"providerStatusCode":401}}

Browser client parsing notes:

Each event is two lines: event: <name> and data: <json>, separated from the next event by a blank line.
data is always valid JSON.
Unknown event types carry informational payloads and can be ignored for forward compatibility.
text-delta carries the visible reply text, and modification-delta carries the text of a proposed document modification.

The action and review endpoints also return SSE streams, with their own events. See the API reference for actions and reviews.

Error code reference

Error codes returned in HTTP 4xx responses and inside SSE event: error payloads.

Every error response carries a traceId. See Tracing a failed request.

Code Origin Likely cause Fix

invalid-jwt-signature

JWT verifier

Wrong API Secret, or used ENVIRONMENTS_MANAGEMENT_SECRET_KEY, or signed with RS256

Re-sign with HS256 using the correct API Secret

invalid-jwt-payload

JWT verifier

aud does not match a real Environment ID, OR environment created through raw API not Panel UI

Re-copy env ID from /panel/, or recreate the env through the Panel UI

invalid-jwt

JWT verifier

Token >60 s past exp

Issue tokens with shorter lifetime and refresh sooner

Environment not found

AI runtime

Same as invalid-jwt-payload second sub-cause

Recreate env through Panel UI

missing-permissions

Permission checker

auth.ai.permissions array does not cover the requested action

Add the missing permission string

invalid-request-data

Input validator

Field validation failed (most commonly the 100,000 char prompt cap)

Fix the request body. See error message

environment-not-found

AI runtime

Same as Environment not found. The editor displays this error as Invalid API key provided in JWT token (aud) claim.

Recreate through Panel UI

conversation in use

Conversation runtime

Stream-abort left stale state

Start a new conversation

conversation does not exist

Conversation runtime

Follow-up to conversation in use

Start a new conversation

NoValidApiKeysFoundError (HTTP 500)

Bedrock / Vertex adapter

No credentials that the service can use

See AWS Bedrock or Google Vertex AI

AccessDeniedException

Bedrock

Missing model access or IAM permissions

Enable Bedrock model access; attach the IAM policy from LLM providers

INVALID_PAYMENT_INSTRUMENT

Bedrock

Anthropic on Bedrock without Marketplace subscription

Subscribe through AWS Marketplace

ValidationException

Bedrock

Wrong model ID format (regional instead of cross-region)

Use the inference profile ID for recent Claude models

DeploymentNotFound

Azure

MODELS[].id does not match Azure deployment name

Set MODELS[].id to the exact deployment name

invalid_grant

Vertex

Mangled private_key newlines

Build PROVIDERS from json.dumps() of the SA key

SERVICE_DISABLED

Vertex

aiplatform.googleapis.com not enabled

gcloud services enable aiplatform.googleapis.com

API_KEY_INVALID

Vertex

Account-bound API key blocked by org policy

Grant policy exception

Incorrect API key provided

OpenAI / Anthropic / Google

Bad API key

Update PROVIDERS and --force-recreate

Wrong license key.

AI service startup

Truncated or whitespace-padded license key

Re-paste as a single line

License error with a reason

License check

In image version 1.2.0 and later, a license error in an API response states its reason

Act on the stated reason, or contact Tiny support with it

content-rejected (HTTP 422)

Guardrails

A guardrail classified the content as an attack, such as prompt injection, or the content matched a blocklist phrase

Review the content, or adjust the guardrail configuration. See Guardrails

unsafe-content-detected (HTTP 422)

Content moderation

The moderation provider flagged the prompt, an image uploaded to a conversation, or a file uploaded to the context library. data.flaggedCategories lists the categories

Change the content, or adjust the moderation configuration. See Content moderation

hook-failed (HTTP 502)

Hooks

The configured hook endpoint did not complete successfully

Check the hook endpoint logs using the requestId value. See Hooks

hook-timeout (HTTP 504)

Hooks

The configured hook endpoint did not respond in time

Check the hook endpoint availability and the hook timeout settings. See Hooks

Known limits

Limit Value Notes

Maximum prompt length

100,000 characters

Hard limit enforced by the service. Requests exceeding this return invalid-request-data. Summarize or shorten source content before it exceeds this threshold.

Conversation create

Client-supplied id required

The plugin auto-generates tiny-<uuid>. Raw API callers must supply a unique id in the create body.

Stream-abort recovery

Stop button leaves stale state

The next message returns 409 conversation in use then 404 conversation does not exist. Recovery: start a new conversation or reload.

Built-in rate limiting

None

Front the service with nginx limit_req or ALB rate-limit rules. See Rate limiting.

File support (OpenAI-compatible providers)

Images only (image/*)

PDFs, text, and Office files are not forwarded to OpenAI-compatible providers. Use a non-OpenAI-compatible provider for non-image file attachments.

MCP tool availability

Conversations, and Document Processing in image version 1.1.0 and later

MCP tools are not available in reviews or quick actions. Document Processing skips OAuth-enabled servers.

MCP authentication

Static token or OAuth 2.0, configured independently for each server

Static tokens use the headers field (shared across all users, fixed at deploy time). Per-user authentication is supported through OAuth 2.0 (Authorization Code with PKCE). See OAuth 2.0 authentication.

PostgreSQL default schema

cs-on-premises (with hyphen)

Pre-create with CREATE SCHEMA "cs-on-premises"; or set DATABASE_SCHEMA=public.

/v1/models/{compatibilityVersion}

Only accepts 1

Values such as v1, v2, or latest return 400.

Environment creation through raw API

Not supported

Always create environments through the Management Panel UI.

Bedrock credentials

Inline only, in image versions earlier than 1.2.0

See Assumed role and host credentials.

Vertex credentials

Inline only, in image versions earlier than 1.2.0

See Impersonation and host credentials.

Azure MODELS[].id

Must equal deployment name

There is no separate deploymentName field. The ID is the deployment name. Start the deployment name with the ID of the OpenAI model it serves: the service reads that prefix to choose the request options for the model.

OpenAI-compatible baseUrl

Must include /v1 suffix

Omitting it produces a "Not Found" SSE error.

TinyMCE AI on-premises reference

Environment variable reference

Configuration file

Complete docker run reference

API endpoint reference

Server-Sent Events reference

Error code reference

Known limits

Complete `docker run` reference